Measure and point helpers: nearest points, distance test, point on surface, boundary, densify, reverse
Six small helpers close gaps that hosts meet daily and that the existing algorithms do not cover: NearestPoints (the two points that realise Distance), IsWithinDistance (a fast yes/no distance test), PointOnSurface (a point that lies on the geometry, for labels), Boundary, Densify and Reverse. They follow the rules already fixed: point-like and scalar results are values without a factory (ADR 0012), geometric results come from the factory and are restricted to what it supports (ADR 0004, ADR 0015), empty and invalid input never throws, and invalid numeric parameters throw ArgumentOutOfRangeException. They add no new concept, so they share one ADR.
German version: 0019-mess-und-punkt-helfer-werte-statt-geometrien.de.md
Consequences
- Placement:
NearestPoints,IsWithinDistanceandPointOnSurfacejoinMeasures(distance and point values, likeDistanceandCentroid).Boundary,DensifyandReverseare in a new static classConstructions(geometric results through the factory).Measuresbecomespartial. Both are inSpatialNET.Extensions, namespaceSpatialNET; for the package validation this is an addition only. NearestPoints(IGeometry2D a, IGeometry2D b)returns(Coordinate OnA, Coordinate OnB)?:nullif either geometry is empty (asDistanceisNaN, ADR 0012); the distance between the two points isDistance(a, b).- If the geometries intersect, or one lies in the area of the other, the point is the same on both sides (a point of intersection, or a point of the inner geometry that lies in the area).
- Among several equally near pairs, the first in input order wins, so the result is deterministic.
- Z and M of the two points are interpolated on their segment under the rules of ADR 0015 and ADR 0017 (only if both ends carry them, at a vertex its own values). The coordinates of a crossing of two segments are computed in floating point, so the two sides may differ by rounding.
- There is no
ShortestLine; a caller builds the line withfactory.CreatePolylinein one line.
IsWithinDistance(IGeometry2D a, IGeometry2D b, double distance)returnsbool: the distance is at mostdistance;distance = 0means the geometries touch or overlap. Empty geometries givefalse. A negative,NaNor infinitedistancethrowsArgumentOutOfRangeException. It stops at the first pair of segments within the distance and starts with an envelope test, so it is faster than comparingDistancefor large inputs.PointOnSurface(IGeometry2D)returnsCoordinate?without Z and M (likeCentroid),nullfor an empty geometry. The point lies on the geometry:- Polygon: an interior point, taken from the widest interior stretch of a horizontal line through the envelope, between the two vertex heights nearest to its centre (the method of JTS
InteriorPointArea); holes and parts are handled by even-odd over all rings. A polygon without area falls back to a vertex of its rings. - Polyline: the interior vertex (not a path end) nearest to the centroid; if there is none, the point at half the length along the line.
- Point and multipoint: the point nearest to the centroid, the first among equals.
- The result is deterministic. It is not the same point as the one of JTS or NTS in every case, so the oracle checks the property (on the geometry, in the interior where an area has one), not equality.
- Polygon: an interior point, taken from the widest interior stretch of a horizontal line through the envelope, between the two vertex heights nearest to its centre (the method of JTS
Boundary:Boundary(IPolygon2D)returnsIPolyline2D: the rings, normalised (shells counter-clockwise, holes clockwise, degenerate rings dropped, ADR 0003), one path per ring.Boundary(IPolyline2D)returnsIMultiPoint2D: the end points by the mod-2 rule of ADR 0013 (an end point that occurs an odd number of times; closed paths have no boundary).- Point and multipoint have an empty boundary, returned as an empty
IMultiPoint2D. A general overload onIGeometry2DreturnsIGeometry2D. - Z and M are kept from the rings and end points, restricted to the factory.
Densify(maxSegmentLength)forIPolyline2D,IPolygon2Dand a generalIGeometry2Doverload (points are copied unchanged):- A segment longer than
maxSegmentLengthis split intoceil(length / maxSegmentLength)pieces of equal length; shorter segments are untouched. The shape does not change, and original vertices are kept. This is the rule of the NTSDensifier. - Z and M of the new vertices are interpolated (both ends needed, ADR 0015). Polygon rings are densified after the normalisation of ADR 0003, so shells stay counter-clockwise and the polygon stays valid.
maxSegmentLengthmust be finite and greater than 0, otherwiseArgumentOutOfRangeException. A value so small that the result would exceed 50 million vertices also throwsArgumentOutOfRangeExceptioninstead of exhausting memory.
- A segment longer than
Reverse(IPolyline2D): reverses every path and the order of the paths, so that the result is the same line traversed backwards. There is noReversefor polygons: their orientation is normalised (ADR 0003), so reversing would have no effect.- Exceptions (ADR 0012):
ArgumentNullExceptionfornull,NotSupportedExceptionfor unknown kinds,InvalidOperationExceptionwithout a factory (for the geometric results). Empty geometries answernull,falseor an empty geometry as above. - Tests (ADR 0008):
- Fixtures with the NTS oracle for
nearestPoints(DistanceOp.NearestPoints: the distance of the returned pair equals the oracle distance, and each point lies on its geometry; the points themselves may differ among ties),isWithinDistance(IsWithinDistance),pointOnSurface(the property check above),boundary(Boundary) anddensify(Densifier). They take the inputs of the existing fixtures ofdistanceandcentroid, so the mandatory tag catalog is covered, with justified exceptions in_catalog.json. Reverseis covered by[Covers]and hand-written tests against NTSReverse.- Property tests (CsCheck):
Distanceequals the distance of theNearestPoints;IsWithinDistance(d)agrees withDistance <= d;Reversetwice gives the line back;Densifykeeps the length and every original vertex and bounds the segment length; the boundary of a polygon has the length of its perimeter; the point on a polygon lies in it.
- Fixtures with the NTS oracle for
- Playground and documentation: descriptors for all six methods (ADR 0011), a section in the concept page of measures and constructions, glossary entries.
Considered Options
NearestPointsreturning a lineShortestLine(rejected: a value needs no factory and the caller builds the line in one line; the tuple can also express "no nearest points" asnull)IsWithinDistanceasDistance(a, b) <= d(rejected: it computes every segment pair; the dedicated test stops early and starts with the envelopes)- Naming the interior point
InteriorPointas JTS does (rejected:PointOnSurfaceis the OGC name; "interior point" is a glossary alias) PointOnSurfacereturning a point with Z and M (rejected: the point is computed, not an original vertex in general;Centroidreturns a plainCoordinatetoo)- Always returning the JTS point (rejected: an exact copy of JTS's choice would tie the project to its internals; the property is what callers need)
- Boundary of a point as an empty polygon or collection (rejected: there is no geometry collection (ADR 0002); an empty multipoint is the closest lower-dimension type)
- Boundary of a polygon as a multipoint of vertices (rejected: that is not the boundary)
Densifyby a fixed step instead of equal pieces (rejected: leaves a short last piece; equal pieces match NTS and keep the segments uniform)- A
Reversefor polygons (rejected: no effect after normalisation) - Six ADRs, one per method (rejected: they introduce no concept of their own; the rules are those of ADR 0004, 0012, 0013, 0015)