Skip to content

TrailView ground plan GP12.1: crossings in the way graph: states, end lines, storeys and the ladder (counts only) #3342

Closed

Description

@timohueser

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's deck depth of the upper way. Over water the lower values come from waterways.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.
  • Step: Full r >= full; Thin least <= r < full; Closed snap_height_m < r < least; At grade |r| <= snap_height_m;
    Inverted: the heights put the tagged lower way over the upper way by more than snap_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 of roads.json ends):
    • 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 (its ranks put 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_m on 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: at A1 the 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, as B09).
  • Two DECK pieces whose strokes only touch (their edge bands overlap, their paved strokes do not) are one sheet
    only within snap_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 than deck_min_m remain 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 within edge_band_m of 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 within edge_band_m of 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

  • WayGraph gains: 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 crossing r and its step.
    The crate's checks (graph::check, gp/graph/mod.rs:422) gain the invariants below.
  • GraphStats gains 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; the T15 kind: 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 layer levels: 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 in examples/.

Invariants

  1. Every station of a tagged way has exactly one state; OPEN lies only within open_max_m of a tag end; no OPEN run
    lies between two BORE runs. Check: graph::check over every fixture cell, target 0.
  2. 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.
  3. 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).
  4. A BORE station has c >= least or lies on free ground within lift_max_m; a DECK has at least deck_min_m
    between its end lines. Check: graph::check.
  5. Each A lies outside the paved stroke of every ground arm. Check: graph::check.
  6. 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 census binary 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.py counted centre-line crossings with a nominal deck depth; explain each
    difference over 3 points of share.
  • The T15 count 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.md against the crate's step. Each difference has a reason.
  • The debug tool's top-down levels picture at the fixture places T14 (46.82262, 8.40113), p04 (46.82385,
    8.38679) and B04 (46.82271, 8.41662). The implementer opens each one.
  • For A1, W1 and N1 (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-plan at 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)

  1. 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 bake c3 (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.
  2. Merged end lines (section 6) are a choice of this plan; A1 (four ways) and W1 confirm 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

  1. timohueser commented on Nov 11, 2026

    @timohueser
    OwnerAuthor

    GP12.1 design note (implementer, before code)

    Base: ground-plan d97131f. 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.

    • Rule values. roads.json rows get clearance_least_m, bore_m, bore_least_m, deck_least_m, roof_least_m; waterways.json rows get clearance_least_m. sections.rs reads them with GRAPH_FIELDS / WATER_GRAPH_FIELDS into WaySection / WaterSection. The bake's solver_rows and waterway_rows keep only their own fields, so the bake options do not change. A test in obc-trailview-features/src/structures.rs holds bore_m of every row equal to bore(tags).
    • structures block. plan.json structures → graph::Structures, parsed in faces::rules::Rules::parse (it already parses plan.json). graph::build(cell, input, sections, structures); every caller passes &rules.structures.
    • Bore records. graph/crossings.rs crossings(): the pair with a tunnel way (not water) is no longer skipped; it gets CrossingKind::Bore, Source::Tag, over the 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.
    • New stage graph/levels.rs, called at the end of graph::build after points::assemble: per crossing room_m, step and the interrupted way (Crossing gains 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).
    • Checks. graph::check gains 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.rs G5 compares states, end lines and storeys near each border. A table test in graph/tests.rs covers the ladder boundaries.
    • Verified in the code, against the issue's wording:
      1. The plan digest of requests hashes {:?} of the whole WayGraph, so it changes by construction. The proof of "no pixel change" is new digests of the near records and of the face words in the requests index (one tooling commit, run on the base and on the head), the far block digest, and check-bytes.sh (native = WASM) on the head.
      2. Nothing outside transport and the debug tool reads graph.crossings, so a new kind changes no face.
      3. A way without a deck tag has no deck depth in the tiles: I use its deck_least_m for deck(upper) (to confirm).
      4. The last tie key on step 3 is the span owner of the tiles (tile and feature index) at the crossing, not the first vertex: a part's first vertex depends on the cell (parts.rs trim).
      5. The block has no bore wall value: a bore stroke uses edge_band_m as its wall until GP12.4 adds one (to confirm).
      6. A graph way is one piece of one part. The DECK rule (step 3, deck_min_m) acts per graph way; the length between the A lines reads on through deck joints up to deck_min_m.

    Generated by Claude Code

  2. timohueser commented on Nov 11, 2026

    @timohueser
    OwnerAuthor

    GP12.1 deviations from this issue (PR #3367)

    1. Bore records do not insert their stations as samples: an inserted sample moves the samples of the way on top, and so the faces.
    2. The census counters are not in GraphStats: they cost WASM bytes and no viewer reads them. They are in the fixture helper (tests/fixture/mod.rs levels_counts) that the debug tool and the census binary share. T15's input is WayGraph.levels.deck_into_tunnel. The census binary has --levels (graph and levels only).
    3. deck(upper) of a way without a deck tag is its deck_least_m (to confirm).
    4. The last tie key on step 3 is the span owner of the tiles (tile, feature index), not the first vertex: a part's first vertex depends on the cell.
    5. A bore stroke's wall is edge_band_m: the block structures has no wall value.
    6. The DECK rule (step 3, deck_min_m) acts per graph way; the metres between the A lines read on through deck joints up to deck_min_m.
    7. The overlap area of r is capped at PLACE_M (16 m) along each way; the surface is linear between samples.
    8. An end line spans the stroke's half-width on each side.
    9. A level crossing is "at grade" by its kind; its room is recorded.
    10. Untagged ways that end on step 3 also get runs (HIDDEN under the body, OPEN elsewhere).
    11. WASM: the step adds 25,818 B of gzip, past the 25 kB of the whole block (the issue estimated 3 to 6 kB). The guard is raised to the measured size; this waits for the owner.

    Generated by Claude Code

  3. timohueser commented on Nov 11, 2026

    @timohueser
    OwnerAuthor

    GP12.1 after the review of PR #3367: changed deviations

    • graph::build does not call graph::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.
    • The sheets and storeys and the merging of end lines left this step (branch claude/gp12-1-later); the T15 data moved to the census helper; the check computes G7 to G9 itself.
    • The room's corners lie on each way's own curve (B1). OPEN allows the floor snap_height_m over 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.
    • The earlier deviation "WASM: +25,818 B, guard raised" is void.

    Generated by Claude Code

  4. timohueser commented on Nov 13, 2026

    @timohueser
    OwnerAuthor

    Done: merged into ground-plan as #3367 (states, end lines, storeys and the ladder, counts only).


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions