ThinkGeo Core Architecture Guide¶

MapView
└── Overlays  (ordered collection)
    ├── LayerOverlay          ← contains vector/raster Feature Layers
    │   └── Layers  (ordered collection)
    │       └── FeatureLayer  ← wraps a FeatureSource
    │           └── FeatureSource  ← actual data access (shapefile, SQL, in-memory…)
    │               └── ProjectionConverter  ← optional on-the-fly reprojection
    └── ThinkGeoCloudVectorMapsOverlay  ← background tile service (a special overlay)

mapView.MapUnit    = GeographyUnit.Meter;
mapView.CenterPoint = new PointShape(-10777290, 3908740); // Spherical Mercator
mapView.CurrentScale = 9400;

// Background first
var cloudOverlay = new ThinkGeoCloudVectorMapsOverlay
{
    ClientId     = "your-client-id",
    ClientSecret = "your-client-secret",
    MapType      = ThinkGeoCloudVectorMapsMapType.Light,
    TileCache    = new FileRasterTileCache(@".\cache", "thinkgeo_light")
};
mapView.Overlays.Add(cloudOverlay);

// Your data on top
var myOverlay = new LayerOverlay();
mapView.Overlays.Add("myData", myOverlay);

var hotelsLayer = new ShapeFileFeatureLayer(@"./Data/Hotels.shp");
myOverlay.Layers.Add("hotels", hotelsLayer);

// Attach a projection converter so data in EPSG:2276 (Texas State Plane)
// gets reprojected on the fly to the map's EPSG:3857
hotelsLayer.FeatureSource.ProjectionConverter = new ProjectionConverter(2276, 3857);

hotelsLayer.Open();
var features = hotelsLayer.QueryTools.GetAllFeatures(ReturningColumnsType.AllColumns);
hotelsLayer.Close();

┌─────────────────────────────────────────┐
│  5. Interaction overlays                │  EditOverlay, PopupOverlay, MeasureOverlay
│  4. Your vector feature overlays        │  LayerOverlay containing FeatureLayers
│  3. Your raster data overlays           │  LayerOverlay with WmsRasterLayer etc.
│  2. Tile basemap overlay                │  ThinkGeoCloudVectorMapsOverlay
│  1. MapView canvas                      │  MapView (sets MapUnit, scale, center)
└─────────────────────────────────────────┘

RefreshAsync()
  │
  ├─► For each Overlay (in order):
  │     │
  │     └─► Overlay.DrawAsync(extent, canvas)
  │           │
  │           └─► [LayerOverlay] For each Layer:
  │                 │
  │                 ├─► Layer.IsDrawingNeeded(currentScale)   ← zoom filter
  │                 │
  │                 └─► Layer.DrawCore(GeoCanvas, labelsInAllLayers)
  │                       │
  │                       └─► FeatureSource.GetFeaturesForDrawing(boundingBox, w, h, columns)
  │                             │
  │                             └─► [For each Feature]:
  │                                   ZoomLevel.Draw(canvas, feature, labels)
  │                                     └─► Style.Draw(feature, canvas)
  │
  └─► Composite all overlay bitmaps → screen

// Data is in Texas State Plane South (feet), map is in Web Mercator
layer.FeatureSource.ProjectionConverter = new ProjectionConverter(2276, 3857);

layer.Open(); // opens both FeatureSource and ProjectionConverter

// Create the style
var circleStyle = new PointStyle(PointSymbolType.Circle, 12,
                                  GeoBrushes.Blue,
                                  new GeoPen(GeoBrushes.White, 2));

// Attach to ZoomLevel01 (most zoomed in)
layer.ZoomLevelSet.ZoomLevel01.CustomStyles.Clear();
layer.ZoomLevelSet.ZoomLevel01.CustomStyles.Add(circleStyle);

// Cascade this style to apply at all zoom levels
layer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;

// Icon from file
var iconStyle = new PointStyle(new GeoImage(@"./Resources/hotel_icon.png"))
{
    ImageScale = 0.25
};

