M values: carried and interpolated like Z, never evaluated by the geometry algorithms
SpatialNET gets M values (a measure attached to a vertex, for example the distance along a road). M is carried, not computed with: all algorithms stay planar 2D, and M never influences a result's X/Y (nor Z). Where an algorithm creates a vertex, M is interpolated the way Z already is. This reverses the exclusion of M from the charter (map #1, ADR 0009) because the hosts (gView) store M, WKB interchange needs it, and linear referencing (planned) is only useful with it. The reversal happens now, in the preview phase, because it changes Coordinate.
German version: 0015-m-werte-mitgefuehrt-nicht-ausgewertet.de.md
Consequences
- Core:
Coordinategets a fourth positional parameter:Coordinate(X, Y, Z = NaN, M = NaN), withHasM.NaNmeans "no M". This is a binary break of the constructor, accepted in 0.x (package validation needs a suppression for it).IPointM : IPoint2Dwithdouble M { get; }. It is independent ofIPoint3D: a point may implement either or both, and algorithms test the two interfaces separately (asGeometryAccessdoes for Z). There is no combinedIPointZM.IGeometryFactory.SupportsMis a default interface member returningfalse, so existing host factories keep compiling. If it isfalse, algorithms drop M from their results (as forSupportsZ).
- Host contract: as for Z, a class that implements
IPointMreports itsMas valid, including 0. A host that cannot tell "no M" from 0 (gView'sPointalways storesM = 0.0; onlyIGeometryDef.HasMknows) must not implementIPointMon that base class. It implements it on an M-capable subclass or wrapper that it uses whereHasMis true. This goes into the host integration guide. - Interpolation:
- At a new vertex, M comes from the source segment of the result edge, linearly by the parameter along it, exactly as Z does in the noder. If several edges meet in one grid pixel, the first one in the noder's deterministic order wins.
- M is interpolated only if both ends of the segment have M. Otherwise the new vertex has no M. Nothing is guessed, and 0 is never substituted.
- Original vertices keep their M, even if the other end of the segment has none (the noder takes the segment's own end points' M directly). Z follows the same rule: since then, the end points of a segment keep their own Z as well (before, a vertex lost its Z if the other end of its only segment had none).
- Algorithms: overlays (
Intersection,Union,Difference,SymDifference),Cut,SimplifyandOffsetCurvecarry M like Z.BufferandConvexHullproduce no M, just asBufferproduces no Z (ADR 0006).Centroidreturns aCoordinate?without M (as without Z, ADR 0012). Predicates and measures ignore M. - IO: WKT reads and writes
MandZM(POINT M (1 2 3),POINT ZM (1 2 3 4)). GeoJSON stays without M, so that exports remain standard (RFC 7946); whoever needs M uses WKT and, later, WKB. - Tests (ADR 0008): the NTS oracle does not interpolate M in overlays, so M is not checked against it. Instead:
- hand-written expectations (original M is kept, M at new vertices lies between the ends of the source segment, no M if an end has none);
- a invariant property test: the same operation with and without M yields identical X/Y (and Z). This is the strongest guarantee that M never affects the computation and needs no oracle;
- a new mandatory fixture tag
m(onem.jsonper algorithm: input with M, X/Y compared against the oracle as forz); the foreign implementation runs these fixtures too, but drops M because its points never implementIPointM. The M-capable test geometries for the propagation tests are separate (tests/SpatialNET.Tests/MValues).
- Delivery: in three stages (ADR and core; extensions and tests; IO, documentation), but one release (
0.3.0-preview.1), so that no intermediate state with half an M lands on NuGet. - Follow-ups that depend on this: WKB (reading ISO and EWKB, writing ISO) and linear referencing (
Interpolate,Project,Substringby length, plus...ByMvariants). Each gets its own ADR.
Considered Options
- Keep M out and let hosts carry it themselves (rejected: WKB and linear referencing would be unusable for gView data)
- M as a separate coordinate type next to
Coordinate(rejected: doubles the factory and algorithm paths; one value type withNaNfor "none" is consistent with Z) IPointZMand further combined interfaces (rejected: larger interface surface; testing two small interfaces separately is enough)- A
HasMflag onIPointM(rejected: enlarges the contract without solving the host problem; the contract "implements it, so it counts" is the same as for Z) M == 0meaning "no M" (rejected: 0 is a valid measure, linear referencing often starts there)- Averaging M where two operands meet at one vertex (rejected: the result edge belongs to one input edge, whose interpolated M is the natural value)
- M in GeoJSON as a fourth position element (rejected: not standardised, exports should stay interoperable)
- Algorithms that evaluate M (for example filtering by M) in this step (rejected: keeps the 2D core untouched; linear referencing is a separate API on top)