Table of Contents

Class LinearReferencing

Namespace
SpatialNET
Assembly
SpatialNET.Extensions.dll

Linear referencing on polylines (ADR 0017): a position on a line is addressed by its length along the line or by its M value (ADR 0015). Lengths are planar (like SpatialNET.Measures.Length(SpatialNET.IPolyline2D)); the paths of a polyline are laid end to end in their order. Point-like and scalar results are values, only the pieces of Substring and SubstringByM are created through the factory.

public static class LinearReferencing

Inheritance

Inherited Members

Remarks

The ...ByM variants use only segments whose both ends carry M and answer with the first hit along the line, so non-monotonic M is allowed. Empty or degenerate lines never throw; they answer null, System.Double.NaN or an empty polyline.

Methods

CalibrateM(IPolyline2D, IEnumerable<Coordinate>, double, MExtrapolation, IGeometryFactory?)

Gives a polyline M values from anchor points that carry M: every anchor is projected onto the line, a vertex is inserted at its position, and M is interpolated linearly in the length along the line between the anchors (ADR 0030). With the result, SpatialNET.LinearReferencing.ProjectToM(SpatialNET.IPolyline2D,SpatialNET.Coordinate) answers what interpolating between the previous and the next anchor would.

public static IPolyline2D CalibrateM(this IPolyline2D line, IEnumerable<Coordinate> anchors, double maxSnapDistance, MExtrapolation extrapolation = MExtrapolation.None, IGeometryFactory? factory = null)

Parameters

line IPolyline2D

The polyline, usually without M.

anchors IEnumerable<Coordinate>

Points with X, Y and M, in any order.

maxSnapDistance double

The largest distance of an anchor from the line, in map units.

extrapolation MExtrapolation

What M the line gets before the first and after the last anchor.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IPolyline2D

The polyline with M; an empty polyline for a line without points.

Remarks

M of the line itself is ignored, Z is kept (and interpolated at inserted vertices). The anchors are sorted by their position on the line; M need not be monotonic. Anchors at the same position (within 1e-9 of the line length) are merged if their M is equal. Where the nearest point of an anchor is not unique (a line that crosses itself) the smallest length is used, as in SpatialNET.LinearReferencing.Project(SpatialNET.IPolyline2D,SpatialNET.Coordinate).

Exceptions

ArgumentNullException

line or anchors is null.

ArgumentOutOfRangeException

maxSnapDistance is negative, NaN or infinite, or the X or Y of an anchor is not finite.

ArgumentException

There is no anchor; an anchor has no finite M or is farther from the line than maxSnapDistance; two anchors at the same position have different M; SpatialNET.MExtrapolation.Linear with anchors at fewer than two positions.

InvalidOperationException

No factory available, or it does not support M.

CalibrateM(IPolyline2D, IEnumerable<IPoint2D>, double, MExtrapolation, IGeometryFactory?)

Gives a polyline M values from anchor points that carry M: every anchor is projected onto the line, a vertex is inserted at its position, and M is interpolated linearly in the length along the line between the anchors (ADR 0030). With the result, SpatialNET.LinearReferencing.ProjectToM(SpatialNET.IPolyline2D,SpatialNET.Coordinate) answers what interpolating between the previous and the next anchor would.

public static IPolyline2D CalibrateM(this IPolyline2D line, IEnumerable<IPoint2D> anchors, double maxSnapDistance, MExtrapolation extrapolation = MExtrapolation.None, IGeometryFactory? factory = null)

Parameters

line IPolyline2D

The polyline, usually without M.

anchors IEnumerable<IPoint2D>

Points with X, Y and M, in any order.

maxSnapDistance double

The largest distance of an anchor from the line, in map units.

extrapolation MExtrapolation

What M the line gets before the first and after the last anchor.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IPolyline2D

The polyline with M; an empty polyline for a line without points.

Remarks

M of the line itself is ignored, Z is kept (and interpolated at inserted vertices). The anchors are sorted by their position on the line; M need not be monotonic. Anchors at the same position (within 1e-9 of the line length) are merged if their M is equal. Where the nearest point of an anchor is not unique (a line that crosses itself) the smallest length is used, as in SpatialNET.LinearReferencing.Project(SpatialNET.IPolyline2D,SpatialNET.Coordinate).

Exceptions

ArgumentNullException

line or anchors is null.

ArgumentOutOfRangeException

maxSnapDistance is negative, NaN or infinite, or the X or Y of an anchor is not finite.