// Font glyph
var glyphStyle = new PointStyle(new GeoFont("Verdana", 16, DrawingFontStyles.Bold), "@", GeoBrushes.Black)
{
    Mask     = new AreaStyle(GeoBrushes.White),
    MaskType = MaskType.Circle
};

<!-- XAML declaration (single-tile mode) -->
<tgWpf:MapView x:Name="MapView"
               MapUnit="Meter"
               Loaded="MapView_Loaded"
               DefaultOverlaysRenderSequenceType="Concurrent">
    <tgWpf:MapView.Overlays>
        <tgWpf:LayerOverlay TileType="SingleTile">
            <tgWpf:LayerOverlay.Layers>
                <tgCore:ShapeFileFeatureLayer ShapePathFilename="Data/Countries.shp"/>
            </tgWpf:LayerOverlay.Layers>
        </tgWpf:LayerOverlay>
    </tgWpf:MapView.Overlays>
</tgWpf:MapView>

private void Form_Load(object sender, EventArgs e)
{
    mapView1.MapUnit = GeographyUnit.Meter;
    // ... same pattern as WPF
}

<tgMaui:MapView x:Name="MapView"
                MapUnit="Meter"
                DefaultOverlaysRenderSequenceType="Concurrent"
                SizeChanged="MapView_OnSizeChanged">
    <tgMaui:MapView.Overlays>
        <tgMaui:LayerOverlay TileType="SingleTile">
            ...
        </tgMaui:LayerOverlay>
    </tgMaui:MapView.Overlays>
</tgMaui:MapView>

public void Register(ThinkGeoWebServerOptions options)
{
    var rasterLayers = new[]
    {
        new RasterLayerDefinition
        {
            Name = "coyoteSightings",
            CreateLayer = () =>
            {
                var layer = new SqlServerFeatureLayer(connectionString, "frisco_coyote_sightings", "id")
                {
                    FeatureSource = { ProjectionConverter = new ProjectionConverter(2276, 3857) }
                };
                layer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle =
                    new PointStyle(PointSymbolType.Circle, 12, GeoBrushes.Black, new GeoPen(GeoColors.White, 1));
                layer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
                return layer;
            }
        }
    };

    options.AddWmsEndpoint(rasterLayers);
    options.AddXyzEndpoint(rasterLayers);
    options.AddWfsEndpoint(vectorLayers);
}

private void MapView_Loaded(object sender, RoutedEventArgs e)
{
    // 1. Set the map's CRS
    MapView.MapUnit = GeographyUnit.Meter;

    // 2. Add a basemap overlay
    MapView.Overlays.Add(new ThinkGeoCloudVectorMapsOverlay
    {
        ClientId     = "your-client-id",
        ClientSecret = "your-client-secret",
        MapType      = ThinkGeoCloudVectorMapsMapType.Light,
        TileCache    = new FileRasterTileCache(@".\cache", "basemap")
    });

    // 3. Create a layer and reproject it to match the map
    var layer = new ShapeFileFeatureLayer(@"./Data/Hotels.shp");
    layer.FeatureSource.ProjectionConverter = new ProjectionConverter(2276, 3857);

    // 4. Style the layer
    layer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle =
        new PointStyle(PointSymbolType.Circle, 12, GeoBrushes.Blue, new GeoPen(GeoBrushes.White, 2));
    layer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;

    // 5. Add to overlay, add overlay to map
    var overlay = new LayerOverlay();
    overlay.Layers.Add("hotels", layer);
    MapView.Overlays.Add("hotels", overlay);

    // 6. Set initial view and refresh
    MapView.CenterPoint = new PointShape(-10777290, 3908740);
    MapView.CurrentScale = 9400;
    _ = MapView.RefreshAsync();
}

var memoryLayer = new InMemoryFeatureLayer();
memoryLayer.InternalFeatures.Add(new Feature(new PointShape(-10777290, 3908740)));
memoryLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle =
    PointStyle.CreateSimpleCircleStyle(GeoColors.Red, 12);
memoryLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;

layer.Open();
try
{
    var features = layer.QueryTools.GetFeaturesByColumnValue(
        "Category", "Hotel",
        ReturningColumnsType.AllColumns);
    // features is IEnumerable<Feature>
}
finally
{
    layer.Close();
}

