Host-Anbindung
SpatialNET arbeitet ausschließlich über Interfaces. Ein Host – eine bestehende GIS-Anwendung mit eigenen Geometrieklassen – bindet es in drei Schritten ein, ohne seine Geometrien umzuwandeln:
- Die Host-Geometrieklassen implementieren die Geometrie-Interfaces aus
SpatialNET.Core. - Der Host stellt eine
IGeometryFactorybereit, die aus Koordinaten Ergebnis-Geometrien als Host-Klassen erzeugt. GeometryFactory.Defaultwird einmal beim Start gesetzt (oder die Factory wird bei jedem Aufruf übergeben).
Danach arbeitet jeder Algorithmus in SpatialNET.Extensions direkt auf den Host-Geometrien und liefert Host-Geometrien zurück.
Die Geometrie-Interfaces
Alle Interfaces sind lesend und minimal (ADR 0002):
| Interface | Member | Bedeutung |
|---|---|---|
IGeometry2D |
– | Leerer Basistyp aller Geometrien |
IPoint2D |
X, Y |
Ein Punkt |
IPoint3D : IPoint2D |
Z |
Ein Punkt mit Höhe; 3D gibt es nur am Punkt |
IPointM : IPoint2D |
M |
Ein Punkt mit Messwert; unabhängig von IPoint3D, ein Punkt darf beide implementieren |
IPointCollection2D |
PointCount, Indexer |
Geordnete Punkte; Basis der nächsten drei |
IPath2D : IPointCollection2D |
– | Ein Pfad (Linienzug), Teil einer Polylinie |
IRing2D : IPath2D |
– | Ein geschlossener Pfad, Teil eines Polygons |
IMultiPoint2D : IGeometry2D, IPointCollection2D |
– | Eine Menge von Punkten |
IPolyline2D : IGeometry2D |
PathCount, Indexer |
Ein oder mehrere Pfade (entspricht MultiLineString) |
IPolygon2D : IGeometry2D |
RingCount, Indexer |
Eine flache Liste von Ringen (entspricht MultiPolygon) |
Wichtig zu wissen:
- Ringe. Ein Polygon ist eine flache Ringliste ohne Loch-Marker. Seine Fläche ist über alle Ringe nach der Even-Odd-Regel definiert; Außenringe und Löcher ergeben sich aus der Verschachtelung, die Ring-Orientierung wird bei der Eingabe ignoriert. Der Schlusspunkt eines Rings (gleich dem Startpunkt) darf wiederholt werden oder fehlen (ADR 0003).
- Bewusst kein
IReadOnlyList<T>. Punktfolgen nutzenPointCountund einen Indexer. So gibt es kein zweitesIEnumerable<T>an Klassen, die ihre Punkte schon aufzählen und bei denen LINQ sonst mehrdeutig würde. Für LINQ undforeachbietetSpatialNET.ExtensionsListen-Sichten:points.AsList(),polyline.AsList(),polygon.AsList(). Ein Host darf zusätzlichIReadOnlyList<T>implementieren und wird dann direkt durchgereicht. - Weitere Member wie Envelope, Fläche oder
IsEmptygehören nicht in die Interfaces. Sie sind Extension-Methoden und kollidieren deshalb nicht mit gleichnamigen Membern der Host-Klassen. - Z. Algorithmen interpolieren Z an neuen Knoten, wenn die beteiligten Punkte
IPoint3Dsind. Hosts, die immer eine Höhe führen, liefern einfachZ = 0. - M. Algorithmen führen M mit und interpolieren es an neuen Knoten (wie Z), wenn die beteiligten Punkte
IPointMsind; sie rechnen nie damit (ADR 0015). Eine Klasse, dieIPointMimplementiert, meldet ihrMals gültig, auch 0;NaNheißt „kein M“. Ein Host, der „kein M“ nicht von 0 unterscheiden kann (zum Beispiel eine Punktklasse, die immerM = 0speichert), darfIPointMnicht auf dieser Klasse implementieren, sondern auf einer M-fähigen Unterklasse oder einem Wrapper, den er dort einsetzt, wo die Geometrie M hat. - Leere Geometrien sind Geometrien mit 0 Punkten, Pfaden bzw. Ringen.
Die Interfaces zu implementieren sind meist wenige Zeilen je Klasse: entweder direkt an den Host-Klassen oder – wenn der Host eigene Interfaces hat – an diesen, mit Default-Interface-Membern für Indexer mit abweichendem Rückgabetyp. Ein minimaler Host sieht so aus:
// 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];
}
Die Geometrie-Factory
Algorithmen konstruieren Geometrien nie selbst. Sie übergeben Koordinaten an die Factory (ADR 0004):
| Member | Erzeugt |
|---|---|
SupportsZ |
– (ob erzeugte Geometrien Z tragen sollen) |
SupportsM |
– (ob erzeugte Geometrien M tragen sollen; Default-Member, false) |
CreatePoint(Coordinate, source) |
einen Punkt |
CreateMultiPoint(ReadOnlySpan<Coordinate>, source) |
einen Multipunkt; ohne Koordinaten einen leeren |
CreatePolyline(ReadOnlySpan<ReadOnlyMemory<Coordinate>>, source) |
eine Polylinie aus Pfaden; ohne Pfade eine leere |
CreatePolygon(ReadOnlySpan<PolygonPart>, source) |
ein Polygon aus Teilflächen; ohne Teilflächen ein leeres |
Eine PolygonPart ist ein Außenring (geschlossen, gegen den Uhrzeigersinn) mit den Löchern, die direkt in ihm liegen (geschlossen, im Uhrzeigersinn). Das Ergebnis ist bereits gültig, der Host muss die Löcher also nicht neu ableiten.
Der Vertrag für Implementierungen:
- Thread-sicher bzw. zustandslos.
GeometryFactory.Defaultwird von allen Threads genutzt. - Puffer kopieren. Übergebene Puffer dürfen nach dem Aufruf nicht mehr referenziert werden.
- Leer heißt leer. Leere Eingaben erzeugen leere Geometrien, nie
null. - Z darf verworfen werden. Bei
SupportsZ == falseliefern Algorithmen gar kein Z. - M darf verworfen werden. Bei
SupportsM == false(dem Standard des Interfaces) liefern Algorithmen gar kein M. sourceist die primäre Eingabe-Geometrie des Algorithmus (odernull). Daraus kann der Host Metadaten wie die Spatial Reference übernehmen, ohne dass SpatialNET sie kennt.
Ergebnisse sind dimensionshomogen, deshalb gibt es kein CreateGeometryCollection. Hat ein Host für eine Art keine Klasse (hier: Multipunkt und Polylinie), kann er in der jeweiligen Methode eine NotSupportedException werfen; Algorithmen, die sie bräuchten, scheitern dann deutlich, statt etwas anderes zurückzugeben.
// 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);
}
}
Alles zusammen
// 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 ist ein einfaches statisches Property, das einmal beim Start gesetzt werden soll. Für einen einzelnen Aufruf mit anderer Factory wird sie explizit übergeben: square.Intersection(other, factory: myFactory).
Threads und veränderliche Geometrien
Host-Geometrien sind meist veränderlich; die Bibliothek behandelt sie für die Dauer eines Aufrufs als Werte.
- Während eines Aufrufs liest ein Algorithmus Ihre Geometrie. Ändern Sie diese Instanz nicht aus einem anderen Thread, solange ein Algorithmus darauf läuft. Dieselbe Instanz aus vielen Threads zu lesen ist in Ordnung, sofern Ihre eigenen Klassen gleichzeitiges Lesen erlauben.
PreparedGeometryundSpatialIndex<T>kopieren, was sie brauchen (einen Schnappschuss der Koordinaten, die Envelopes), spätere Änderungen am Host-Objekt wirken sich also nicht aus; für Änderungen bauen Sie eine neue. Beide sind nach dem Bauen thread-sicher, bauen Sie sie also einmal und teilen Sie sie (ADR 0014, ADR 0024).- Die Factory wird von dem Thread aufgerufen, der den Algorithmus ausführt, muss also thread-sicher oder zustandslos sein (siehe oben).
- Ergebnisse sind neue Objekte. Ein Algorithmus liefert nie eine Eingabeinstanz zurück und verändert nie seine Eingabe, Sie können Eingabe und Ergebnis also nebeneinander behalten.
Einheiten, Koordinatensysteme und das Gitter
Die Algorithmen sind planar: Sie rechnen mit den Zahlen X und Y, was immer diese bedeuten. Abstände und Flächen kommen in den Einheiten der Koordinaten heraus; nehmen Sie für alles, was misst, ein projiziertes Koordinatensystem (Meter): Ein Buffer von 10 um Längen-/Breitengrad-Daten sind 10 Grad. Z und M gehen nie in eine Berechnung ein.
Overlays runden ihr Ergebnis auf ein Gitter (ADR 0005). Standardmäßig wird die Gitterweite aus der größten Koordinate der Eingabe abgeleitet, was für die meisten Daten passt. Setzen Sie Precision.DefaultGridSize einmal, wenn Ihre Daten eine natürliche Auflösung haben (etwa 0,001 m), oder übergeben Sie gridSize an einen einzelnen Aufruf; siehe Optionen und Genauigkeit. Prädikate und Maße rechnen auf den genauen Eingabekoordinaten und nutzen kein Gitter.
Fehler und Randfälle
Alle Algorithmen folgen denselben Regeln (ADR 0012), Sie können sich also an einer Stelle darauf verlassen:
| Situation | Ergebnis |
|---|---|
Ein Argument ist null |
ArgumentNullException |
Ein Parameter liegt außerhalb des Bereichs (ein negativer Abstand, eine Gitterweite, die nicht endlich oder nicht größer als 0 ist, eine NaN-Toleranz) |
ArgumentOutOfRangeException |
Keine Factory übergeben und GeometryFactory.Default nicht gesetzt |
InvalidOperationException |
Ein Objekt implementiert IGeometry2D, aber keine der vier Arten (Punkt, Multipunkt, Polylinie, Polygon) |
NotSupportedException |
| Eine Geometrie ist leer oder ungültig | nie eine Exception: ein leeres Ergebnis, 0 bei Fläche und Länge, NaN bei einem Abstand, null, wo es keinen Punkt gibt, false bei einem Prädikat |
Eine Koordinate ist NaN oder unendlich |
IsValid und Validate melden es; MakeValid entfernt sie; andere Algorithmen sind darauf nicht definiert |
| Ein ungültiges Polygon ist die Eingabe | das Ergebnis folgt der Even-Odd-Regel über alle Ringe; prüfen Sie IsValid, wo Sie eine Garantie brauchen (ADR 0003) |
Das richtige Werkzeug wählen
| Sie tun das oft | Nehmen Sie |
|---|---|
| Eine Geometrie gegen viele andere testen | Prepare(), dann die vorbereitete Geometrie abfragen |
| Elemente einer großen Menge nach Ort finden | SpatialIndex<T>: Query für ein Rechteck, Nearest für das nächste |
| Die sich treffenden Elemente zweier Mengen paaren | Join und SelfJoin auf zwei Indizes |
| Viele Polygone, Linien oder Punkte verschmelzen | UnionAll, keine Schleife aus Union |
| Geometrie in kleinem Maßstab zeigen | Simplify, Clip |
| Benutzereingaben sauber halten | Validate und MakeValid |
| Einer Straße ihre Kilometer geben und nach Kilometer oder Klick fragen | einmal CalibrateM, dann ProjectToM, LocateAlong, LocateBetween |
| Tabellen von Routenereignissen verrechnen (Tempolimit, Belag, Brücken) | LineEvents und PointEvents, dann LocateEvents zum Zeichnen |
| Höhen, Neigungen, Höhenlinien oder ein Höhenprofil | eine Triangulation, oft gefragt |
| Welcher Punkt der nächste ist, als Flächen | VoronoiDiagram, auf eine Grenze zugeschnitten |
Lesen und Schreiben
SpatialNET.IO liest und schreibt WKT, WKB (ISO und EWKB, mit Z und M) und GeoJSON. Jedes Read nimmt optional eine Factory: Übergeben Sie Ihre, und was Sie lesen, ist schon eine Host-Geometrie, ohne Umwandlungsschritt. Anwendungsfälle stehen in den Rezepten.
Checkliste
- Die Host-Geometrieklassen implementieren die Interfaces;
PointCount,RingCountund die Indexer sind billig (sie werden in Schleifen aufgerufen). IPoint3Dnur dort, wo Z echt ist;IPointMnur dort, wo „kein M“ von 0 unterscheidbar ist.- Eine Factory, die Ihre Klassen erzeugt, thread-sicher ist, ihre Puffer kopiert und für leere Eingabe leere Geometrien erzeugt.
GeometryFactory.Defaulteinmal beim Start gesetzt.- Koordinaten in einem projizierten System zum Messen;
Precision.DefaultGridSizegesetzt, wenn Ihre Daten eine natürliche Auflösung haben. Prepare()undSpatialIndex<T>dort, wo dieselbe Geometrie oder Menge wiederholt abgefragt wird.- Die Fremd-Geometrie-Tests des Repositorys laufen gegen Ihre Klassen (nächster Abschnitt).
Die Anbindung prüfen
Im Testprojekt liegt eine absichtlich unbequeme, host-artige Implementierung (tests/SpatialNET.Tests/Foreign/ForeignGeometries.cs): klassenbasierte Indexer, Ringe ohne Schlusspunkt, Außenringe im Uhrzeigersinn, zusätzlich IReadOnlyList<T> und jeder Punkt als IPoint3D mit Z = 0. Jeder Fixture-Test läuft auch gegen sie, so fallen Annahmen über konkrete Typen auf (ADR 0008). Sie ist ein gutes Vorbild dafür, wie ein echter Host aussieht.