ArgumentException

There is no anchor; an anchor has no finite M or is farther from the line than maxSnapDistance; two anchors at the same position have different M; SpatialNET.MExtrapolation.Linear with anchors at fewer than two positions.

InvalidOperationException

No factory available, or it does not support M.

Interpolate(IPolyline2D, double)

The point at distance along the line, with Z and M interpolated on the segment. The distance is clamped to [0, length].

public static Coordinate? Interpolate(this IPolyline2D line, double distance)

Parameters

line IPolyline2D

The polyline.

distance double

The length from the start of the line.

Returns

Coordinate?

The point, or null for a line without points.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

distance is NaN or infinite.

Interpolate(IPolyline2D, double, double)

The point at distance along the line, moved sideways by offset (ADR 0035): to the left of the direction of the line for a positive offset, to the right for a negative one. With an offset of 0 it is SpatialNET.LinearReferencing.Interpolate(SpatialNET.IPolyline2D,System.Double).

public static Coordinate? Interpolate(this IPolyline2D line, double distance, double offset)

Parameters

line IPolyline2D

The polyline.

distance double

The length from the start of the line.

offset double

The distance to the side, in map units; positive left, negative right.

Returns

Coordinate?

The point, or null for a line without points, or for a line without length if the offset is not 0 (it has no direction).

Remarks

The direction is that of the segment that contains the position; at a vertex it is the segment that ends there (the earlier one, as for the boundary of two paths in ADR 0017), at the start of the line the first one. A distance beyond the line is clamped and uses the first or last segment. Z and M are those of the point on the line.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

distance or offset is NaN or infinite.

InterpolateByM(IPolyline2D, double, double)

The point where the line first reaches the M value, moved sideways by offset (see SpatialNET.LinearReferencing.Interpolate(SpatialNET.IPolyline2D,System.Double,System.Double) for the direction; ADR 0035).

public static Coordinate? InterpolateByM(this IPolyline2D line, double m, double offset)

Parameters

line IPolyline2D

The polyline.

m double

The M value.

offset double

The distance to the side, in map units; positive left, negative right.

Returns

Coordinate?

The point, or null if no segment with M at both ends contains the value or the line has no direction.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

m or offset is NaN or infinite.

InterpolateByM(IPolyline2D, double)

The point where the line first reaches the M value, with Z and M interpolated on the segment.

public static Coordinate? InterpolateByM(this IPolyline2D line, double m)

Parameters

line IPolyline2D

The polyline.

m double

The M value.

Returns

Coordinate?

The point, or null if no segment with M at both ends contains the value.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

m is NaN or infinite.

LocateAlong(IPolyline2D, double, IGeometryFactory?)

Every point of the line where M has the value, in the order along the line (ADR 0032): a hit at a vertex shared by two segments counts once, and a segment with constant M equal to the value answers with its start, as SpatialNET.LinearReferencing.InterpolateByM(SpatialNET.IPolyline2D,System.Double) does. Unlike InterpolateByM, which gives the first hit, this finds them all.

public static IMultiPoint2D LocateAlong(this IPolyline2D line, double m, IGeometryFactory? factory = null)

Parameters

line IPolyline2D

The polyline.

m double

The M value.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IMultiPoint2D

The points with Z and M interpolated on the segment; an empty multipoint if there is none.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

m is NaN or infinite.

InvalidOperationException

No factory available.

LocateBetween(IPolyline2D, double, double, IGeometryFactory?)

All stretches of the line where M lies between two values (closed interval), as one polyline: the stretches of consecutive segments form one path, a gap starts a new one (ADR 0032). Unlike SpatialNET.LinearReferencing.SubstringByM(SpatialNET.IPolyline2D,System.Double,System.Double,SpatialNET.IGeometryFactory), which follows the first hit of two values, this finds every stretch, also where M is not monotonic.

public static IPolyline2D LocateBetween(this IPolyline2D line, double fromM, double toM, IGeometryFactory? factory = null)

Parameters

line IPolyline2D

The polyline.

fromM double

One bound of the M interval.

toM double

The other bound of the M interval.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IPolyline2D

The stretches; an empty polyline if there is none.

Remarks

Only segments with M at both ends take part (as in ADR 0017). M is interpolated linearly on a segment, the cut ends get exactly the bound as M and an interpolated Z; original vertices keep their own values, and the direction of the line is kept. Stretches without length (M touches the interval only at a point) are not part of the result; SpatialNET.LinearReferencing.LocateAlong(SpatialNET.IPolyline2D,System.Double,SpatialNET.IGeometryFactory) finds such points. If fromM is greater than toM they are swapped.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

