Seitlicher Versatz und Projektion mit Abstand und Seite
Zwei Dinge, die ein WebGIS mit einer Route tut und die zusammengehören. Erstens wird ein Symbol, eine Beschriftung oder ein Ereignis neben der Straße gezeichnet, nicht auf ihrer Achse: „Kilometer 12,4, 3 m rechts“. Zweitens soll ein Klick nicht nur „Kilometer 12,437“ sagen, sondern auch „3 m links der Achse“, damit der Host entscheiden kann, ob der Klick die Straße überhaupt gemeint hat. Beides ist dieselbe Größe, der vorzeichenbehaftete Abstand zur Linie, und es sind die beiden Richtungen einer Umrechnung: Interpolate(position, offset) geht von einer Position und einem Versatz zu einem Punkt, und ProjectDetailed geht von einem Punkt zurück zu Position und Versatz.
English version: 0035-seitlicher-versatz-und-projektion-mit-seite.md
Consequences
Ort: zwei neue Überladungen,
Interpolate(distance, offset)undInterpolateByM(m, offset), die MethodeProjectDetailed(vier Überladungen) und der WerttypLineProjectioninLinearReferencing(ADR 0017) inSpatialNET.Extensions, NamespaceSpatialNET. Die vorhandenen Methoden bleiben unverändert, für die Paketvalidierung und die API-Verfolgung ist das also eine reine Ergänzung (ADR 0028).Das Vorzeichen: ein positiver Versatz liegt links der Richtung der Linie, ein negativer rechts, im üblichen mathematischen Sinn (gegen den Uhrzeigersinn): Fährt man nach Osten, ist links Norden. Das ist die Konvention von
BufferOptions.SingleSided(positiv links, ADR 0006) und von NTSLengthIndexedLine.ExtractPoint(index, offset), womit die Längenvariante in den Tests innerhalb der Segmente geprüft wird.Interpolate(distance, offset)liefert den Punkt beidistanceentlang der Linie, umoffsetsenkrecht zur Linie verschoben. Mit 0 ist esInterpolate(distance).InterpolateByM(m, offset)macht dasselbe für den ersten Treffer eines M-Wertes. Beide liefern eineCoordinate?, einen Wert ohne Factory (ADR 0012).- Die Richtung ist die des Segments, das die Position enthält. An einem Stützpunkt ist es das Segment, das dort endet, das frühere, da die Grenze zweier Pfade zum Ende des früheren Pfades gehört (ADR 0017), wo NTS das Segment nimmt, das dort beginnt (eine dokumentierte Abweichung, getestet); am Anfang der Linie ist es das erste Segment. Eine Distanz außerhalb der Linie wird begrenzt (ADR 0017) und nimmt das erste oder letzte Segment. Der Punkt ist kein Bogen um eine Ecke: An einem Stützpunkt springt der versetzte Punkt von einer Seite der Biegung auf die andere, was eine Zeichnung an dieser Position will.
- Segmente der Länge 0 werden übersprungen. Eine Linie ganz ohne Segment mit Länge hat keine Richtung, ein Versatz ungleich 0 ergibt also
null(und eine Linie ohne Punktenull); ein Versatz von 0 braucht keine Richtung und liefert den Punkt. - Z und M sind die des Punktes auf der Linie; der Versatz verschiebt nur X und Y (ADR 0015).
ProjectDetailed(point)liefert eineLineProjection?(nullfür eine Linie ohne Punkte):Feld Bedeutung Positiondie Länge des nächsten Punktes, wie ProjectPointder nächste Punkt auf der Linie, mit auf dem Segment interpoliertem Z und M, wie ProjectToMihn liestDistanceder Abstand des Punktes dazu, nicht negativ OffsetDistancemit der Seite als Vorzeichen: positiv links, negativ rechtsPositionundPointsind die vonProjectundProjectToM, mit derselben Gleichstandsregel (die kleinste Länge unter gleich nahen Punkten). Überladungen fürIPoint2Dund mit einem Längenfenster(from, to)wie in ADR 0031, damit ein Punkt nahe einer Schleife seinen Durchgang wählen kann und trotzdem seine Seite bekommt.Rundreise. Für einen Punkt, dessen nächster Punkt im Inneren eines Segments liegt, ergibt
Interpolate(Position, Offset)den Punkt zurück. Wo der nächste Punkt ein Stützpunkt oder ein Ende ist, ist die Senkrechte nicht eindeutig, undInterpolatenimmt im Allgemeinen ein anderes Segment als das nächste des Punktes, die Rundreise wird dort also nicht versprochen.Die Seite des Segments des nächsten Punktes. An einer konvexen Ecke sind beide Segmente für einen Punkt im äußeren Keil gleich nah; das erste gewinnt wie bei
Project, die Seite ist also die des früheren Segments, wie auch die Richtungsregel vonInterpolate. Ein Punkt jenseits des Linienendes hat seinen nächsten Punkt am Ende und die Seite der Verlängerung des Endsegments. Ein Punkt genau auf dieser Verlängerung (oder auf der Linie, mit Abstand 0) liegt auf keiner Seite: SeinOffsetzählt als links, also+Distance, auf der Linie also 0. Ein Segment der Länge 0 am nächsten Stützpunkt weicht einem echten, sodass eine Linie, die mit einem doppelten Stützpunkt beginnt, trotzdem eine Seite hat.Ausnahmen (ADR 0012):
ArgumentNullExceptionbeinull,ArgumentOutOfRangeExceptionbei nicht endlichem Punkt,offset,distance,m,fromoderto. Eine leere Linie antwortetnullund wirft nie.Kosten: O(n) wie
Project; die Richtungen der Linie werden einmal je Aufruf aufgebaut, nur wenn ein Versatz verlangt ist.Tests (ADR 0008): NTS hat
ExtractPoint(index, offset), die Versatzvariante wird also für zufällige Linien innerhalb der Segmente damit verglichen (die Stützpunktregel ist die eigene dieser Bibliothek und wird von Hand getestet). Die Seite vonProjectDetailedist von Hand getestet (links, rechts, auf der Linie, jenseits des Endes, auf der Verlängerung, eine Schleife mit Fenster, doppelte Stützpunkte), und eine Rundreise-Eigenschaft prüftInterpolate(Position, Offset)gegen den Eingabepunkt für zufällige Linien und Punkte. AußerdemProjectDetailedgegenProjectundProjectToM, Null-Ergebnisse und ungültige Eingaben.Playground und Dokumentation:
Interpolatebehält seinen Deskriptor unter demselben Namen;ProjectDetailedhat keinen (ADR 0011), da sein Ergebnis eine Struktur ist, die die Oberfläche nicht zeigt; es ist mit dieser Begründung als ausgenommen geführt. Die Konzeptseite „Lineare Referenzierung“ hat einen Abschnitt mit Beispiel, und das Glossar hat „seitlicher Versatz“.Vorerst nicht dabei: ein Bogen oder eine Gehrung um eine Ecke für eine versetzte Linie (das ist
OffsetCurve, ADR 0006), der Versatz eines ganzenSubstring, und eineLineProjectionfür Ereignisse.
Considered Options
offsetals optionalen Parameter zuInterpolate(distance)ergänzen, verworfen: Es würde eine ausgelieferte Signatur ändern und die Binärkompatibilität brechen; eine neue Überladung lässt den alten Aufruf, wie er ist- Ein Ergebnis von
Projectmit dem Versatz alsout-Parametern, verworfen: Ein Record-Struct ist leichter zu lesen und zu erweitern, undProjectbleibt eine schlichte Zahl - ADR 0017 hatte „eine Struktur mit Länge, Punkt und Abstand“ verworfen, weil
Interpolate(Project(p))undDistanceden Rest liefern; das gilt für den Punkt, aber nicht für die Seite, die man aus diesen Aufrufen nicht bekommt, und die Seite macht die Umrechnung umkehrbar. Dieses ADR ergänzt die Struktur aus diesem Grund - Positiven Versatz nach rechts, verworfen: Die mathematische und NTS-Konvention ist links, und
SingleSidednutzt sie - Ein eigenes
Side-Enum neben dem Abstand ohne Vorzeichen, verworfen: Eine vorzeichenbehaftete Zahl nimmtInterpolatezurück, und eine Seite „auf der Linie“ bräuchte einen dritten Wert, den ein Vorzeichen 0 schon ist - Die Winkelhalbierende der Biegung an einem Stützpunkt für die Richtung, verworfen: Sie liefert einen Punkt, der von keinem Segment den Versatzabstand hat, und weicht von JTS ab; das frühere Segment ist einfach und vorhersagbar
- Den Versatz entlang der begrenzten Distanz als Bogen jenseits der Enden, verworfen: Eine Position jenseits der Linie wird in dieser API überall auf ihr Ende begrenzt (ADR 0017), und die Richtung des Endsegments ist die natürliche Fortsetzung
- Bei einem Stützpunkt NTS folgen (das Segment, das dort beginnt), verworfen: Diese API löst jede Grenze zum Ende des früheren Teils auf (ADR 0017), und eine Regel für Positionen auf einem Stützpunkt ist leichter zu merken als eine andere für Versätze; die Abweichung ist dokumentiert und getestet
nullstatt 0 für den Versatz eines Punktes auf der Verlängerung, verworfen: Er hat einen Abstand und einen nächsten Punkt, und „links“ per Konvention hältOffseteine Zahl, dieInterpolateannimmt