Shiny Spatial

Shiny.Spatial Skill

You are an expert in Shiny.Spatial, a dependency-free, cross-platform .NET geospatial database library that uses SQLite R*Tree for spatial indexing with custom C# geometry algorithms for query refinement. No SpatiaLite, no NetTopologySuite — only SQLite via Microsoft.Data.Sqlite.

When to Use This Skill

Invoke this skill when the user wants to:

• Create or query a spatial database with geospatial data
• Store and retrieve geometry objects (Points, LineStrings, Polygons, Multi*, GeometryCollection)
• Perform spatial queries: distance, intersection, containment, bounding box
• Use the fluent query builder with property filters and distance ordering
• Work with WKB (Well-Known Binary) serialization
• Use pre-built databases (US/Canadian states, provinces, cities)
• Build location-aware applications on iOS, Android, or any .NET platform
• Set up GPS-driven geofence monitoring with enter/exit events
• Implement an ISpatialGeofenceDelegate for region change handling
• Configure ISpatialGeofenceManager to start/stop geofence detection

Library Overview

Repository: https://github.com/shinyorg/geospatialdb Namespace: Shiny.Spatial AOT compatible and trimmable.

Target Frameworks

Dependencies

• Microsoft.Data.Sqlite — brings SQLitePCLRaw.bundle_e_sqlite3 with R*Tree enabled
• Shiny.Locations — geofencing package only (background GPS)

Setup

Install NuGet Package

dotnet add package Shiny.Spatial

Architecture

Two-Pass Query Pipeline

1. R*Tree bounding box filter (SQL, O(log n)) — eliminates most candidates using the SQLite R*Tree index
2. C# geometry refinement — exact Contains/Intersects/WithinDistance checks on survivors

SQLite Schema

Each spatial table creates a single R*Tree virtual table with auxiliary columns:

CREATE VIRTUAL TABLE {name}_rtree USING rtree(
    id, min_x, max_x, min_y, max_y,
    +geometry BLOB,              -- WKB-encoded geometry
    +prop_{name} {type}, ...     -- user-defined property columns
);

Metadata is tracked in __spatial_meta and __spatial_columns tables.

Geometry Types

All geometry classes are immutable and sealed, extending the abstract Geometry base class. Namespace: Shiny.Spatial.Geometry.

Creating Geometries

using Shiny.Spatial.Geometry;

// Point
var point = new Point(-104.99, 39.74);

// LineString (minimum 2 coordinates)
var line = new LineString(new[]
{
    new Coordinate(-104.99, 39.74),
    new Coordinate(-104.82, 38.83)
});

// Polygon (exterior ring, closed — first == last coordinate)
var polygon = new Polygon(new[]
{
    new Coordinate(-109.05, 37.0), new Coordinate(-102.05, 37.0),
    new Coordinate(-102.05, 41.0), new Coordinate(-109.05, 41.0),
    new Coordinate(-109.05, 37.0)
});

// Polygon with holes
var polygonWithHole = new Polygon(
    exteriorRing: new[] { /* outer coords */ },
    interiorRings: new[] { new[] { /* hole coords */ } }
);

// Multi types
var multiPoint = new MultiPoint(new[] { point1, point2 });
var multiLine = new MultiLineString(new[] { line1, line2 });
var multiPoly = new MultiPolygon(new[] { polygon1, polygon2 });
var collection = new GeometryCollection(new Geometry[] { point, line, polygon });

Database API

SpatialDatabase (IDisposable)

using Shiny.Spatial.Database;

var db = new SpatialDatabase("path.db");    // file-backed
var db = new SpatialDatabase(":memory:");   // in-memory

SpatialTable table = db.CreateTable(name, coordinateSystem, properties...);
SpatialTable table = db.GetTable(name);
bool exists       = db.TableExists(name);
db.DropTable(name);
db.Dispose();

Creating Tables with Properties

var table = db.CreateTable("cities", CoordinateSystem.Wgs84,
    new PropertyDefinition("name", PropertyType.Text),
    new PropertyDefinition("population", PropertyType.Integer),
    new PropertyDefinition("area", PropertyType.Real));

SpatialTable CRUD

SpatialFeature

var feature = new SpatialFeature(new Point(-104.99, 39.74))
{
    Properties = { ["name"] = "Denver", ["population"] = 715000L }
};

long id = feature.Id;              // set after Insert
Geometry geom = feature.Geometry;
Dictionary<string, object?> props = feature.Properties;

Spatial Queries

// Distance query
var nearby = table.FindWithinDistance(
    new Coordinate(-104.99, 39.74),
    distanceMeters: 150_000
);

// Shape intersection
var inState = table.FindIntersecting(coloradoPolygon);