fromM or toM is NaN or infinite.

InvalidOperationException

No factory available.

LocateEvents<T>(IPolyline2D, IEnumerable<LineEvent<T>>, IGeometryFactory?)

Draws the line events of a table on the route (ADR 0040): for every event the stretch of the route whose M lies in its range, as SpatialNET.LinearReferencing.LocateBetween(SpatialNET.IPolyline2D,System.Double,System.Double,SpatialNET.IGeometryFactory) gives it. The result has one entry per event, in the order of the input; an event whose range the route does not reach has an empty polyline. The index of the route is built once, so many events cost little more than one.

public static IReadOnlyList<(LineEvent<T> Event, IPolyline2D Shape)> LocateEvents<T>(this IPolyline2D route, IEnumerable<LineEvent<T>> events, IGeometryFactory? factory = null)

Parameters

route IPolyline2D

The route, a polyline with M.

events IEnumerable<LineEvent<T>>

The line events.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IReadOnlyList<(LineEvent<T> Event, IPolyline2D Shape)>

The events with their stretches.

Type Parameters

T

The values of the events.

Exceptions

ArgumentNullException

route or events is null.

ArgumentOutOfRangeException

An event has a From or To that is NaN or infinite.

InvalidOperationException

No factory available.

LocateEvents<T>(IPolyline2D, IEnumerable<PointEvent<T>>, IGeometryFactory?)

Draws the point events of a table on the route (ADR 0040): for every event the points of the route where M has its value, as SpatialNET.LinearReferencing.LocateAlong(SpatialNET.IPolyline2D,System.Double,SpatialNET.IGeometryFactory) gives them (several where the route passes the value more than once). The result has one entry per event, in the order of the input; an event whose M the route does not reach has an empty multipoint.

public static IReadOnlyList<(PointEvent<T> Event, IMultiPoint2D Points)> LocateEvents<T>(this IPolyline2D route, IEnumerable<PointEvent<T>> events, IGeometryFactory? factory = null)

Parameters

route IPolyline2D

The route, a polyline with M.

events IEnumerable<PointEvent<T>>

The point events.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IReadOnlyList<(PointEvent<T> Event, IMultiPoint2D Points)>

The events with their points.

Type Parameters

T

The values of the events.

Exceptions

ArgumentNullException

route or events is null.

ArgumentOutOfRangeException

An event has an M that is NaN or infinite.

InvalidOperationException

No factory available.

LocateFeature(IPolyline2D, IGeometry2D, double, IGeometryFactory?)

The ranges of M along a route where a line or an area lies: the reverse of SpatialNET.LinearReferencing.LocateBetween(SpatialNET.IPolyline2D,System.Double,System.Double,SpatialNET.IGeometryFactory), from a geometry to what a route system stores (ADR 0034). A parcel next to a road becomes "from 4200 to 4900".

public static IReadOnlyList<(double From, double To)> LocateFeature(this IPolyline2D route, IGeometry2D feature, double tolerance, IGeometryFactory? factory = null)

Parameters

route IPolyline2D

The calibrated route, a polyline with M.

feature IGeometry2D

A polyline or a polygon.

tolerance double

How far from the feature the route still counts, in map units. For a polygon 0 is allowed (the area itself); for a line it must be greater than 0.

factory IGeometryFactory?

The factory for the intermediate geometries; null = SpatialNET.GeometryFactory.Default. It must support M.

Returns

IReadOnlyList<(double From, double To)>

The ranges, sorted; empty if there is none or the route has no M there.

Remarks

The feature is widened by tolerance (a buffer) and cut with the route; the M values of the pieces of the route inside it are the result. A piece gives (lowest M, highest M) of its vertices, which is the M that it covers since M is interpolated linearly on a segment (ADR 0017). Stretches of the route without M cannot answer and are left out; a piece without length (the feature touches the route at one point) is not a range. Ranges that touch or overlap are joined, so a route that passes the feature twice gives two ranges only if they are apart in M.

The M values at the ends of a range are interpolated on the grid of the overlay (ADR 0005), so they are exact to about its size.

A point has an M value, not a range: use SpatialNET.LinearReferencing.ProjectToM(SpatialNET.IPolyline2D,SpatialNET.Coordinate) and IsWithinDistance.

Exceptions

ArgumentNullException

