Project with a window of lengths
A line that crosses itself or doubles back (a hairpin bend, a loop, a road that returns along itself) has several nearest points for one click, and Project (ADR 0017) answers with the smallest length, so a click on the later pass lands on the earlier one. A host usually knows where the point should be: near the previous result, or within the section it is working on. Project and ProjectToM with a window [from, to] search only that stretch of the line and tell the passes apart.
German version: 0031-project-mit-laengenfenster.de.md
Consequences
Placement: two more overloads each of
ProjectandProjectToMinLinearReferencing(ADR 0017), inSpatialNET.Extensions, namespaceSpatialNET. For the package validation and the API tracking this is an addition only (ADR 0028).API (extension methods on
IPolyline2D):Method Returns Project(Coordinate point, double from, double to)the length, on the whole line, of the point nearest to pointwithin the windowProjectToM(Coordinate point, double from, double to)the M value at that point Both also exist for
IPoint2D, which only converts, as without a window. The result is a length (or M) on the whole line, so it can be fed toInterpolate,Substringand the rest unchanged.The window is the part of the line between the lengths
fromandto, with the paths laid end to end as everywhere (ADR 0017). Both are clamped to[0, length], and iffromis greater thantothey are swapped: unlikeSubstring, a search has no direction, so there is nothing to reverse. The window is closed, the nearest point may be at its start or its end, and a point that is nearer to the line outside the window still gets the nearest point inside it. An empty window (from == to) answers with that length.Same rules as without a window: among equally near points the smallest length wins; the projection onto a segment is clamped to the part of the segment inside the window;
ProjectToMgives the M of that point, interpolated if both ends of its segment carry M,NaNotherwise; an empty line givesNaN. A window over the whole line gives exactly the result ofProject(point)."After a position" (JTS
IndexOfAfter) is the window[position, length]: passline.Length()asto. A separateProjectAfteris not added, since JTS falls back to the whole line when nothing lies after the position and this API would rather answer within the window than guess.Exceptions (ADR 0012):
ArgumentNullExceptionfornull,ArgumentOutOfRangeExceptionfor a non-finite point or aNaNor infinitefromorto. Infinity is not accepted as "to the end" so that the behaviour is the same as for all other lengths inLinearReferencing.Cost: O(n) like
Project; segments outside the window are skipped without a distance computation.CalibrateM(ADR 0030) does not use the window yet: its anchors carry no hint where they lie. Anchors on a later pass of a loop still land on the earlier one; a way to give them a window (or to use their order) is a possible next step.Tests (ADR 0008): NTS has only
IndexOfAfter, so the cases are hand-written ([Covers]), plus a brute-force scan of a dense sampling of a hairpin road against random points and windows. Also a window over the whole line equals no window, the result stays inside the window, several paths and single-point paths, empty lines and invalid input.Playground and documentation: the playground keeps one input per algorithm without a way to give lengths for a window, and M-based methods are exempt anyway (ADR 0017), so no descriptor; the concept page "linear referencing" has a section.
Out of scope for now: a result with distance and side of the nearest point, a window in terms of M values, a window for
CalibrateM.
Considered Options
ProjectAfter(point, position)only, rejected: it covers "after" but not "within this section", and the window includes it- Accepting
double.PositiveInfinityas "to the end", rejected: all other lengths here must be finite, andLength()is one call - Throwing if
fromis greater thanto, rejected: for a search the order of the bounds carries no meaning, so swapping loses nothing - Falling back to the whole line when the window has no nearer point (as JTS
IndexOfAfter), rejected: the answer would then lie outside the window the caller asked for - A
ProjectionOptionsobject with window, side and tolerance, rejected for now: two lengths are all this step needs, and the other parts are not decided