Host integration
SpatialNET works exclusively through interfaces. A host – an existing GIS application with its own geometry classes – integrates it in three steps, without converting its geometries:
- Let the host geometry classes implement the geometry interfaces of
SpatialNET.Core. - Provide an
IGeometryFactorythat creates result geometries as host classes from coordinates. - Set
GeometryFactory.Defaultonce at startup (or pass the factory to each call).
From then on, every algorithm in SpatialNET.Extensions works directly on the host geometries and returns host geometries.
The geometry interfaces
All interfaces are read-only and minimal (ADR 0002):
| Interface | Members | Meaning |
|---|---|---|
IGeometry2D |
– | Empty base type of all geometries |
IPoint2D |
X, Y |
A point |
IPoint3D : IPoint2D |
Z |
A point with height; 3D exists only on points |
IPointM : IPoint2D |
M |
A point with a measure; independent of IPoint3D, a point may implement both |
IPointCollection2D |
PointCount, indexer |
Ordered points; base of the following three |
IPath2D : IPointCollection2D |
– | A path (line string), part of a polyline |
IRing2D : IPath2D |
– | A closed path, part of a polygon |
IMultiPoint2D : IGeometry2D, IPointCollection2D |
– | A set of points |
IPolyline2D : IGeometry2D |
PathCount, indexer |
One or more paths (corresponds to MultiLineString) |
IPolygon2D : IGeometry2D |
RingCount, indexer |
A flat list of rings (corresponds to MultiPolygon) |
Things to know:
- Rings. A polygon is a flat list of rings without a hole marker. Its area is defined by the even-odd rule over all rings; shells and holes follow from nesting, and the ring orientation is ignored on input. The closing point of a ring (equal to the start point) may be repeated or omitted (ADR 0003).
- No
IReadOnlyList<T>on purpose. Point sequences usePointCountplus an indexer. This avoids a secondIEnumerable<T>on classes that already enumerate their points, which would make LINQ ambiguous. For LINQ andforeach,SpatialNET.Extensionsoffers list views:points.AsList(),polyline.AsList(),polygon.AsList(). A host may additionally implementIReadOnlyList<T>and is then passed through directly. - Further members such as envelope, area or
IsEmptyare not part of the interfaces. They are extension methods, so they do not collide with members of the same name on the host classes. - Z. Algorithms interpolate Z at new vertices if the points involved are
IPoint3D. Hosts that always carry a height simply returnZ = 0. - M. Algorithms carry M and interpolate it at new vertices (like Z) if the points involved are
IPointM; they never compute with it (ADR 0015). A class that implementsIPointMreports itsMas valid, including 0;NaNmeans "no M". A host that cannot tell "no M" from 0 (for example a point class that always storesM = 0) must not implementIPointMon that class, but on an M-capable subclass or wrapper that it uses where the geometry has M. - Empty geometries are geometries with 0 points, paths or rings.
Implementing the interfaces is usually a few lines per class: either directly on the host classes, or – if the host has its own interfaces – on those, using default interface members for indexers whose return type differs. A minimal host looks like this:
// A minimal host: mutable classes that implement the SpatialNET interfaces.
public sealed class HostPoint(double x, double y) : IPoint3D
{
public double X { get; set; } = x;
public double Y { get; set; } = y;
public double Z { get; set; } // hosts that always carry a height simply return 0
}
public sealed class HostRing(params HostPoint[] points) : IRing2D
{
public int PointCount => points.Length;
public IPoint2D this[int index] => points[index];
}
public sealed class HostPolygon(params HostRing[] rings) : IPolygon2D
{
public int RingCount => rings.Length;
public IRing2D this[int index] => rings[index];
}
The geometry factory
Algorithms never construct geometries themselves. They hand coordinates to the factory (ADR 0004):
| Member | Creates |
|---|---|
SupportsZ |
– (whether created geometries are meant to carry Z) |
SupportsM |
– (whether created geometries are meant to carry M; default member, false) |
CreatePoint(Coordinate, source) |
a point |
CreateMultiPoint(ReadOnlySpan<Coordinate>, source) |
a multipoint; empty without coordinates |
CreatePolyline(ReadOnlySpan<ReadOnlyMemory<Coordinate>>, source) |
a polyline from paths; empty without paths |
CreatePolygon(ReadOnlySpan<PolygonPart>, source) |
a polygon from parts; empty without parts |
A PolygonPart is a shell (closed, counter-clockwise) with the holes that lie directly in it (closed, clockwise). The result is already valid, so the host does not have to re-derive holes.
The contract for implementations:
- Thread-safe or stateless.
GeometryFactory.Defaultis used by all threads. - Copy buffers. Passed buffers must not be referenced after the call.
- Empty means empty. Empty input produces empty geometries, never
null. - Z may be dropped. If
SupportsZisfalse, algorithms produce no Z at all. - M may be dropped. If
SupportsMisfalse(the default of the interface), algorithms produce no M at all. sourceis the primary input geometry of the algorithm (ornull). The host can take metadata such as the spatial reference from it, without SpatialNET knowing it.
Results are dimension-homogeneous, so there is no CreateGeometryCollection. A host without a class for some kind (here: multipoint and polyline) can throw NotSupportedException in the corresponding method; algorithms that would need it then fail clearly instead of returning something else.
// The factory receives coordinates only and creates the host classes from them.
public sealed class HostGeometryFactory : IGeometryFactory
{
public bool SupportsZ => false;
public IPoint2D CreatePoint(Coordinate coordinate, IGeometry2D? source) =>
new HostPoint(coordinate.X, coordinate.Y);
public IMultiPoint2D CreateMultiPoint(ReadOnlySpan<Coordinate> coordinates, IGeometry2D? source) =>
throw new NotSupportedException("This host has no multipoint class.");
public IPolyline2D CreatePolyline(ReadOnlySpan<ReadOnlyMemory<Coordinate>> paths, IGeometry2D? source) =>
throw new NotSupportedException("This host has no polyline class.");
public IPolygon2D CreatePolygon(ReadOnlySpan<PolygonPart> parts, IGeometry2D? source)
{
var rings = new List<HostRing>();
foreach (var part in parts)
{
rings.Add(ToRing(part.Shell.Span));
foreach (var hole in part.Holes.Span)
{
rings.Add(ToRing(hole.Span));
}
}
return new HostPolygon(rings.ToArray());
}
private static HostRing ToRing(ReadOnlySpan<Coordinate> coordinates)
{
var points = new HostPoint[coordinates.Length];
for (int i = 0; i < points.Length; i++)
{
points[i] = new HostPoint(coordinates[i].X, coordinates[i].Y);
}
return new HostRing(points);
}
}
Putting it together
// 1. Your own geometry classes implement the read-only interfaces ...
var square = new HostPolygon(
new HostRing(new HostPoint(0, 0), new HostPoint(10, 0), new HostPoint(10, 10), new HostPoint(0, 10)));
var other = new HostPolygon(
new HostRing(new HostPoint(5, 5), new HostPoint(15, 5), new HostPoint(15, 15), new HostPoint(5, 15)));
// 2. ... and a factory creates the results as your own classes.
GeometryFactory.Default = new HostGeometryFactory();
IPolygon2D result = square.Intersection(other);
Console.WriteLine(result is HostPolygon); // True
Console.WriteLine(result.AsList().Count); // 1 ring
GeometryFactory.Default is a plain static property that is meant to be set once at startup. To use a different factory for a single call, pass it explicitly: square.Intersection(other, factory: myFactory).
Threads and mutable geometries
Host geometries are usually mutable; the library treats them as values for the length of a call.
- During a call an algorithm reads your geometry. Do not change that instance from another thread while an algorithm is running on it. Reading the same instance from many threads is fine, as long as your own classes allow concurrent reads.
PreparedGeometryandSpatialIndex<T>copy what they need (a snapshot of the coordinates, the envelopes), so later changes to the host object do not affect them; build a new one to see changes. Both are thread-safe after construction, so build them once and share them (ADR 0014, ADR 0024).- The factory is called from whatever thread runs the algorithm, so it must be thread-safe or stateless (see above).
- Results are new objects. An algorithm never returns an input instance and never changes its input, so you can keep the input and the result side by side.
Units, coordinate systems and the grid
The algorithms are planar: they compute on the numbers X and Y, whatever they mean. Distances and areas come out in the units of the coordinates, so use a projected coordinate system (metres) for anything that measures: a buffer of 10 around longitude/latitude data is 10 degrees. Z and M never take part in a computation.
Overlays round their result to a grid (ADR 0005). By default the grid size is derived from the largest coordinate of the input, which suits most data. Set Precision.DefaultGridSize once if your data has a natural resolution (for example 0.001 m), or pass gridSize to a single call; see Options and precision. Predicates and measures compute on the exact input coordinates and use no grid.
Errors and edge cases
All algorithms follow the same rules (ADR 0012), so you can rely on them in one place:
| Situation | Result |
|---|---|
An argument is null |
ArgumentNullException |
A parameter is out of range (a negative distance, a grid size that is not finite or not greater than 0, a NaN tolerance) |
ArgumentOutOfRangeException |
No factory passed and GeometryFactory.Default is not set |
InvalidOperationException |
An object implements IGeometry2D but none of the four kinds (point, multipoint, polyline, polygon) |
NotSupportedException |
| A geometry is empty or invalid | never an exception: an empty result, 0 for area and length, NaN for a distance, null where there is no point, false for a predicate |
A coordinate is NaN or infinite |
IsValid and Validate report it; MakeValid removes it; other algorithms are not defined on it |
| An invalid polygon is the input | the result follows the even-odd rule over all rings; check IsValid where you need a guarantee (ADR 0003) |
Choosing the right tool
| You do this many times | Use |
|---|---|
| Test one geometry against many others | Prepare(), then query the prepared geometry |
| Look up items by place in a large set | SpatialIndex<T>: Query for a rectangle, Nearest for the closest |
| Pair the items of two sets that meet | Join and SelfJoin on two indexes |
| Merge many polygons, lines or points | UnionAll, not a loop of Union |
| Show geometry at a small scale | Simplify, Clip |
| Keep user input clean | Validate and MakeValid |
| Give a road its kilometres, and ask by kilometre or by click | CalibrateM once, then ProjectToM, LocateAlong, LocateBetween |
| Combine tables of route events (speed limit, surface, bridges) | LineEvents and PointEvents, then LocateEvents to draw them |
| Heights, slopes, contour lines or a height profile | one Triangulation, asked many times |
| Which point is the nearest, as areas | VoronoiDiagram, cut to a boundary |
Reading and writing
SpatialNET.IO reads and writes WKT, WKB (ISO and EWKB, with Z and M) and GeoJSON. Every Read takes an optional factory: pass yours, and what you read is already a host geometry, without a conversion step. For the use cases see the Cookbook.
Checklist
- The host geometry classes implement the interfaces;
PointCountandRingCountand the indexers are cheap (they are called in loops). IPoint3Donly where Z is real;IPointMonly where "no M" can be told from 0.- A factory that creates your classes, thread-safe, copies its buffers, creates empty geometries for empty input.
GeometryFactory.Defaultset once at startup.- Coordinates in a projected system for measuring;
Precision.DefaultGridSizeset if your data has a natural resolution. Prepare()andSpatialIndex<T>where the same geometry or set is queried repeatedly.- The foreign-geometry tests of the repository run against your classes (next section).
Checking your integration
The repository contains a deliberately awkward host-style implementation in the test project (tests/SpatialNET.Tests/Foreign/ForeignGeometries.cs): class-based indexers, rings without closing point, shells clockwise, additionally IReadOnlyList<T>, and every point as IPoint3D with Z = 0. Every fixture test runs against it, which is how assumptions about concrete types are caught (ADR 0008). It is a good model for what a real host looks like.