Shiny.Spatial.Geofencing 1.0.0-beta-0022

Shiny.Spatial

Documentation

A dependency-free, cross-platform .NET geospatial database library. 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.

AOT compatible and trimmable.

Features

• Two-pass spatial query pipeline (R*Tree bounding box filter + C# geometry refinement)
• WGS84 (Haversine) and Cartesian (Euclidean) coordinate systems
• Full geometry type support: Point, LineString, Polygon (with holes), Multi*, GeometryCollection
• WKB (Well-Known Binary) serialization
• Fluent query builder with property filtering, distance ordering, and paging
• Bulk insert with transaction support
• Works on iOS, Android, and all .NET platforms

Installation

<PackageReference Include="Shiny.Spatial" Version="1.0.0" />

Target Frameworks

Dependencies

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

Quick Start

Create a Database and Table

using Shiny.Spatial.Database;
using Shiny.Spatial.Geometry;

using var db = new SpatialDatabase("mydata.db");  // or ":memory:"

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

Insert Features

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

table.Insert(new SpatialFeature(new Point(-104.82, 38.83))
{
    Properties = { ["name"] = "Colorado Springs", ["population"] = 478000L }
});

Bulk Insert

var features = new List<SpatialFeature>();
for (int i = 0; i < 100_000; i++)
    features.Add(new SpatialFeature(new Point(lon, lat)));

table.BulkInsert(features); // wrapped in a transaction

Distance Query

// Find all cities within 150 km of Denver
var nearby = table.FindWithinDistance(
    new Coordinate(-104.99, 39.74),
    distanceMeters: 150_000
);

Shape Containment Query

var colorado = 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)
});

var inState = table.FindIntersecting(colorado);

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();

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

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.

API Reference

Geometry Types

All geometry classes are immutable and sealed, extending the abstract Geometry base class.

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.

Algorithms

using Shiny.Spatial.Algorithms;

Database

SpatialDatabase (IDisposable)

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();

Validates R*Tree support on startup via PRAGMA compile_options.

SpatialTable

SpatialQuery (Fluent Builder)

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;

PropertyDefinition

new PropertyDefinition("name", PropertyType.Text)
new PropertyDefinition("population", PropertyType.Integer)
new PropertyDefinition("area", PropertyType.Real)
new PropertyDefinition("data", PropertyType.Blob)

Pre-Built Databases

The databases/ folder contains ready-to-use spatial databases seeded with real geographic data.

Database Catalog

All databases use the CoordinateSystem.Wgs84 coordinate system with WGS84 (longitude/latitude) coordinates.

Using a Pre-Built Database

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"

// Find all states within 500km of Chicago
var nearby = states.FindWithinDistance(new Coordinate(-87.6298, 41.8781), 500_000);

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

// Find cities near San Francisco with population over 500K
var sf = new Coordinate(-122.4194, 37.7749);
var results = cities.Query()
    .WithinDistance(sf, 100_000)
    .WhereProperty("population", ">", 500000L)
    .OrderByDistance(sf)
    .ToList();

using var db = new SpatialDatabase("databases/ca-provinces.db");
var provinces = db.GetTable("provinces");

// Find which province Toronto is in
var toronto = new Point(-79.3832, 43.6532);
var results = provinces.FindIntersecting(toronto);
// results[0].Properties["name"] == "Ontario"

Regenerating Databases

The databases are generated by the Shiny.Spatial.DatabaseSeeder tool. To regenerate:

dotnet run --project tools/Shiny.Spatial.DatabaseSeeder -- ./databases

The seeder contains hardcoded geographic data with simplified polygon boundaries for states/provinces and point locations for cities, using census population figures.

Geofencing (Shiny.Spatial.Geofencing)

GPS-driven geofence monitoring for iOS and Android. Built on Shiny.Locations for background GPS and Shiny.Spatial for spatial queries.

The primary use case is monitoring preexisting spatial databases containing city and state/province polygons. Point the monitor at one or more spatial database tables and it detects region enter/exit automatically.

Installation

<PackageReference Include="Shiny.Spatial.Geofencing" Version="1.0.0" />

Setup

Add() requires a file path on disk. For databases bundled as MAUI raw assets (Resources/Raw), copy 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
        .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;
}

Controlling the Monitor

Use ISpatialGeofenceManager to start/stop geofence monitoring and query the current region:

// Inject ISpatialGeofenceManager
await geofences.RequestAccess();
await geofences.Start();