// Bounding box
var envelope = new Envelope(-110, -100, 35, 42);
var inBox = table.FindInEnvelope(envelope);

Fluent Query Builder

var center = new Coordinate(-104.99, 39.74);

var results = table.Query()
    .WithinDistance(center, 150_000)
    .WhereProperty("population", ">", 200000L)
    .OrderByDistance(center)
    .Limit(10)
    .ToList();

int count = table.Query().InEnvelope(envelope).Count();
var first = table.Query().WithinDistance(center, 1000).FirstOrDefault();

Coordinate vs geometry parameters: WithinDistance/OrderByDistance (and FindWithinDistance) take a Coordinate; the geometry methods Intersecting/ContainedBy (and FindIntersecting/FindContainedBy) take a Geometry. A Coordinate implicitly converts to a Point, so you can pass a bare lon/lat to the geometry methods directly — e.g. query.Intersecting(new Coordinate(lon, lat)) — without writing new Point(...).

Algorithms

Namespace: Shiny.Spatial.Algorithms

WKB Serialization

using Shiny.Spatial.Serialization;

byte[] wkb = WkbWriter.Write(geometry);
Geometry restored = WkbReader.Read(wkb);

Full roundtrip support for all geometry types using the WKB (Well-Known Binary) format.

Pre-Built Databases

Located in databases/:

All use CoordinateSystem.Wgs84 (longitude/latitude).

using var db = new SpatialDatabase("databases/us-states.db");
var states = db.GetTable("states");

// Find which state Denver is in
var denver = new Point(-104.99, 39.74);
var results = states.FindIntersecting(denver);
// results[0].Properties["name"] == "Colorado"

Coordinate Systems

Code Generation Instructions

When generating code with Shiny.Spatial:

1. Database Lifecycle

• Always wrap SpatialDatabase in a using statement or IDisposable pattern
• Use :memory: for tests, file paths for production
• Call CreateTable for new tables, GetTable for existing tables

2. Coordinate System Selection

• Use CoordinateSystem.Wgs84 for real-world GPS latitude/longitude data
• Use CoordinateSystem.Cartesian for projected or flat coordinate systems
• WGS84 uses Haversine distance (meters), Cartesian uses Euclidean distance

3. Property Types

• Use PropertyType.Text for strings
• Use PropertyType.Integer for long values — always use L suffix (e.g., 715000L)
• Use PropertyType.Real for doubles
• Use PropertyType.Blob for binary data

4. Query Strategy

• For simple spatial queries, use the direct methods (FindWithinDistance, FindIntersecting, etc.)
• For combined spatial + property filtering, use the fluent Query() builder
• Always apply spatial filters first (they use the R*Tree index) before property filters
• Use Limit() and Offset() for pagination
• Use OrderByDistance() for nearest-neighbor results

5. Bulk Operations

• Use BulkInsert() for inserting multiple features — it wraps in a transaction for performance
• Single Insert() is fine for one-off inserts

6. Geometry Construction

• Polygons must be closed (first coordinate == last coordinate)
• LineStrings require minimum 2 coordinates
• Use Coordinate struct for X/Y pairs (aliases: Longitude/Latitude)

7. Testing Pattern

using var db = new SpatialDatabase(":memory:");
var table = db.CreateTable("test", CoordinateSystem.Wgs84,
    new PropertyDefinition("name", PropertyType.Text));

table.Insert(new SpatialFeature(new Point(-104.99, 39.74))
{
    Properties = { ["name"] = "Denver" }
});

var results = table.FindWithinDistance(new Coordinate(-104.99, 39.74), 1000);
results.Count.ShouldBe(1);
results[0].Properties["name"].ShouldBe("Denver");

Geofencing (Shiny.Spatial.Geofencing)

A separate NuGet package that adds GPS-driven geofence monitoring on top of Shiny.Spatial. Built on Shiny.Locations for background GPS on iOS and Android.

The primary use case is monitoring preexisting spatial databases containing city and state/province polygons. There is currently no API to add individual geofences manually — you point the monitor at one or more spatial database tables and it detects region enter/exit automatically.

Install

dotnet add package Shiny.Spatial.Geofencing

