Locate, envelope helpers and rectangle clip
Three small pieces fill gaps that every host meets: Locate (where does a point lie relative to a geometry: inside, on the boundary or outside), helpers on Envelope2D (Intersects, Contains, Union, Intersection, Expand, Center, plus ToPolygon) and Clip (a geometry cut to a rectangle, the tile and viewport case). Locate makes public what the predicates already compute internally. Clip is honestly a convenience with fast paths: its core is the existing intersection with the rectangle. They follow the rules already fixed (exact decisions without a grid for what is not constructed, the overlay grid for what is, ADR 0005; empty and invalid input never throws, invalid numeric parameters throw, ADR 0012).
German version: 0022-locate-envelope-helfer-und-clip.de.md
Consequences
Locationis a public enum inSpatialNET.Extensions, namespaceSpatialNET, withOutside,BoundaryandInside(the internal enum of the same name moves there). The name is the one of JTS and NTS; code that imports bothSpatialNETandNetTopologySuite.Geometriesmust qualify it, which the test project does with an alias.Locate(this IGeometry2D geometry, Coordinate point)(and anIPoint2Doverload) in the new static classLocationsreturns where the point lies:- Polygon: by the even-odd rule over all rings (ADR 0003):
Insidein the area,Outsidealso in a hole,Boundaryon any ring, a hole's included. Rings without area are ignored and rings that cancel each other out as in the construction of parts. - Polyline:
Boundaryon an end point by the mod-2 rule (ADR 0013),Insideelsewhere on the line,Outsideoff the line. - Point and multipoint:
Insideif the point is equal to one of them, otherwiseOutside; points have no boundary. - Empty geometry:
Outside. Invalid polygons are read by even-odd, deterministically. - The decisions are exact (orient2d), like the predicates, so
Locateagrees withRelate: for a polygon and a point,InsideisContains,OutsideisDisjoint, andBoundaryis the rest ofIntersects. - A point with a
NaNor infinite coordinate throwsArgumentOutOfRangeException;nullthrowsArgumentNullException.
- Polygon: by the even-odd rule over all rings (ADR 0003):
PreparedGeometry.Locate(Coordinate)gives the same answer for repeated points against one geometry: a polygon goes through the segment index, everything else through the unprepared computation.PreparedGeometrystays not thread-safe (ADR 0013). There is no batch overload with spans in this step.- Envelope helpers are instance members of
Envelope2DinSpatialNET.Core(purely additive, binary compatible; a value type with arithmetic stays within "Core = contracts and value types", ADR 0002):Intersects(Envelope2D)andContains(Envelope2D)treat the border as part of the envelope (closed intervals);Contains(Coordinate)likewise. An empty envelope meets nothing, contains nothing and lies in nothing.Union(Envelope2D)is the smallest envelope containing both (the other one if one is empty),Intersection(Envelope2D)the common part (Emptyif they do not meet),Centerthe middle (NaN if empty).Expand(double distance)widens on all sides; a negative distance shrinks and givesEmptyif nothing is left. Core does not throw: an empty envelope or aNaNdistance givesEmpty.ToPolygon(factory)in the static classEnvelopes(SpatialNET.Extensions) creates the rectangle as a polygon, counter-clockwise and closed. An empty envelope, or one without area (zero width or height), gives an empty polygon. An invalid envelope (not finite, or Min greater than Max) throwsArgumentOutOfRangeException.
Clip(this IPolygon2D, Envelope2D, factory, gridSize)and the overloads forIPolyline2D,IMultiPoint2DandIGeometry2DinOverlaysreturn the part inside the closed rectangle:- Polygon and polyline run through the overlay with the rectangle as polygon (an intersection, so a polyline keeps the parts inside and on the border; strict semantics, ADR 0005); points are filtered exactly and never rounded.
gridSizefollows the cascade of ADR 0005. - Fast paths: a geometry whose envelope lies completely in the rectangle is returned as a copy without rounding (a polygon as a normalised copy: orientation fixed, rings without area dropped; invalid input is not repaired, use
MakeValid), and a geometry whose envelope does not meet the rectangle gives an empty geometry. Only where the border of the rectangle cuts, the overlay runs and only those results lie on the grid. This difference is documented. - A rectangle without area (zero width or height) gives an empty polygon or polyline; a multipoint is still filtered, since a point can lie on a degenerate rectangle. An empty envelope gives an empty result; an invalid envelope throws
ArgumentOutOfRangeException. - Z and M are carried like in
Intersection(ADR 0005, ADR 0015). The corners of the rectangle that become vertices of the result belong to the rectangle, which has no Z and M, so they carry none.
- Polygon and polyline run through the overlay with the rectangle as polygon (an intersection, so a polyline keeps the parts inside and on the border; strict semantics, ADR 0005); points are filtered exactly and never rounded.
- No prepared clip (one polygon against many features) in this step; the existing
Intersectionwith aPreparedGeometryis not part of the API either. - Tests (ADR 0008):
locatefixtures carry the geometry; the test probes every vertex, every segment midpoint, the centre of the envelope and points just outside, and compares each answer with the NTSPointLocator(for polygons on the geometry in the semantics of ADR 0003). Property tests:Locateagrees withContains,DisjointandIntersectsof the predicates, the prepared answer equals the unprepared one, a hole is outside and its ring is boundary.clipfixtures carry the geometry and the rectangle as parameters (minX,minY,maxX,maxY) and are compared with NTSOverlayNGintersecting the same rectangle on the same grid; extra fixtures for a rectangle that contains the geometry and one that misses it. Property tests: the result lies in the rectangle, a geometry inside comes back with identical coordinates, andClipequalsIntersectionwithToPolygonup to the grid.- The envelope helpers are checked against brute-force definitions on random rectangles, including empty ones and touching borders.
- Playground and documentation:
Clipgets a descriptor with four number parameters (ADR 0011).LocateandToPolygonare exempt: the first answers with a category the interface does not display, the second is a conversion and no algorithm. A section in the concept pages for the geometry model and the overlays, glossary entries.
Considered Options
- A different name for
Location, such asPointLocation(rejected: the name of JTS and NTS is what people look for; the clash is limited to code that imports both namespaces) Locatereturning a boolean pair orContains/Touchesonly (rejected:Relatealready gives the matrix; a three-valued answer is what repeated point lookups want)- A batch
Locate(ReadOnlySpan<Coordinate>, Span<Location>)(rejected for now: nothing asks for it yet, and it can follow without a break) - Envelope helpers as extension methods in
SpatialNET.Extensions(rejected: they are plain arithmetic on a value type fromSpatialNET.Core; instance members are found without ausing) Envelope2D.ToPolygonin Core (rejected: it needs the factory, andSpatialNET.Coreis contracts and values only)Clipby Sutherland–Hodgman on the rings (rejected: it leaves degenerate bridges along the border for concave polygons that an overlay would have to repair anyway; the intersection with the rectangle is correct for every polygon)Cliprounding every result to the grid (rejected: tiling should leave geometries that lie completely inside unchanged; the rule "rounded only where cut" is cheap to state)- A prepared clip, or clipping by an arbitrary polygon as a separate method (rejected: that is
Intersection)