var overlay = (LayerOverlay)MapView.Overlays["hotels"];
var hotelsLayer = (ShapeFileFeatureLayer)overlay.Layers["hotels"];

// Refresh a single overlay (fast — only that overlay re-renders)
_ = layerOverlay.RefreshAsync();

// Refresh everything
_ = MapView.RefreshAsync();

var overlay = new LayerOverlay
{
    TileCache = new FileRasterTileCache(@".\cache", "myOverlayCacheKey"),
    TileType  = TileType.MultipleTiles
};

// Wrong
layer.FeatureSource.ProjectionConverter.ConvertToInternalProjection(rect);

// Right
layer.Open(); // opens FeatureSource + ProjectionConverter
var features = layer.QueryTools.GetAllFeatures(ReturningColumnsType.AllColumns);
layer.Close();

// Request all columns
layer.QueryTools.GetAllFeatures(ReturningColumnsType.AllColumns);

// Or request specific columns
layer.QueryTools.GetAllFeatures(new[] { "Name", "Category" });

var layerOverlay = new LayerOverlay
{
    ThrowingExceptionMode = ThrowingExceptionMode.ThrowException
};

layerOverlay.ThrowingException += (sender, e) =>
{
    Debug.WriteLine($"Drawing error: {e.Exception?.Message}");
    e.Handled = true; // swallow — don't rethrow
};

protected override void DrawExceptionCore(GeoCanvas canvas, Exception e)
{
    // draw a custom error indicator instead of the default pink tile
    canvas.DrawArea(canvas.CurrentWorldExtent, GeoBrushes.LightOrange, DrawingLevel.LevelOne);
    canvas.DrawText("Layer error", new GeoFont("Arial", 10), GeoBrushes.Red,
        new[] { new ScreenPointF(canvas.Width / 2, canvas.Height / 2) }, DrawingLevel.LabelLevel);
}

<!-- XAML -->
<tgMaui:MapView x:Name="MapView" SizeChanged="MapView_OnSizeChanged" ...>

private bool _initialized;

private async void MapView_OnSizeChanged(object sender, EventArgs e)
{
    if (_initialized) return;
    _initialized = true;

    MapView.MapUnit = GeographyUnit.Meter;
    // ... add overlays, layers, styles ...
    MapView.CenterPoint = new PointShape(-10777290, 3908740);
    MapView.MapScale = 200000;

    await MapView.RefreshAsync();
}

ThinkGeo.Core
├── MapView                        [UI — platform-specific subclass]
│
├── Overlay (abstract)
│   ├── LayerOverlay
│   ├── ThinkGeoCloudVectorMapsOverlay
│   ├── BingMapsOverlay
│   ├── EditOverlay
│   └── PopupOverlay
│
├── Layer (abstract)
│   ├── FeatureLayer (abstract)
│   │   ├── ShapeFileFeatureLayer
│   │   ├── SqlServerFeatureLayer
│   │   ├── InMemoryFeatureLayer
│   │   ├── GeoJsonFeatureLayer
│   │   ├── MsSqliteFeatureLayer
│   │   └── (+ many more)
│   └── (raster layers)
│       ├── GeoImageLayer
│       ├── WmsRasterLayer
│       └── GeoTiffRasterLayer
│
├── FeatureSource (abstract)       [inside FeatureLayer]
│   ├── ShapeFileFeatureSource
│   ├── SqlServerFeatureSource
│   ├── InMemoryFeatureSource
│   └── (+ more)
│
├── Style (abstract)
│   ├── PointStyle
│   ├── LineStyle
│   ├── AreaStyle
│   ├── TextStyle
│   ├── ValueStyle
│   ├── ClassBreakStyle
│   ├── ClusterPointStyle
│   ├── HeatStyle
│   └── FilterStyle
│
├── ZoomLevel / ZoomLevelSet
├── Feature
├── ProjectionConverter
├── GeoCanvas (abstract)           [platform-specific subclass]
├── GeoBrush / GeoPen / GeoFont
└── Shapes
    ├── PointShape
    ├── LineShape / MultilineShape
    ├── PolygonShape / MultipolygonShape
    └── RectangleShape