Lineare Referenzierung: nach Länge und nach M, erster Treffer entlang der Linie, Werte statt Geometrien
SpatialNET bekommt lineare Referenzierung auf Polylinien: Eine Position auf einer Linie wird entweder über ihre Länge entlang der Linie oder über ihren M-Wert (ADR 0015) angesprochen. Die Operationen sind Interpolate (der Punkt an einer Position), Project (die Position des nächsten Punktes zu einem gegebenen Punkt) und Substring (das Stück zwischen zwei Positionen), jeweils als Längen-Variante und als ...ByM-Variante. Sie sind Extension-Methoden in SpatialNET.Extensions. Wie sonst auch (ADR 0012) sind punktförmige und skalare Ergebnisse Werte (Coordinate?, double), die keine Factory brauchen; nur die Stücke von Substring sind Geometrien und kommen aus der Factory. M spricht eine Position nur dort an, wo die Linie M trägt, und verändert die Geometrie nie; für nicht monotones M, das echte Daten haben, gilt die Regel erster Treffer entlang der Linie, und nichts wirft.
English version: 0017-lineare-referenzierung-laenge-und-m-erster-treffer.md
Consequences
Ort: statische Klasse
LinearReferencinginSpatialNET.Extensions, NamespaceSpatialNET. Kein neues Paket,SpatialNET.Corebleibt reine Verträge. Für die Package Validation ist das nur eine Ergänzung.API (Extension-Methoden auf
IPolyline2D; Parameterreihenfolge wie in ADR 0012: Pflichtparameter, dannfactory):Methode Liefert Bedeutung Interpolate(double distance)Coordinate?der Punkt bei einer Länge; nullbei einer Linie ohne PunkteProject(Coordinate point)doubledie Länge des Punktes auf der Linie, der pointam nächsten liegt;NaNbei einer Linie ohne PunkteSubstring(double from, double to, factory)IPolyline2Ddas Stück zwischen zwei Längen InterpolateByM(double m)Coordinate?der Punkt, an dem die Linie mzuerst erreicht;null, wenn es keinen gibtProjectToM(Coordinate point)doubleder M-Wert am nächsten Punkt; NaN, wenn die Linie dort kein M hatSubstringByM(double fromM, double toM, factory)IPolyline2Ddas Stück zwischen den ersten Treffern zweier M-Werte ProjectundProjectToMgibt es auch fürIPoint2D, das nur umwandelt.IGeometry2D-Overloads gibt es nicht: Die Operationen sind auf Linien definiert, und der Rand eines Polygons ist hier keine Linie.Position entlang der Linie: die planare Länge, dieselbe wie
Length(). Z nimmt nicht teil. Die Pfade einer Polylinie werden in ihrer Reihenfolge aneinandergelegt (kumulierte Länge), ohne dass eine Verbindung zwischen dem Ende eines Pfades und dem Anfang des nächsten angenommen wird. Segmente der Länge 0 tragen nichts bei. Eine Länge, die genau auf die Grenze zweier Pfade fällt, gehört zum Ende des früheren Pfades (Interpolateliefert also dieses Ende, nicht den Anfang des nächsten Pfades).Interpolate:distancewird auf[0, Länge]begrenzt: negativ ergibt den Anfang, zu groß das Ende. „Negativ zählt vom Ende“ wie in JTS gibt es nicht (der Aufrufer rechnetLänge - d).- Eine Linie, deren Punkte alle gleich sind, hat Länge 0 und liefert diesen Punkt.
- Das Ergebnis trägt interpoliertes Z und M auf dem Segment nach den Regeln aus ADR 0015: nur wenn beide Enden es haben, und an einem ursprünglichen Stützpunkt genau dessen eigene Werte.
Project: nächster Punkt in der Ebene, planarer Abstand. Unter gleich nahen Punkten (eine Linie, die sich kreuzt oder berührt) wird die kleinste Länge geliefert, damit die Antwort deterministisch ist. Die Projektion auf ein Segment wird auf das Segment begrenzt.Substring:- Beide Längen werden begrenzt.
from < toläuft vorwärts,from > toliefert das Stück umgekehrt (die Richtung folgt von → nach), wie in JTS. Sind die Längen nach der Begrenzung gleich, ist das Ergebnis eine leere Polylinie: Ein Stück der Länge 0 ist nichts, im Einklang mit den Kollaps-Regeln aus ADR 0006 und ADR 0007. - Das Stück ist eine Polylinie mit einem Pfad je berührtem Pfad; die Lücke zwischen zwei Pfaden wird nicht überbrückt.
- Neue Endpunkte tragen interpoliertes Z und M, ursprüngliche Stützpunkte dazwischen behalten ihre. Das Ergebnis wird auf
SupportsZ/SupportsMder Factory beschränkt (ADR 0015).
- Beide Längen werden begrenzt.
Die
...ByM-Varianten:- Nur Segmente, deren beide Enden M tragen, nehmen teil. Eine Strecke ohne M wird weder überinterpoliert noch ist sie ein Fehler: Sie kann einfach nicht antworten.
- Erster Treffer: Die Linie wird in ihrer Reihenfolge durchlaufen (Pfade der Reihe nach, Segmente der Reihe nach). Das erste Segment, dessen M-Bereich den Wert enthält (geschlossenes Intervall), antwortet; die Position darin ist linear in M. Ein Segment mit konstantem M gleich dem Wert antwortet mit seinem Anfang. Nicht monotones M und mehrfach vorkommende Werte (eine Schleife) sind damit erlaubt, und das erste Vorkommen gewinnt.
InterpolateByMliefertnull, wenn kein Segment antwortet.SubstringByMbestimmt die Länge beider ersten Treffer und verhält sich dann wieSubstring; hat ein Wert keinen Treffer, ist das Ergebnis eine leere Polylinie.ProjectToMliefert das M am nächsten Punkt (demselben wie beiProject): interpoliert, wenn beide Enden seines Segments M tragen, das eigene M des Stützpunkts, wenn der Punkt ein Stützpunkt ist, sonstNaN.- Eine Liste aller Treffer gehört nicht zu diesem Schritt (siehe Considered Options).
Exceptions (ADR 0012):
ArgumentNullExceptionbeinull,ArgumentOutOfRangeExceptionbeiNaNoder unendlichemdistance,from,to,m,fromM,toModer einem nicht endlichen Punkt,InvalidOperationExceptionohne Factory (nurSubstringundSubstringByM). Leere oder entartete Linien werfen nie; sie antworten wie oben mitnull,NaNoder einer leeren Polylinie.Kein Zustand, kein Schnappschuss: Jeder Aufruf rechnet aus der Geometrie in O(n). Ein wiederverwendbarer Index kumulierter Längen für viele Abfragen auf einer langen Linie lässt sich später ohne Bruch ergänzen, wenn ein Benchmark ihn verlangt.
Tests (ADR 0008):
- Orakel für die Längen-Varianten ist die NTS-
LengthIndexedLine(ExtractPoint,IndexOf,ExtractLine), mit den dokumentierten Unterschieden (negative Indizes, Begrenzung, die Gleichstand-Regel vonProject) alsdivergence. Fixtures untersamples/interpolate/,samples/project/undsamples/substring/für die Fälle, die NTS beurteilen kann; der Tag-Katalog wird erfüllt oder seine Ausnahmen sind in_catalog.jsonbegründet (Loch-, Verschachtelungs- und ähnliche Tags gelten für Linien nicht). - NTS hat kein M-basiertes Gegenstück, daher sind die
...ByM-Varianten durch handgeschriebene Fälle ([Covers]) und Property-Tests abgedeckt: die Erster-Treffer-Regel gegen einen Brute-Force-Durchlauf, Schleifen, Lücken ohne M, konstantes M, M gleich 0. - Property-Tests (CsCheck) für die Längen-Varianten:
Project(Interpolate(d))istdauf einfachen Linien; die Länge vonSubstring(a, b)ist|b − a|nach der Begrenzung;Substring(0, Länge)hat dasselbe X/Y wie die Linie; bei monotonem M liefertInterpolateByM(M von Interpolate(d))denselben Punkt; M ändert nie ein X/Y.
- Orakel für die Längen-Varianten ist die NTS-
Playground und Dokumentation: Jede öffentliche Methode braucht einen Deskriptor (ADR 0011) oder eine begründete Ausnahme.
Interpolate,ProjectundSubstringfolgen dem Muster vonCentroid,AreaundCut. Die drei...ByM-Methoden sind ausgenommen: Der Playground liest GeoJSON, und das hat kein M (ADR 0015), sie könnten dort nie antworten. Eine neue Konzeptseite „Lineare Referenzierung“ auf Englisch und Deutsch und ein Glossareintrag.Vorerst nicht dabei: Polygonränder, die Liste aller Treffer eines Wertes, 3D-Längen, M-basierte Maße wie eine Länge entlang M und ein vorberechneter Längenindex.
Considered Options
- Nur die Längen-Varianten (verworfen: Der Hauptgrund für M im Modell ist, eine Linie darüber anzusprechen)
- Negative Längen zählen vom Ende wie in JTS (verworfen: Begrenzen ist einfacher und vermeidet stille Überraschungen; das Ende ist
Länge - d) - Werfen, wenn eine Länge außerhalb der Linie liegt (verworfen: ADR 0012 lässt Algorithmen bei Daten nicht werfen; Begrenzen ist vorhersehbar)
- Für die M-Varianten monotones M verlangen und sonst werfen (verworfen: Echte Netze haben Schleifen und Rücksprünge; die Erster-Treffer-Regel antwortet ohne Exception)
- Lücken ohne M durch Interpolation überbrücken (verworfen: Das würde Messwerte erfinden)
- Eine Liste aller Treffer als einzige M-API (verworfen für jetzt: Die meisten Aufrufer wollen einen Punkt; eine Listenvariante lässt sich ohne Bruch ergänzen)
Interpolatelegt einen Punkt über die Factory an (verworfen: Ein punktförmiges Ergebnis ist ein Wert, wieCentroidin ADR 0012)Projectliefert eine Struktur aus Länge, Punkt und Abstand (verworfen:Interpolate(Project(p))undDistanceliefern den Rest)IGeometry2D-Overloads, die Polygonränder annehmen (verworfen: Die Position entlang der Ringe eines Polygons hat keinen natürlichen Anfang)- Ein
LengthIndex-Objekt von Anfang an (verworfen: Kein Benchmark verlangt es; es kann ohne Bruch folgen)