Files

89 lines
4.7 KiB
Markdown

# 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.
The canonical complex-pavement region fills construction pockets before it
subtracts explicit `model.exclusionRegions`. A core hole alone is not proof of
the published pavement contract: crossing and corner inputs can otherwise fill
it again. After subtraction, an empty or disconnected result, or any missing
complete approach seam, rejects canonical pavement publication and carries the
cluster plus exclusion identities in its diagnostic.
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:
```sh
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.