// Check current regions at any time
var regions = await geofences.GetCurrent();
foreach (var r in regions)
{
    var name = r.Region?.Properties.GetValueOrDefault("name") ?? "None";
    Console.WriteLine($"{r.TableName}: {name}");
}

await geofences.Stop();

Handling Events

Implement ISpatialGeofenceDelegate to receive enter/exit events:

public class MyGeofenceDelegate(ILogger<MyGeofenceDelegate> logger) : ISpatialGeofenceDelegate
{
    public 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);
        return Task.CompletedTask;
    }
}

Each SpatialRegionChange has:

• TableName — the spatial table that was matched
• Region — the SpatialFeature being entered or exited
• Entered — true for entry, false for exit

When transitioning directly from Region A to Region B, two events fire: exit A, then enter B.

Project Structure

geospatialdb/
├── Shiny.Spatial.slnx
├── databases/                  Pre-built spatial databases
│   ├── us-states.db
│   ├── us-cities.db
│   ├── ca-provinces.db
│   └── ca-cities.db
├── src/Shiny.Spatial/
│   ├── Shiny.Spatial.csproj
│   ├── Geometry/               Coordinate, Envelope, Point, LineString, Polygon,
│   │                           MultiPoint, MultiLineString, MultiPolygon, GeometryCollection
│   ├── Serialization/          WkbReader, WkbWriter
│   ├── Algorithms/             DistanceCalculator, PointInPolygon, SegmentIntersection,
│   │                           SpatialPredicates, EnvelopeExpander
│   └── Database/               SpatialDatabase, SpatialTable, SpatialFeature, SpatialQuery
│       └── Internal/           ConnectionPool, SchemaManager, SqlBuilder
├── src/Shiny.Spatial.Geofencing/
│   ├── Shiny.Spatial.Geofencing.csproj
│   ├── ISpatialGeofenceDelegate.cs     Delegate interface for enter/exit events
│   ├── ISpatialGeofenceManager.cs      Manager interface (start/stop/get current)
│   ├── SpatialGpsDelegate.cs           GPS listener that detects region changes
│   ├── SpatialMonitorConfig.cs         Configuration (databases, tables, thresholds)
│   ├── SpatialRegionChange.cs          Event data (Region, Entered bool)
│   ├── ServiceCollectionExtensions.cs  DI registration (AddSpatialGps)
│   └── Infrastructure/
│       └── SpatialGeofenceManager.cs   Manager implementation
├── tests/Shiny.Spatial.Tests/
│   ├── GeometryTests.cs
│   ├── WkbTests.cs
│   ├── AlgorithmTests.cs
│   ├── DatabaseTests.cs
│   ├── QueryTests.cs
│   └── PerformanceTests.cs
├── tests/Shiny.Spatial.Geofencing.Tests/
│   ├── SpatialGpsDelegateTests.cs      GPS delegate enter/exit/transition tests
│   └── SpatialRegionChangeTests.cs     Record equality and deconstruction tests
├── tests/Shiny.Spatial.Benchmarks/
│   ├── InsertBenchmarks.cs
│   ├── SpatialQueryBenchmarks.cs
│   ├── QueryBuilderBenchmarks.cs
│   ├── AlgorithmBenchmarks.cs
│   └── SerializationBenchmarks.cs
├── samples/Sample.Maui/               MAUI sample app with geofencing
└── tools/Shiny.Spatial.DatabaseSeeder/
    ├── Shiny.Spatial.DatabaseSeeder.csproj
    ├── Program.cs
    └── Data/                   Hardcoded geographic seed data
        ├── UsStates.cs             51 US state/territory polygons
        ├── UsCities.cs             100 US city points
        ├── CanadianProvinces.cs    13 Canadian province/territory polygons
        └── CanadianCities.cs       50 Canadian city points

Benchmarks

Measured with BenchmarkDotNet on Apple M2, .NET 10.0.3, Arm64 RyuJIT AdvSIMD. All database benchmarks use in-memory SQLite (:memory:) to isolate CPU/algorithm cost from disk I/O.

# Run all benchmarks
dotnet run --project tests/Shiny.Spatial.Benchmarks -c Release

# Run a specific suite
dotnet run --project tests/Shiny.Spatial.Benchmarks -c Release -- --filter "*Algorithm*"

Insert Performance

Spatial Queries (100K points)

Fluent Query Builder (100K points)

Algorithms (pure computation, no DB)

WKB Serialization

Running Tests

dotnet test

53 tests covering geometry types, WKB roundtrips, spatial algorithms, database CRUD, query pipeline, and a 100K point performance benchmark.

License

MIT