Repository navigation
Description
Status: proposed
Part of #3105 (GP12, the crossing block of #3096). One pull request into ground-plan.
The steps of the block, in build order: GP12.1 #3342, GP12.2a #3343, GP12.2b #3352, GP12.3a #3344, GP12.3b #3353, GP12.4 #3345, GP12.5 #3346, GP12.6 #3347, GP12.7 #3348, GP12.8 #3349.
Read first: #3105, the contract of the block (words, invariants, the gallery, the costs, the owner's decisions). The
design is on timosPC in /media/timo/OSM1/tmp/ground-plan/crossings/ (CASES.md sections 3, 4 and 7.1;
proto/LEARNED.md section 3a). Short names: gp/ = host/obc-ground-plan/src/, tv/ =
builder/web/src/lib/trailview/. Every place in the code below is verified on ground-plan ea4da43.
Goal
The way graph knows, for each bridge way, each tunnel way and each crossing, what the drawing builds there: the
state of each station, the end lines, the storey of each piece, and the ladder step of each crossing. This step
draws nothing. It gives the counts over the fixture and over box B that every later step reads.
Depends on / blocks
- Depends on: nothing. It can start now.
- Blocks: GP12.3a and GP12.3b (deck sheets), GP12.4 (bores), GP12.5 (closed faces). GP12.2a and GP12.2b do not
need it.
Design
1. What exists, and what is new
| What | Today (verified) | New |
|---|---|---|
| Level of a part | classify in gp/graph/parts.rs:62-93: Level::Tunnel for the kind tunnel, Level::Deck for a deck tag, else Ground. From the tag only |
Unchanged. The level is the claim of the tag; the state (below) is what the geometry allows |
| Crossings with a tunnel way | gp/graph/crossings.rs: a pair where one side is a tunnel way and the other side is not water in a culvert is skipped (continue after the culvert test). No record exists |
A record of the new kind Bore, source Tag: over is the way on top, under the tunnel way. Water over a tunnel way counts as free ground |
| Two ground ways that cross | crossings.rs:386-400: within snap_height_m a junction or a level crossing; from the lower way's clearance_m a synthetic deck; between them Stacked |
Unchanged here: the ladder step of the pair is recorded (section 3). GP12.3b moves the synthetic deck's start to the least room of the pair, when it draws decks; between snap_height_m and the least room the pair stays Stacked, which is ladder step 3. Changing it here would change which pieces storey 0 draws |
| Deck groups | gp/graph/points.rs:631-672: deck pieces that share a point are one Deck (union-find), sorted by the position of their first sample. gp/faces/mod.rs:197-206 (in_level) reads w.deck == Some(k - 1) as level k; level 0 holds Level::Ground ways only, so no tunnel way is drawn on storey 0 |
Sheets by stroke overlap and height (section 5), with a storey each: decks positive, bores negative (faces::build already takes level: i8). in_level does not change here; GP12.3a and GP12.3b make it read the states and storeys |
| State of a station | none | DECK, BORE, OPEN or HIDDEN per station of a tagged way (section 4) |
| End lines | none. A way ends square at its tag end (line end kind LEVEL in the records) |
End line A, portal line and closed line (section 6) |
| Ladder step | none | per crossing (section 3) |
2. Rule values (data, not code)
New per-class fields in the rows of data/trailview/roads.json (the full values exist: clearance_m; the bake's
BORE_M 5.0, BORE_PATH_M 2.6, BORE_RAIL_M 6.5 in host/obc-trailview-features/src/structures.rs:39-41):
| Field | Road classes | Rail classes | Path classes (and track: road values) |
|---|---|---|---|
clearance_least_m |
3.0 | 4.8 | 2.0 |
bore_m |
5.0 | 6.5 | 2.6 |
bore_least_m |
3.0 | 4.8 | 2.0 |
deck_least_m |
0.4 | 0.4 | 0.2 |
roof_least_m |
0.3 | 0.3 | 0.2 |
data/trailview/waterways.json: clearance_least_m 0.3 per kind (the full value clearance_m 1.5 exists).
A new block structures in data/trailview/plan.json: cover_m 1.0, lift_max_m 1.0,
open_max_m 30, deck_min_m 2.0, edge_band_m 0.5, door_min_m 1.0. Later steps add their values to the same
block. The new class fields stay out of the bake's class fields (check solver_rows in
host/obc-trailview-features/src/kinds.rs), so the bake's options do not change. A test holds bore_m equal to the
bake's constants. graph::build (gp/graph/mod.rs:385) takes only Sections today; it gets the structures block
as well.
3. Room and ladder step of a crossing (CASES O6)
- Role: the tag gives it. A tunnel way is the lower way and a bridge way the upper way, also where the heights say the
opposite. Without a tag the heights give it, as today. r= surface of the upper way less surface of the lower way, the least value over the area where the two paved
strokes overlap in plan. A surface is the owner rule: the curve's height at the nearest station plus the bank times
the metres across.- Rooms of the pair, from the class rows (this replaces the fixed numbers of the table in CASES section 4; they are its
defaults):- a deck:
full = clearance_m(lower) + deck(upper),least = clearance_least_m(lower) + deck_least_m(upper), with
deck(upper)the tile'sdeckdepth of the upper way. Over water the lower values come fromwaterways.json
and r is measured to the water level. - a bore:
full = bore_m(tunnel way) + cover_m,least = bore_least_m(tunnel way) + roof_least_m(tunnel way). - The defaults give an opening from 3.4 m over a road, 5.2 m over a railway, 2.2 m over a path; for a bore 3.3 m
(road), 5.1 m (rail), 2.2 m (path); over water 0.7 m under a road deck, 0.5 m under a path deck.
- a deck:
- Step: Full
r >= full; Thinleast <= r < full; Closedsnap_height_m < r < least; At grade|r| <= snap_height_m;
Inverted: the heights put the tagged lower way over the upper way by more thansnap_height_m. Inverted is drawn as
Closed. - Step 3 (Closed), who is interrupted (owner: with no room a railway never ends; the smaller way ends; of two railways
the later row ofroads.jsonends):- a tunnel way, under any way (for a railway tunnel see open point 1 below);
- else the way of the later row of
roads.json(the class rank: rail classes first), whatever the storey-0
overlay's surface rank says (itsranksput every carriageway before a rail bed,gp/faces/mod.rs:482); - a tie in class rank: the tagged lower way, or untagged the lower way; a further tie: the way whose first vertex
has the greater global position (x, then y), a key that every cell gives alike; - a bridge way over water on step 3 is a ground way over a culvert (TrailView ground plan GP15: water crossings: culverts, fords, pipes in stones, stepping stones, footbridges #3108); the water is not interrupted.
4. The state of a station (CASES O1, section 3)
Per sample of a tagged way, on the tiles' heights. ground(q) is storey 0 at q without this way: the highest of the
terrain of the cell input (gp/terrain.rs Terrain::height, the viewer's Catmull-Rom) and, per ground way near q, its
surface less its class fill times the metres past its paved stroke: the body of the way with its bank (CASES section
3; at A1 the stations between the three tracks see the railway's body, not the half bank of the terrain model).
| State | Bridge way | Tunnel way |
|---|---|---|
| DECK | between its two end lines A, when they lie at least deck_min_m apart and no crossing under it is on step 3 with the bridge way as the interrupted way |
|
| BORE | c >= least of the bore, with c = the least of ground over the bore's width less the floor; or the ground over the station is free (no paved stroke) and lacks at most lift_max_m |
|
| OPEN | a bridge way that is not DECK: a ground way | no bore fits; the floor is at or under the terrain; no paved stroke lies over the station; and the station lies within open_max_m of a tag end along the way |
| HIDDEN | the stations over the body of a way that interrupts it on step 3 | everything else. A run between two BORE runs that is not BORE is HIDDEN: a tunnel never becomes an open road in the middle |
A way on step 3 that is not tagged (the lower way under a bridge way of a higher rank) is HIDDEN under that body too.
HIDDEN means: not drawn; storey 0 over it is whole.
5. Sheets and storeys (CASES 7.1, corrected by LEARNED 3a.4)
- A deck stroke is the paved half-width plus
edge_band_mon each side. A bore stroke is the bore's half-width plus
its wall. - Two DECK pieces whose paved strokes overlap in plan are one sheet while their surfaces differ by less than the
least room of the pair: the overlay's rank decides the surface and a riser stands between the two heights, as on
storey 0. Reason: atA1the cycleways overlap the carriageways by 2 m and lie 0.8 m and 1.3 m higher, in one box
(LEARNED 3a.4); the 0.5 m snap of CASES 7.1 would split one box into three storeys. At the least room or more, the
higher piece goes one storey up (a deck over a deck, asB09). - Two DECK pieces whose strokes only touch (their edge bands overlap, their paved strokes do not) are one sheet
only withinsnap_height_m; else they are two sheets of one storey, each with its own free outline and its own
parapet or railing. So two ramps at different heights never get a bare step inside one deck. - Union-find over these pairs, in the order of
gp/graph/points.rs. The same rules for BORE pieces. - Storeys: decks +1, +2, … and bores −1, −2, …, by height among sheets that overlap in plan.
6. End lines (CASES 7.2)
- A at each end of a DECK run: where the tagged stretch begins, moved along the way until the deck stroke lies
outside the paved stroke of every ground arm at that station (search on the samples in steps of 0.1 m, then bisect
to 0.01 m). If less thandeck_min_mremain between the two A, the way is OPEN. - Portal line at each change BORE ↔ OPEN, at the first station from the OPEN side where
c >= least, bisected to
0.01 m. - Closed line at each change to HIDDEN.
- Each end line is one straight segment across its way, normal to the curve at its station, half as long as the
stroke. One line per way per change. - In a sheet of several ways, the ways' own end lines merge where their segments, grown to the sheet's stroke, cross
or lie withinedge_band_mof each other. A merged line is straight, normal to the mean direction of the merged
ways only, at the station farthest into the sheet among them; the ways whose own line lay farther out keep a short
OPEN or ground stretch. An end that merges with no other keeps its own line (a ramp that joins mid-deck,W1,
N1). The rule for one way is this rule with one line. Its inputs are only the ways withinedge_band_mof the
end, which every cell that holds the end holds. This gives a frame and a bore one end line (LEARNED 3.4).
7. Output, counts and debug
WayGraphgains: per tagged way its state runs (station ranges), its end lines (station, the two ends of the
segment, the kind A / portal / closed), the sheet and storey of each piece, and per crossingrand its step.
The crate's checks (graph::check,gp/graph/mod.rs:422) gain the invariants below.GraphStatsgains counters: metres per state; crossings per step and kind (deck over road, rail, path, water;
bore of a road, a rail, a path under a way; bore under free ground); inverted; sheets with more than one way;
storeys beyond ±1; step-3 crossings per class pair, with the way that ends; railway tunnels on step 3 under a
way, counted for both outcomes of open point 1; theT15kind: a change from a DECK run to a tunnel way whose first stations lie over the
terrain, with the metres along the way until the terrain rises over the floor.- The debug tool (
examples/debug) gets a layerlevels: states by colour, end lines, sheets, storeys. - Bytes: no tile or record change. The WASM grows by the state rule and the ladder (estimate 3 to 6 kB gzip). The
debug layer stays inexamples/.
Invariants
- Every station of a tagged way has exactly one state; OPEN lies only within
open_max_mof a tag end; no OPEN run
lies between two BORE runs. Check:graph::checkover every fixture cell, target 0. - Two cells give a way the same states, end lines and storeys where both hold its data within reach. Check: the
border comparison of the fixture test, per way and station, target 0. - The ladder step follows the room by the class rows at every boundary. Check: one table test of synthetic pairs
(each step, each boundary, inverted). - A BORE station has
c >= leastor lies on free ground withinlift_max_m; a DECK has at leastdeck_min_m
between its end lines. Check:graph::check. - Each A lies outside the paved stroke of every ground arm. Check:
graph::check. - No pixel changes. Check: the record and mesh digests of the fixture cells are unchanged (the existing tests).
Decisions already made by the owner that apply
- "The proposal of three forms (deck, bore, roof) with the ladder full → thin → closed → at grade: approved as
proposed." - "No room at all: the closed framed door" (drawn in GP12.5; here only the step).
- "Ground lifted up to 1 m over a shallow tunnel: okay, but heights first; the lift is only the fallback"
(lift_max_m= 1.0 here; GP12.8 asks the heights for the room). - No special cases: one rule per operation for every input; list each remaining case distinction with its reason.
Not in scope
Any drawing (GP12.2a to GP12.7). The heights and the bake (GP12.8). Level crossings (#3106) and culverts (#3108):
they keep their crossing kinds.
Proofs and pictures required before review
- The counts of section 7 over the fixture and over box B on the demo release (the release
censusbinary of
host/obc-trailview-features, one run under its caps:--workers 3 --memory 2G, nice, its time reported). - A comparison with CASES section 4 ("Today": 5,059 crossings, 77 % full, 11 % thin, 11 % closed, 1 % at grade, 1 %
inverted; by kind).gallery/tools/ladder.pycounted centre-line crossings with a nominal deck depth; explain each
difference over 3 points of share. - The
T15count with the metres to the rising terrain, as a table (input for open point 1 of TrailView ground plan GP12: bridges, tunnels, underpasses and galleries: decks, bores and roofs with the ladder (the contract of the crossing block) #3105,T15). - The step and the state of each of the 50 gallery places (
gallery/views.json) in a table: today's room of
gallery/INDEX.mdagainst the crate's step. Each difference has a reason. - The debug tool's top-down
levelspicture at the fixture placesT14(46.82262, 8.40113),p04(46.82385,
8.38679) andB04(46.82271, 8.41662). The implementer opens each one. - For
A1,W1andN1(box B): the station states and the end lines in a table from the census output (A1: one
BORE run under all three tracks;W1,N1: an end line per ramp end). - No gallery shoot: nothing draws differently (invariant 6).
Cost to measure
- The graph stage time per cell, p50 and p95 over the fixture, before and after (
examples/debug --bench). Base:
ground-planat the branch point. - WASM bytes, gzip and raw, against the guard (
builder/wasm/wasm_size_guard.py --module ground-plan). The owner
accepts about 15 to 25 kB of gzip for the whole block, the wall top included; report the step's bytes; stop and
report past 25 kB in total.
Risks and the stop rule
ground(q)from the graph's strokes is not the drawn ground (it has no slope bands). A station can be BORE by this
rule while a neighbour's cut lowers the drawn ground over it. GP12.4 holds that ground by a cover bound with a rank
(LEARNED 3.2); here only count the BORE stations within a slope reach of another way.- Stop and report to the orchestrator if: two cells disagree on a state, an end line or a storey; the counts on box B
differ from CASES section 4 by more than 5 points of share in a kind without a reason; or the state rule needs a
case distinction by class pair or by place. - After two failed review rounds, stop and report.
Open points (not decided here)
- A railway tunnel with no room under a road (open with the owner; TrailView ground plan GP12: bridges, tunnels, underpasses and galleries: decks, bores and roofs with the ladder (the contract of the crossing block) #3105 open point 2). (a) It is not drawn
there: a closed door on each side, like any tunnel (the orchestrator's recommendation). (b) It stays whole in an
open cut, and the road ends at it; the state table then gains "OPEN under the body of a way that a railway tunnel
interrupts", and invariant 1 its exception. Size: 43 closed and 4 inverted rail bores on today's data, 0 on the
solver's bakec3(CASES section 4). This step counts both outcomes per class pair and can start before the
answer; the rule above follows (a) until the owner answers. - Merged end lines (section 6) are a choice of this plan;
A1(four ways) andW1confirm them in GP12.4's
and GP12.3b's pictures.
Requirements: the verification console could not be checked from this PC (no agent token here). The orchestrator sets
the pull request's Requirements: line.
Activity
timohueser commentedon Nov 11, 2026
GP12.1 design note (implementer, before code)
Base:
ground-pland97131f. The places of the issue (parts.rs:62-93,crossings.rs:339,mod.rs:385,mod.rs:422,points.rs:631-672,faces/mod.rs:197-206) are unchanged there.roads.jsonrows getclearance_least_m,bore_m,bore_least_m,deck_least_m,roof_least_m;waterways.jsonrows getclearance_least_m.sections.rsreads them withGRAPH_FIELDS/WATER_GRAPH_FIELDSintoWaySection/WaterSection. The bake'ssolver_rowsandwaterway_rowskeep only their own fields, so the bake options do not change. A test inobc-trailview-features/src/structures.rsholdsbore_mof every row equal tobore(tags).structuresblock.plan.jsonstructures→graph::Structures, parsed infaces::rules::Rules::parse(it already parsesplan.json).graph::build(cell, input, sections, structures); every caller passes&rules.structures.graph/crossings.rscrossings(): the pair with a tunnel way (not water) is no longer skipped; it getsCrossingKind::Bore,Source::Tag,overthe other way. Verified difference: the other kinds insert their stations as samples (insert), which moves the samples of the way on top and so the faces. A Bore record does not insert them, so storey 0 does not change.graph/levels.rs, called at the end ofgraph::buildafterpoints::assemble: per crossingroom_m,stepand the interrupted way (Crossinggains three fields); per tagged way the state runs (WayGraph.runs), the end lines (WayGraph.end_lines), the sheets with their storey (WayGraph.sheets);GraphStats.levels(counts of owned elements only, so the census sums them over cells without double counts).graph::checkgains G7 (one state per station, OPEN only near a tag end, no OPEN between BORE), G8 (BORE room, DECK length), G9 (A outside every ground arm).tests/graph.rsG5 compares states, end lines and storeys near each border. A table test ingraph/tests.rscovers the ladder boundaries.requestshashes{:?}of the wholeWayGraph, so it changes by construction. The proof of "no pixel change" is new digests of the near records and of the face words in therequestsindex (one tooling commit, run on the base and on the head), the far block digest, andcheck-bytes.sh(native = WASM) on the head.transportand the debug tool readsgraph.crossings, so a new kind changes no face.decktag has no deck depth in the tiles: I use itsdeck_least_mfordeck(upper)(to confirm).parts.rstrim).edge_band_mas its wall until GP12.4 adds one (to confirm).deck_min_m) acts per graph way; the length between the A lines reads on through deck joints up todeck_min_m.Generated by Claude Code
timohueser commentedon Nov 11, 2026
GP12.1 deviations from this issue (PR #3367)
GraphStats: they cost WASM bytes and no viewer reads them. They are in the fixture helper (tests/fixture/mod.rslevels_counts) that the debug tool and the census binary share. T15's input isWayGraph.levels.deck_into_tunnel. The census binary has--levels(graph and levels only).deck(upper)of a way without adecktag is itsdeck_least_m(to confirm).edge_band_m: the blockstructureshas no wall value.deck_min_m) acts per graph way; the metres between the A lines read on through deck joints up todeck_min_m.ris capped atPLACE_M(16 m) along each way; the surface is linear between samples.Generated by Claude Code
timohueser commentedon Nov 11, 2026
GP12.1 after the review of PR #3367: changed deviations
graph::builddoes not callgraph::levels: the device does not link the levels yet (size, the review's option ii). The WASM guard is back at 714 KiB gzip / 1860 KiB raw; the step adds 2,094 B of gzip. GP12.3a (TrailView ground plan GP12.3a: deck sheets in the crate: storey records, one deck plan per storey, the shell with a real thickness (no pixel change) #3344) links the levels in, with a target of at most 12 kB.claude/gp12-1-later); the T15 data moved to the census helper; the check computes G7 to G9 itself.snap_height_mover the terrain, and the ground over a tunnel station leaves out the ways that go on from its ends (B2). OPEN only between a tag end and the first BORE from it. A step-3 crossing hides only the stretch over the body. An A line lies at most 40 m into its deck.Generated by Claude Code
timohueser commentedon Nov 13, 2026
Done: merged into
ground-planas #3367 (states, end lines, storeys and the ladder, counts only).Generated by Claude Code