route or feature is null.

ArgumentOutOfRangeException

tolerance is negative, NaN or infinite, or 0 for a line.

ArgumentException

feature is a point, a multipoint or not a known geometry kind.

InvalidOperationException

No factory available, or it does not support M.

Project(IPolyline2D, Coordinate)

The length along the line of the point nearest to point; among equally near points the smallest length.

public static double Project(this IPolyline2D line, Coordinate point)

Parameters

line IPolyline2D

The polyline.

point Coordinate

The point.

Returns

double

The length, or System.Double.NaN for a line without points.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite.

Project(IPolyline2D, IPoint2D)

The length along the line of the point nearest to point; among equally near points the smallest length.

public static double Project(this IPolyline2D line, IPoint2D point)

Parameters

line IPolyline2D

The polyline.

point IPoint2D

The point.

Returns

double

The length, or System.Double.NaN for a line without points.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite.

Project(IPolyline2D, Coordinate, double, double)

The length along the line of the point nearest to point on the part of the line between two lengths (ADR 0031). It tells apart the passes of a line that crosses itself or doubles back: restrict the search to the stretch where the point is expected. The result is a length on the whole line.

public static double Project(this IPolyline2D line, Coordinate point, double from, double to)

Parameters

line IPolyline2D

The polyline.

point Coordinate

The point.

from double

The length where the search window starts.

to double

The length where the search window ends.

Returns

double

The length, or System.Double.NaN for a line without points.

Remarks

Both lengths are clamped to [0, length]; if from is greater than to they are swapped (the direction does not matter for a search). Among equally near points the smallest length wins. For "after a position" pass the line's Length() as to.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite, or from or to is NaN or infinite.

Project(IPolyline2D, IPoint2D, double, double)

The length along the line of the point nearest to point on the part of the line between two lengths (ADR 0031). It tells apart the passes of a line that crosses itself or doubles back: restrict the search to the stretch where the point is expected. The result is a length on the whole line.

public static double Project(this IPolyline2D line, IPoint2D point, double from, double to)

Parameters

line IPolyline2D

The polyline.

point IPoint2D

The point.

from double

The length where the search window starts.

to double

The length where the search window ends.

Returns

double

The length, or System.Double.NaN for a line without points.

Remarks

Both lengths are clamped to [0, length]; if from is greater than to they are swapped (the direction does not matter for a search). Among equally near points the smallest length wins. For "after a position" pass the line's Length() as to.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite, or from or to is NaN or infinite.

ProjectDetailed(IPolyline2D, Coordinate)

Where a point lies relative to the line (ADR 0035): the length of the nearest point on the line, that point, the distance to it and the signed offset to the side (positive left of the direction of the line, negative right), so that Interpolate(Position, Offset) gives the point back when it lies beside the line.

public static LineProjection? ProjectDetailed(this IPolyline2D line, Coordinate point)

Parameters

line IPolyline2D

The polyline.

point Coordinate

The point.

Returns

LineProjection?

The result, or null for a line without points.

Remarks

The nearest point and the length are those of SpatialNET.LinearReferencing.Project(SpatialNET.IPolyline2D,SpatialNET.Coordinate). The side is that of the segment of the nearest point. A point beyond the end of the line has its nearest point at the end, the distance to it, and the side of the extension of the end segment; on that extension itself (and for a line without direction) the side counts as left.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite.

ProjectDetailed(IPolyline2D, IPoint2D)

Where a point lies relative to the line (ADR 0035): the length of the nearest point on the line, that point, the distance to it and the signed offset to the side (positive left of the direction of the line, negative right), so that Interpolate(Position, Offset) gives the point back when it lies beside the line.

public static LineProjection? ProjectDetailed(this IPolyline2D line, IPoint2D point)

Parameters

line IPolyline2D

The polyline.

point IPoint2D

The point.

Returns

LineProjection?

The result, or null for a line without points.

Remarks

The nearest point and the length are those of SpatialNET.LinearReferencing.Project(SpatialNET.IPolyline2D,SpatialNET.Coordinate). The side is that of the segment of the nearest point. A point beyond the end of the line has its nearest point at the end, the distance to it, and the side of the extension of the end segment; on that extension itself (and for a line without direction) the side counts as left.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite.

ProjectDetailed(IPolyline2D, Coordinate, double, double)

