Allocation-free VertexLinker edge distance on packed geometry

[vpaturet]

Motivation

VertexLinker.distance() materializes a full JTS LineString per candidate edge, projects it (cloning every Coordinate), and runs JTS DistanceOp — producing CoordinateXY, PackedCoordinateSequence, Envelope, GeometryLocation for every candidate edge on the linking hot path (and the GBFS rental-linking at startup).

This PR provides an allocation-free alternative implementation of the same algorithm.

What changed

1. Allocation-free edge distance. New EndpointContextLineString.squaredDistanceToPointEquirectangular(...) walks the packed delta geometry directly via the existing DlugoszVarLenIntPacker.Decoder, computing the same per-segment point-to-segment distance JTS DistanceOp produces (mathematically equivalent up to floating-point rounding) — with zero allocation and no LineString materialization. StreetEdge exposes it; VertexLinker.distance() becomes a one-liner. findSplitVertex() (once per winning edge, not per candidate) is intentionally left on JTS.

2. Squared distance. The linker only orders edges and applies thresholds (both monotonic), so the per-candidate sqrt is dropped — the method returns the squared distance and the search radius is squared once. The one consumer needing real distance (the per-mode duplicate-way dedup, an additive epsilon) takes a single sqrt per mode group: dSq <= (closest + eps)², exactly equivalent to d <= closest + eps. This moves sqrt from O(candidate edges) to O(modes).

3. Two cohesive packed-geometry types. The packed byte[] format backs two contracts, now expressed as two single-responsibility types that share one private delta engine:

   • CompactLineString — the self-contained value object (endpoints baked into the packed bytes; used by CompactLineStringSequence).
   • EndpointContextLineString (new, stateless) — the endpoint-context contract, where the endpoints are supplied externally by StreetEdge and omitted from the bytes (compact / uncompact / squaredDistanceToPointEquirectangular).

   The shared encode/decode engine (packIntermediateDeltas / decodeInto + the fixed-point conversions) stays package-private on CompactLineString and is reused, so there is no logic duplication. StreetEdge keeps its raw byte[] field and delegates to EndpointContextLineString — no per-edge wrapper object, no extra indirection, no serialization change. (This replaces the old CompactLineStringUtils.)

Performance (local A/B: Norway graph, 68 GBFS rental networks, 9,995 real production trip queries; JFR + async-profiler)

Allocation sample counts on the linking path (JFR; startup/GBFS-apply window → warm-load window), confirmed independently by async-profiler:

Site	Baseline	This PR
VertexLinker.distance	10,797 / 5,198	0 / 0
JTS DistanceOp	5,692 / 2,710	0 / 0
equirectangularProject	2,872 / 1,451	12 / 2
CoordinateXY	3,006 / 1,348	582 / 58 (−81% / −96%)

The new walk appears in CPU samples but never in allocation samples (the Decoder scalar-replaces). Warm-load distance CPU dropped 1,619 → 54 samples.

[codecov]

Codecov Report

❌ Patch coverage is 93.00000% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.06%. Comparing base (d25d924) to head (1a7fe4a).
⚠️ Report is 27 commits behind head on dev-2.x.

Files with missing lines	Patch %	Lines
...ner/street/geometry/EndpointContextLineString.java	92.40%	1 Missing and 5 partials ⚠️
...g/opentripplanner/street/linking/VertexLinker.java	91.66%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             dev-2.x    #7688      +/-   ##
=============================================
+ Coverage      74.04%   74.06%   +0.02%     
- Complexity     21830    21879      +49     
=============================================
  Files           2423     2426       +3     
  Lines          85772    85930     +158     
  Branches        8536     8563      +27     
=============================================
+ Hits           63507    63644     +137     
- Misses         19235    19249      +14     
- Partials        3030     3037       +7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[leonardehrenfried]

Claude and myself could not find anything wrong with this but I agree with the small issues that @optionsome has raised.