Files
road-compiler/.trellis/spec/backend/junction-layer-seams.md
T

4.3 KiB

Junction layer seams

Scope and source contracts

Complex-junction seams use a 0.01 m numerical tolerance in local metric coordinates. This is internal stitching precision, not OSM survey accuracy. test/helpers/junction-seams.js audits published features against source identities in junction_structure; it does not call the geometry builders to manufacture expected geometry.

  • Exterior surfaces match the complete directional_road_ids set of a carriageway. Core and pavement match cluster_id; approaches match carriageway_key.
  • Native lanes use road_id and travel-direction lane_index. Preview lanes use a combined cross-section index running from outer.right to outer.left. Map outgoing lanes in reverse order, followed by incoming lanes in forward order. Do not equate these two index spaces or choose a nearest lane globally.
  • Edge lines match the source road and side. Separators match the lane pair; the boundary between opposite directions belongs to the road centre marking. Centre markings match the complete directional_road_ids set and a primary road_id belonging to that set; a partial source match is not sufficient.
  • Sidewalk corners match corner_key and strips from their two source arms. Absence is acceptable only for disabled source sidewalks or an explicit rejection identifying that exact corner. A cluster-wide fallback diagnostic must not excuse a missing corner elsewhere.

Both ends of a corridor

trimRoadAtComplexClusters(road, junctionPlans, clusters, boundaries) in native-road.js calculates both endpoint cutbacks from the original source polyline and each cluster's outer.stationMeters, then calls trimLineRange once. Road surfaces, sidewalks, edges, centre lines and native lanes share it.

Wrong: select startCluster || endCluster as the only trim owner, or trim sequentially using the second station on the shortened line. Correct: resolve each endpoint independently and preserve intermediate source bends.

The first bug leaves the far approach covered by exterior pavement and its edge/lane endpoints tens of metres past the seam. Vertex-to-boundary checks can miss it because the long side edges still touch both seam endpoints.

Measurements and failures

auditJunctionSeams(model, geometry, structures) returns each layer's checked, failed, notApplicable and identity-bearing records.

Interface Required measurement
Exterior surface / approach Endpoint error and complete boundary segment coverage
Approach / core and published pavement Complete segment containment, respecting holes
Native / preview lanes and solid edges Corresponding endpoint or paint-cap midpoint
Dashed edges, centre lines, separators Support alignment and bounded terminal gap
Corner / sidewalk strip Both full end edges, with source-arm matching

Missing expected objects fail; never iterate only detected objects and report an empty set as success. Segment coverage partitions at all boundary crossings, so interior notches cannot hide between fixed probes. Polygon holes remain holes.

Dashes do not need white paint across every seam. An outward road starts its dash sequence at the seam, so its first cap must coincide; the other end can leave a residual dash cycle. Current edge/separator cycles are 2 m paint + 2 m gap. Centre markings publish dash_length_m and dash_gap_m. Report these gaps separately from the 1 cm transverse alignment tolerance. The audit does not certify every individual dash, every double-line component, or interior paint continuity through a complex core where centre markings are not published.

Required regression

Run node test/junction-layer-seams.js (also in npm test). To inspect every identity and measurement, run:

node test/junction-layer-seams.js --report /private/tmp/junction-layer-seams.json

Keep nonempty per-layer counts for straight/curved, one-way/two-way, local width and island edits, two-ended corridors, reordered input, current real OSM and explicitly sidewalk-enabled real OSM. Required negative controls: exactly 2 cm displacement, missing single/whole counterparts, wrong source identities, swapped lane indices, absent first anchored dash, a 2 cm interior notch and a hole. Do not loosen the tolerance or refresh unrelated fixture snapshots.