SpatialMapping.Core 0.1.0

SpatialMapping.Core

3D spatial indices for points and AABB-shaped items (line segments, boxes, mesh primitives). Six structures, a unified set of queries (nearest / k-NN / radius / segment / ray / box), and an empirical benchmark harness that measures every combination on your data so you can pick by reading numbers, not guessing.

Multi-targets netstandard2.0 + net8.0. Works in modern .NET, .NET Framework 4.7.2+, Mono, Unity.

Quick start

Points

using SpatialMapping.Core;
using System.Numerics;

var positions = new[] { new Vector3(0,0,0), new Vector3(1,0,0), new Vector3(0,5,0) };
var bvh = new BvhIndex3D<Vector3, Vector3Distance>();
bvh.Build(positions);

var nearest = bvh.FindNearestToPoint(new Vector3(0.4f, 0, 0));   // .Index = 0

var topK = new List<NearestResult<Vector3>>();
bvh.FindKNearestToPoint(new Vector3(0,0,0), k: 2, topK);

var withinR = new List<NearestResult<Vector3>>();
bvh.FindWithinRadiusOfPoint(Vector3.Zero, radius: 3f, withinR);

Segments (or any AABB-shaped item)

var segments = new[]
{
    new Segment3D(new Vector3(0,0,0), new Vector3(1000, 0, 0)), // long
    new Segment3D(new Vector3(0,5,0), new Vector3(0, 5, 1)),    // short
};
var bvh = new BvhIndex3D<Segment3D, Segment3DDistance>();
bvh.Build(segments);

// Endpoints are 300 and 700 units from this query, but distance to the segment is 0.
var hit = bvh.FindNearestToPoint(new Vector3(300, 0, 0));        // .Index = 0, d² = 0

var clash = bvh.FindNearestToSegment(new Segment3D(new Vector3(0, -1, 0), new Vector3(0, 1, 0)));

var inBox = new List<NearestResult<Segment3D>>();
bvh.QueryBox(new Bounds3D(new Vector3(-1,-1,-1), new Vector3(2,2,2)), inBox);

var firstHit = bvh.FindFirstRayHit(new Vector3(-5, 0, 0), new Vector3(1, 0, 0));

Empirical "which structure?" — SpatialBenchmark

[Fact]
public void PickIndexForMyData()
{
    var report = SpatialBenchmark.RunForSegments(myActualData);
    _out.WriteLine(report.ToMarkdown());
    Assert.Empty(report.CorrectnessIssues);
}

The harness times every applicable structure on every supported query. Naive O(N) fallbacks fill in queries a structure doesn't natively support (so every cell has a number — the timing tells you the cost of forcing the wrong tool). A per-query-type timeout lets you cap infeasible combinations.

Pick a structure

If unsure, run SpatialBenchmark on your data and read the table.

Query × structure matrix

Native = the structure's own implementation. Naive = O(N) fallback (still correct, just slow). "—" = not supported by this structure (use a different one).

All six expose batch + parallel variants of FindNearest* for read-only-after-build query workloads.

Adapting custom item types

Implement IItemDistance3D<T> as a readonly struct for the JIT-monomorphized fast path:

public readonly struct SphereDistance : IItemDistance3D<Sphere>
{
    public Bounds3D GetAabb(in Sphere s) => new(s.Center - new Vector3(s.Radius), s.Center + new Vector3(s.Radius));
    public float DistanceSquaredToPoint(in Sphere s, Vector3 p)
    {
        float d = Vector3.Distance(s.Center, p) - s.Radius;
        return d <= 0 ? 0 : d * d;
    }
    public float DistanceSquaredToSegment(in Sphere s, in Segment3D q)
    {
        float d = MathF.Sqrt(q.DistanceSquaredTo(s.Center)) - s.Radius;
        return d <= 0 ? 0 : d * d;
    }
}

var bvh = new BvhIndex3D<Sphere, SphereDistance>();
bvh.Build(spheres);

Or use the delegate-flavored convenience overload (BvhIndex3D<Sphere>(getAabb, distToPoint, distToSegment)) for ad-hoc work — one extra delegate dispatch per leaf hit.

Out of scope (today)

• No serialization. In-process use only; rebuild from source data on load.
• No frustum query. Same traversal as ray; trivial to add when needed.
• No parallel build. Rebuild is single-threaded; query is parallel.
• Float-only (System.Numerics.Vector3). For city-scale-mm precision, work in a local coordinate frame.

Versioning

0.x — early. API may change between minor versions.