Getting started
This page walks through the first program: installing, setting up the geometry factory, reading geometries, running an algorithm and writing the result.
Installation
SpatialNET is a pre-release and is on NuGet. Install the packages you need with --prerelease:
dotnet add package SpatialNET.Extensions --prerelease
dotnet add package SpatialNET.Imp --prerelease
dotnet add package SpatialNET.IO --prerelease
Alternatively, clone the repository and reference the projects:
git clone https://github.com/jugstalt/SpatialNET.Core.git
dotnet add <your project> reference SpatialNET.Core/src/SpatialNET.Extensions/SpatialNET.Extensions.csproj
dotnet add <your project> reference SpatialNET.Core/src/SpatialNET.Imp/SpatialNET.Imp.csproj
dotnet add <your project> reference SpatialNET.Core/src/SpatialNET.IO/SpatialNET.IO.csproj
The target framework is net10.0. Which projects you need depends on your role:
| You are … | Reference |
|---|---|
| a host (GIS application with its own geometry classes) | SpatialNET.Extensions (brings SpatialNET.Core); see Host integration |
| a user without geometry classes of your own | SpatialNET.Extensions, SpatialNET.Imp and, for text formats, SpatialNET.IO |
A first program
using SpatialNET;
using SpatialNET.Imp;
using SpatialNET.IO;
// Once at startup: the factory that algorithms use to create their results.
GeometryFactory.Default = ImpGeometryFactory.Instance;
var a = Wkt.Read<IPolygon2D>("POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))");
var b = Wkt.Read<IPolygon2D>("POLYGON((5 5, 15 5, 15 15, 5 15, 5 5))");
IPolygon2D overlap = a.Intersection(b);
Console.WriteLine(overlap.ToWkt()); // POLYGON ((10 5, 10 10, 5 10, 5 5, 10 5))
Console.WriteLine(overlap.Area()); // 25
Console.WriteLine(a.Intersects(b)); // True
Console.WriteLine(a.Buffer(1).Area() > 100); // True
What happens here:
- Geometries are interfaces.
IPolygon2Dis a read-only interface;Wkt.Read<T>creates the geometry through the factory, in this case as the classes of the reference implementationSpatialNET.Imp. - Algorithms are extension methods on the interfaces (
Intersection,Buffer,Area,Intersects, …). All of them live in the namespaceSpatialNET. - Results come from the factory. An algorithm creates its result geometries through
IGeometryFactory. Every algorithm takes it as an optionalfactoryparameter; if you passnull(the default),GeometryFactory.Defaultis used. If neither is set, the algorithm throws anInvalidOperationExceptionwith a clear message (ADR 0004).
Options and precision
Optional parameters follow a fixed order: required parameters → domain options → factory → gridSize.
// Grid size in map units (default: derived automatically from the coordinates).
IPolygon2D union = a.Union(b, FillRule.NonZero, gridSize: 0.001);
// Several expensive predicates against the same geometry: prepare it once.
PreparedGeometry prepared = a.Prepare();
bool inside = prepared.Contains(Wkt.Read<IPolygon2D>("POLYGON((1 1, 2 1, 2 2, 1 2, 1 1))"));
// Full DE-9IM: matrix and pattern matching.
string matrix = a.Relate(b).ToString(); // "212101212"
- Fill rule. The area of a polygon is defined by the even-odd rule over all its rings; shells and holes are derived from nesting, not marked (ADR 0003). Overlay operations accept a
FillRule(EvenOdd,NonZero,Positive,Negative), for example to merge overlapping shells withNonZero. - Grid. Overlays always round their results to a grid (snap rounding): result coordinates lie on the grid, and in return the topology is provably consistent and the result valid. The grid size is taken from the
gridSizeparameter, otherwise fromPrecision.DefaultGridSize, otherwise derived automatically from the largest coordinate of the inputs (ADR 0005). Predicates such asIntersectsandRelatecompute exactly on the input coordinates, without a grid. - Strict results. Results are dimension-homogeneous: touch remnants of lower dimension are dropped (two polygons touching along an edge intersect in an empty polygon, not in a line).
Reading and writing
SpatialNET.IO reads and writes WKT, GeoJSON and WKB (ADR 0009, ADR 0016):
IGeometry2D g = Wkt.Read("LINESTRING(0 0, 10 10)");
string json = g.ToGeoJson();
IReadOnlyList<IGeometry2D> all = GeoJson.ReadAll(json); // also FeatureCollection
byte[] wkb = g.ToWkb(); // ISO WKB, little endian
IGeometry2D fromWkb = Wkb.Read(wkb); // ISO and EWKB
Reading always goes through the factory (parameter factory, otherwise GeometryFactory.Default). Geometries that are syntactically correct but geometrically invalid are accepted unchanged.
For vector tiles (Mapbox Vector Tiles) of any tile grid see Vector tiles (MVT).
What is available
| Area | Methods (extension methods in the namespace SpatialNET; the event tables and the triangulation are static methods and classes of that namespace) |
|---|---|
| Overlays | Intersection, Union, UnionAll, Difference, SymDifference, Clip, Polygonize |
| Position of a point | Locate (Location), also on PreparedGeometry |
| Derived geometries | Buffer, OffsetCurve, ConvexHull, Simplify, Cut |
| Predicates | Intersects, Disjoint, Contains, Within, Covers, CoveredBy, Touches, Crosses, Overlaps, EqualsTopo, Relate, Prepare |
| Spatial index | SpatialIndex<T>, ToSpatialIndex, Query, Nearest, Join, SelfJoin |
| Linear referencing | Interpolate (also with a side offset), Project (also within a window of lengths), ProjectDetailed, Substring, InterpolateByM, ProjectToM, SubstringByM, CalibrateM, LocateBetween, LocateAlong, LocateFeature, LocateEvents |
| Event tables (route events, no geometry) | LineEvents (Intersect, Union, Difference, Dissolve, Clip, At), PointEvents (Between, Within, Outside) |
| Triangulation, Voronoi and terrain | DelaunayTriangles, DelaunayEdges, VoronoiDiagram, VoronoiEdges, Triangulate, and the class Triangulation (FromPoints, FromPointsAndLines, FromPolygon, Locate, InterpolateZ, Contour, Slope, Aspect, SurfaceArea, Volume, Drape, InterpolateNaturalNeighbour, Resample, Refine, SlopeZones, ContourBands, LineOfSight, Viewshed) |
| Validity | IsValid, Validate, MakeValid |
| Measures | Area, Length, Envelope, Centroid, Distance, NearestPoints, IsWithinDistance, PointOnSurface, HausdorffDistance, Polylabel, FastPolygonLabel, FastAlternativePolygonLabelsLazy |
| Constructions | Boundary, Densify, Smooth, SmoothToTolerance, Reverse, LineMerge, Translate, Scale, Rotate, Transform, MinimumRotatedRectangle, MinimumBoundingCircle, ConcaveHull, ConcaveHullByRatio |
| Clean-up | RemoveHoles, RemoveSmallParts, SnapToGrid, ReducePrecision |
| Checks | IsSimple, IsClosed, IsRing, EqualsExact |
| Conversion | AsList (LINQ-friendly views), ToWkt, ToGeoJson, ToWkb |
The signatures, parameters and exceptions of every method are in the API reference, which is generated from the XML comments. The methods live in static classes named by topic (Measures, Overlays, Validation, Preparation, …; the extension class has a plural or gerund name, its result type a singular one, such as ValidationResult), but you rarely name them, because you call the methods on the geometry. Create geometries through a factory (ImpGeometryFactory or your own); the classes behind it are not public.
The playground
The playground is a small web application to try the algorithms on a map:
dotnet run --project src/SpatialNET.Playground
Open http://localhost:5003, press Ctrl+K to choose an algorithm, draw inputs (target A/B), upload GeoJSON or pick one of the sample geometries from the bar. The samples are the fixtures with the tag playground from the repository folder samples/. Distances are given in the units of the computation CRS, which is chosen automatically (auto-UTM) by default (ADR 0010). Every input also has a WKT field (with Z and M) and every result shows its WKT, which is how the M algorithms get their data (GeoJSON has no M, ADR 0015).
Building the documentation
The documentation site (English and German) is built with DocFX, which is pinned as a local tool:
./docs/build.ps1 # builds docs/_site/en and docs/_site/de
./docs/build.ps1 -Serve # additionally serves the result at http://localhost:8080
The API reference is generated from the XML comments of the four libraries and exists in English only.