Platforms: iOS, Android (registration API is #if IOS || ANDROID)

Setup (DI Registration)

Add() requires a file path on disk. For databases bundled as MAUI raw assets (Resources/Raw), copy the asset to AppDataDirectory first since SQLite cannot open files directly from the app package.

// In MauiProgram.cs
builder.Services.AddSpatialGps<MyGeofenceDelegate>(config =>
{
    config.MinimumDistance = Distance.FromMeters(300); // default
    config.MinimumTime = TimeSpan.FromMinutes(1);     // default
    config.MaximumDistance = Distance.FromKilometers(1); // optional safety net (unset by default)
    config.MaximumTime = TimeSpan.FromMinutes(5);        // optional safety net (unset by default)
    config
        .Add(CopyAssetToAppData("us-states.db"), "states")
        .Add(CopyAssetToAppData("us-cities.db"), "cities");
});

// Helper to copy a MAUI raw asset to a writable location
static string CopyAssetToAppData(string assetFileName)
{
    var destPath = Path.Combine(FileSystem.AppDataDirectory, assetFileName);
    if (!File.Exists(destPath))
    {
        using var source = FileSystem.OpenAppPackageFileAsync(assetFileName).GetAwaiter().GetResult();
        using var dest = File.Create(destPath);
        source.CopyTo(dest);
    }
    return destPath;
}

Key Types

ISpatialGeofenceManager

The main interface for controlling geofence monitoring. Inject this to start/stop monitoring and query the current region.

public interface ISpatialGeofenceManager
{
    bool IsStarted { get; }
    Task<AccessState> RequestAccess();
    Task Start();
    Task Stop();
    Task<IReadOnlyList<SpatialCurrentRegion>> GetCurrent(CancellationToken cancelToken = default);
}

ISpatialGeofenceDelegate

Implement this interface to receive geofence enter/exit events. Register it with AddSpatialGps<T>().

public interface ISpatialGeofenceDelegate
{
    Task OnRegionChanged(SpatialRegionChange change);
}

SpatialRegionChange

Event data for geofence transitions. Each event represents either entering or exiting a single region.

public record SpatialRegionChange(
    string TableName,    // the spatial table that was matched
    SpatialFeature Region, // the region being entered or exited
    bool Entered          // true = entered, false = exited
);

When transitioning directly from Region A to Region B, two events fire: an exit from A (Entered = false), then an entry into B (Entered = true).

SpatialCurrentRegion

Returned by ISpatialGeofenceManager.GetCurrent().

public record SpatialCurrentRegion(string TableName, SpatialFeature? Region);

SpatialMonitorConfig

Configuration for which databases/tables to monitor.

public class SpatialMonitorConfig
{
    public List<SpatialMonitorEntry> Entries { get; }
    public Distance? MinimumDistance { get; set; } // default: 300m
    public TimeSpan? MinimumTime { get; set; }    // default: 1 minute
    public Distance? MaximumDistance { get; set; } // default: unset
    public TimeSpan? MaximumTime { get; set; }    // default: unset
    public SpatialMonitorConfig Add(string databasePath, string tableName);
}

• Add() takes a file path on disk — for MAUI raw assets, copy to AppDataDirectory first (see setup example above)
• MinimumDistance/MinimumTime use AND logic (both must be met before a reading is processed); MaximumDistance/MaximumTime use OR logic and override the minimums — crossing either forces the reading through. Leave the maximums unset (default) to disable the safety net.

Delegate Example

public class MyGeofenceDelegate(
    ILogger<MyGeofenceDelegate> logger,
    INotificationManager notifications
) : ISpatialGeofenceDelegate
{
    public async Task OnRegionChanged(SpatialRegionChange change)
    {
        var regionName = change.Region.Properties.GetValueOrDefault("name") ?? "Unknown";
        var action = change.Entered ? "Entered" : "Exited";

        logger.LogInformation("{Action} {Region} in {Table}", action, regionName, change.TableName);
        await notifications.Send("Geofence", $"{action}: {regionName}");
    }
}

Usage in a Page/ViewModel

public class MyViewModel(ISpatialGeofenceManager geofences)
{
    public async Task StartMonitoring()
    {
        await geofences.RequestAccess();
        await geofences.Start();
    }

    public async Task StopMonitoring()
    {
        await geofences.Stop();
    }

    public async Task CheckCurrentRegions()
    {
        var regions = await geofences.GetCurrent();
        foreach (var r in regions)
        {
            var name = r.Region?.Properties.GetValueOrDefault("name") ?? "None";
            Console.WriteLine($"{r.TableName}: {name}");
        }
    }
}

Best Practices

1. Always use using for SpatialDatabase — it manages SQLite connections
2. Use BulkInsert for batch operations — transactions improve performance significantly
3. Apply spatial filters first — the R*Tree index makes spatial queries O(log n)
4. Use the fluent query builder for complex queries — combines spatial + property filters efficiently
5. Use WGS84 for real-world coordinates — Haversine distance is accurate for GPS data
6. Close polygons — first and last coordinates must match
7. Use L suffix for integer properties — PropertyType.Integer expects long values
8. Prefer FindWithinDistance for proximity queries — more intuitive than manual envelope expansion
9. Use pre-built databases for testing — databases/ folder has ready-to-use US/Canadian geographic data
10. Library is AOT-compatible — safe to use in trimmed/NativeAOT applications