SpatialNET.LinearReferencing.ProjectDetailed(SpatialNET.IPolyline2D,SpatialNET.Coordinate) within a window of lengths: the nearest point on the part of the line between two lengths, as for SpatialNET.LinearReferencing.Project(SpatialNET.IPolyline2D,SpatialNET.Coordinate,System.Double,System.Double) (ADR 0031).

public static LineProjection? ProjectDetailed(this IPolyline2D line, Coordinate point, double from, double to)

Parameters

line IPolyline2D

The polyline.

point Coordinate

The point.

from double

The length where the search window starts.

to double

The length where the search window ends; swapped with from if lower.

Returns

LineProjection?

The result, or null for a line without points.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite, or from or to is NaN or infinite.

ProjectDetailed(IPolyline2D, IPoint2D, double, double)

SpatialNET.LinearReferencing.ProjectDetailed(SpatialNET.IPolyline2D,SpatialNET.Coordinate) within a window of lengths: the nearest point on the part of the line between two lengths, as for SpatialNET.LinearReferencing.Project(SpatialNET.IPolyline2D,SpatialNET.Coordinate,System.Double,System.Double) (ADR 0031).

public static LineProjection? ProjectDetailed(this IPolyline2D line, IPoint2D point, double from, double to)

Parameters

line IPolyline2D

The polyline.

point IPoint2D

The point.

from double

The length where the search window starts.

to double

The length where the search window ends; swapped with from if lower.

Returns

LineProjection?

The result, or null for a line without points.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite, or from or to is NaN or infinite.

ProjectToM(IPolyline2D, Coordinate, double, double)

The M value at the point nearest to point on the part of the line between two lengths: the M of Project(point, from, to) (ADR 0031).

public static double ProjectToM(this IPolyline2D line, Coordinate point, double from, double to)

Parameters

line IPolyline2D

The polyline.

point Coordinate

The point.

from double

The length where the search window starts.

to double

The length where the search window ends.

Returns

double

The M value, or System.Double.NaN if the line has no M there.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite, or from or to is NaN or infinite.

ProjectToM(IPolyline2D, IPoint2D, double, double)

The M value at the point nearest to point on the part of the line between two lengths: the M of Project(point, from, to) (ADR 0031).

public static double ProjectToM(this IPolyline2D line, IPoint2D point, double from, double to)

Parameters

line IPolyline2D

The polyline.

point IPoint2D

The point.

from double

The length where the search window starts.

to double

The length where the search window ends.

Returns

double

The M value, or System.Double.NaN if the line has no M there.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite, or from or to is NaN or infinite.

ProjectToM(IPolyline2D, Coordinate)

The M value at the point of the line nearest to point (the point of Project).

public static double ProjectToM(this IPolyline2D line, Coordinate point)

Parameters

line IPolyline2D

The polyline.

point Coordinate

The point.

Returns

double

The M value, or System.Double.NaN if the line has no M there.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite.

ProjectToM(IPolyline2D, IPoint2D)

The M value at the point of the line nearest to point (the point of Project).

public static double ProjectToM(this IPolyline2D line, IPoint2D point)

Parameters

line IPolyline2D

The polyline.

point IPoint2D

The point.

Returns

double

The M value, or System.Double.NaN if the line has no M there.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

The coordinates of point are not finite.

Substring(IPolyline2D, double, double, IGeometryFactory?)

The piece of the line between two lengths, one path per touched path. Both lengths are clamped; if from is greater than to the piece runs in the opposite direction.

public static IPolyline2D Substring(this IPolyline2D line, double from, double to, IGeometryFactory? factory = null)

Parameters

line IPolyline2D

The polyline.

from double

The length where the piece starts.

to double

The length where the piece ends.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IPolyline2D

The piece; an empty polyline if it has no length.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

from or to is NaN or infinite.

InvalidOperationException

No factory available.

SubstringByM(IPolyline2D, double, double, IGeometryFactory?)

The piece of the line between the first hits of two M values (see Substring).

public static IPolyline2D SubstringByM(this IPolyline2D line, double fromM, double toM, IGeometryFactory? factory = null)

Parameters

line IPolyline2D

The polyline.

fromM double

The M value where the piece starts.

toM double

The M value where the piece ends.

factory IGeometryFactory?

The factory; null = SpatialNET.GeometryFactory.Default.

Returns

IPolyline2D

The piece; an empty polyline if one of the values has no hit or the piece has no length.

Exceptions

ArgumentNullException

line is null.

ArgumentOutOfRangeException

fromM or toM is NaN or infinite.

InvalidOperationException

No factory available.