Skip to content

TrailView ground plan GP12.8: the heights contract for crossings, and the bake carries every shallow tunnel's tag #3349

Open

Description

@timohueser

Status: proposed
Part of #3105 (GP12, the crossing block of #3096). Two pull requests into ground-plan: part A (the bake's tunnel tag) and part B (the solver's rules), in that order.
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 heights contract), and on timosPC /media/timo/OSM1/tmp/ground-plan/crossings/CASES.md
sections 4, 5 and 8.3, drawings/x3-embankment.svg, HANDBACK.md section 6, and the solver study
/media/timo/OSM1/tmp/ground-plan/solver-dive/ (STATE.md, FOR-CROSSINGS.md, REPORT.md, the bakes runs/c2,
runs/c3). Code places verified on ground-plan ea4da43.

Goal

The drawing of this block is whole with any heights, but it is right only when the heights give the room. This issue
states what the heights must give the drawing, as one contract, and makes the bake keep every tunnel as a tunnel. It
is the solver's work, not the drawing's.

Depends on / blocks

  • Part A depends on nothing and can start now. It changes no pixel on either path, so it can merge early. It blocks
    the places under towns (R02, W5, R11) of GP12.4 and GP12.5, through the box B rebake.
  • Part B waits for the solver work to resume (the new solver is paused; the old solver's round 1 is the merged code,
    the demo data carries round 2). It reads GP12.1's counters for its proof.
  • Blocks: the GOOD verdicts of the places that the heights alone break (S4, N4, R09), and the room of the
    places on ladder steps 2 and 3 on today's data.

Design

Part A: the bake keeps the tunnel tag

  • Today a tunnel whose terrain lies less than its bore over it everywhere, and that rises nowhere more than 5 m over
    the terrain, loses its tunnel tag and becomes a way of its class on the ground, unless it lies under a road that
    the solver held up (shallow, host/obc-trailview-features/src/structures.rs:360; used in
    host/obc-trailview-features/src/bake.rs:345-357; the contract in specs/trailview-features.md, section
    Structures, "A tunnel whose terrain lies less than its bore …").
  • New: the bake keeps the way's ground kind, as today, and writes its tunnel tag back on it (tunnel=yes, or the
    mapped value). The tiles carry the tunnel tag on these ways and only on them (the ground kinds' tag lists of
    data/trailview/kinds.json keep tunnel for them).
  • No pixel changes, on either path. The viewer's default path keys on the kind (tv/terrain/bins.ts: TUNNEL only
    for the kind tunnel; the tag is read only for streams, tv/terrain/culverts.ts:159), so it draws these ways as
    today. The plan crate reads a tunnel tag on a ground kind as Level::Tunnel (classify, gp/graph/parts.rs:84)
    only from GP12.4 on; until then classify reads the tag only for water, as today. Then the drawing decides what
    shows (GP12.1's states): a shallow tunnel under a building (the terrain does not hold the building) is OPEN, a
    ground way as today, within open_max_m of its tag ends, and HIDDEN past that, with a closed line at each change.
  • The rule that leaves out a part of a tunnel that rises more than 5 m over the terrain farther than 20 m from its
    ends stays (floating, structures.rs:368).
  • A contract change: specs/trailview-features.md changes its sentence (the tiles keep the way on the ground with its
    tunnel tag). The fixture is rebaked in this pull request; the demo data of box B is rebaked when GP12.4 needs it, at
    a time the owner chooses (rebakes run through obc data).

Part B: the contract for the solver (CASES section 5)

  1. Order. At a crossing with a tag, the tagged role holds: the tunnel way lies under the way on top, a bridge way
    over the way under it. Where it does not, the drawing hides the tunnel way there (ladder step 3).
  2. Room, as much as can be reached. The drawing wants r >= full and draws an opening from r >= least
    (GP12.1: full = clearance_m + deck and least = clearance_least_m + deck_least_m of the class rows for a deck;
    bore_m + cover_m and bore_least_m + roof_least_m for a bore). The solver must never drop a clearance that it
    cannot reach in full ("whole or not at all"): it gives every decimetre that it can.
  3. Heights first. A tunnel sits low enough to have its cover. The drawing's ground lift over a bore (at most
    1.0 m, on free ground only) is the fallback, not the plan.
  4. A smooth way through a structure. No step and no bend of more than 2 % at an end line: the deck's first row
    continues the ground way. Inside a structure the way stays within the grade of its class (the solver's own rule,
    a structure at most twice its grade). No tent inside a structure (N4; a step of a metre at R09).
  5. No level for the ends. A structure end needs no terrain level; ramps and troughs beside a structure are
    wanted.
  6. A tunnel way stays at or under the terrain. A tunnel station over the terrain is not drawn.
  7. An upper way on a bank that the terrain model flattens (CASES 8.3; owner: "let's try C"). The order: take what
    the terrain gives (the highest terrain within one pixel under the upper way, the lowest under the lower way); the
    lower way sinks, by at most 3.0 m for a road and 2.9 m for a path; the upper way of a stiff class (a railway, a
    motorway) rises on its own bank for the rest, at its own class grade, also over the band of the ground ways
    (1.5 m in the new solver), but only within the ramp length of the crossing; what still lacks goes to the ladder
    (a thin bore, then closed). The rule's form is the solver's to write.
  8. A trough takes its neighbours with it (LEARNED 3a.9: at A1 a sink of 2.9 m tilts the roundabout 12 m away by
    about 1.2 m). Count the junctions within a ramp's length that a sink tilts, and show them; the owner decides from
    pictures whether a rule is needed.

Part B: the counts the drawing needs

Invariants

  1. Every tunnel of the tiles keeps its tag (part A). Check: a bake test on a synthetic shallow tunnel under a building;
    the count of ground-kind ways with a tunnel tag equals the bake's shallow count.
  2. Part A moves nothing else: every way's heights, grades and kinds in the tiles are bit-equal before and after, except
    the tunnel tag on the shallow tunnels (the road solver runs before the shallow rule, bake.rs:249 and :345-357).
    Check: a byte comparison of the z and grade columns and the kinds over the fixture tiles; the ground census rows
    equal; the default-path and plan-path views give the same bytes.
  3. No crossing loses a clearance that it can partly reach. Check: the solver's rows (solver-dive/rows.sh): the
    count of short crossings and their shortfall, per class pair, before and after.
  4. No step or bend over 2 % at an end line, no tent in a structure. Check: a census row of the solver.
  5. The order holds at every tagged crossing, or the crossing is counted. Check: GP12.1's inverted count.

Decisions already made by the owner that apply

  • Road under a railway on a flattened bank: "let's try C" (shared: the road down by at most 3 m, the railway bank
    raised for the rest).
  • Ground lifted up to 1 m over a shallow tunnel: okay, but "isn't the real solution to make the tunnel sit lower?" →
    heights first; the lift is only the fallback.
  • The owner's solver decisions on EPIC — TrailView ground plan: one engine for ways and water near the eye #3096: the band is the class's cut and fill limits; where the terrain data jumps
    the grade opens only to twice the class limit; two ground ways of different layers move apart only inside the band;
    unreachable clearances and dropped joins: the owner decides from pictures.
  • Climb estimates must never clearly undercount (climb-estimates-spot-on).

Not in scope

The drawing (GP12.1 to GP12.7). The terrain model itself (a cliff that the model does not hold: CASES 8.1).

Proofs and pictures required before review

  • Part A: the fixture's tunnel lines before and after; the crate's states on the fixture; after the box B rebake,
    the gallery of R02, W5, R11 (GP12.5).
  • Part B: the solver's rows on box B (solver-dive/rows.sh), GP12.1's ladder census on the new bake beside the demo
    data's, and the gallery (gallery/shoot.sh with the new features archive; about 25 minutes of GPU with BATCH=7)
    before and after, one before | after sheet per place.
  • The owner sees bridge and tunnel pictures before any solver merge (his rule).

Cost to measure

The bake's time over box B against the base (the epic's budget: less than 10 % longer); the moved ground ways (the
metres moved by a ramp, by more than 2 m); the tiles' bytes.

Risks and the stop rule

  • Option C may move a railway line over a long stretch. Stop and report with pictures if a railway or a motorway
    rises over more than the ramp length of its crossings.
  • Stop and report if part A changes more than the tunnels it should (another way's heights in the bake).
  • After two failed review rounds, stop and report.

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. changed the title [-]TrailView ground plan GP12.8: the heights contract for crossings, and the bake keeps every tunnel's tag[/-] [+]TrailView ground plan GP12.8: the heights contract for crossings, and the bake carries every shallow tunnel's tag[/+] on Nov 11, 2026
  2. timohueser commented on Nov 12, 2026

    @timohueser
    OwnerAuthor

    Part A: design note (before the build)

    Where the rule is. host/obc-trailview-features/src/bake.rs, the loop over the road ways after roads::solve_by_area and structures::bridges: a way of the kind tunnel that is no underpass and that structures::shallow accepts on every part gets the ground kind of kind_of(.., tunnel=no). Today the loop also removes the tunnel tag from tags before it writes the way. The contract is the sentence in specs/trailview-features.md, section Structures ("… the tiles keep it without its tunnel tag, as a way of its class").

    The change. The loop does not remove the tag. The kind is the same as today (it comes from the clone with tunnel=no). The road solver ran before this loop, so no height, grade or alignment can change. The spec sentence changes to: the tiles keep it as a way of its class, with its tunnel tag.

    Encoding. A plain tag of the feature in the tile: the pair (tunnel, yes) in the tag stream of the feature, as varint indices into the tile's string table (tiles.rs, Tile::add). The value is always yes: the kind tunnel of kinds.json matches only tunnel=yes, and its keep list holds tunnel, so the tag is in the exported tags already. The ground kinds' keep lists do not change: an added tunnel there would also write tunnel=building_passage and other values on many ways that are no shallow tunnels. Other features keep their tags; the string indices of a tile can shift where tunnel or yes is a new string in it, but the decoded tags of every other feature are equal.

    No revision bump. No reader reads the tag on a ground kind today (below), so a tile without it (all published tiles) and a tile with it give the same output. The revision tells obc data that the output improved; it improves only when GP12.4 reads the tag. The next rebake of box B (the revision 16 of #3337, or the bump of the step that first reads the tag) carries it. #3337 keeps revision 16. Only the fixture conflicts: the pull request that merges second rebakes the fixture.

    Readers of a way's kind and tags today, and why none changes.

    • Viewer, default path: terrain/bins.ts lineType keys on the kind (TUNNEL only for the kind tunnel); bins.ts addLines reads bridge, deck, highway, surface, junction, uphill, sidewalk*, never tunnel. terrain/culverts.ts:159 reads tags.tunnel only for kind === 'stream', so it cannot see the tag on a road. structures/tunnels.ts, structures/node.ts, roads/arms.ts, terrain/corners.ts: by kind or by the solver's lines, not by the tag. engine.ts feet.tunnel is the floor under the eye, not a tag. planner/trailview-first.ts reads layer and bridge. No code compares whole tag maps of road features.
    • Ground plan crate: tile.rs decodes all tags into Feature.tags. graph/parts.rs classify gives Level::Tunnel to a way only for the kind tunnel; it reads the tunnel tag only for water. So the Bore detection of graph/crossings.rs (a.level == Level::Tunnel || b.level == Level::Tunnel) and the levels of graph/levels.rs (tunnel(w) = Level::Tunnel and not water) do not see the new tag: no new crossing, no new state. sections.rs way(..) reads the class, surface, oneway, gauge, tracktype, width, rack; not tunnel. Two places read the whole tag map: graph/parts.rs joins a part with its own segment in the next tile only when kind and tags are equal (the tag is on every tile piece of the way, so this does not change), and graph/points.rs SegmentOrder sorts the parts of different features that hold one and the same segment by (class, kind, tags, …): that can change only where a shallow tunnel shares a segment with another way of the same class and kind. The digest proof checks this over the fixture.
    • Bake, after the rule: the ground census keys on the kind; the tracks (rails::masts, rails::platforms) read gauge, railway, electrified and filter tunnels by kind.

    Proofs. (1) Fixture bake against the committed revision 15 tiles: every feature decoded and compared, all fields except the new tag; the count of ways that gain it; tile bytes. (2) Plan digests of the 256 fixture cells (near records, face words, far blocks) and check-bytes.sh. (3) The feature-decoding unit tests; the shots are not needed if (1) and (2) are equal (the default path reads only the tile features, the plan path only the plan crate's words). (4) Box B bake, tagged count, the Kriens A2 tunnel, road vertices against the stored baseline. (5) The --levels census on the new box B tiles: expected unchanged, because classify does not read the tag yet.


    Generated by Claude Code

  3. timohueser commented on Nov 12, 2026

    @timohueser
    OwnerAuthor

    Part A built: #3382 (deviations)

    • The tag is tunnel=yes on the ground kind. No revision bump: no reader reads it before GP12.4, and the next box B rebake carries it.
    • The Kriens A2 tunnel at R02 (47.00829, 8.3049) is not a shallow tunnel on box B: it stays the kind tunnel (motorway, layer -2) in this bake, in the round 1 baseline and in the demo data. The motorway tunnels at W5 and R11 are not shallow either. So part A does not change what GP12.4 and GP12.5 see at these places; their faults come from the heights and the old tunnel drawing, not from the shallow rule.
    • Invariant 1 is exact on the fixture (11 shallow tunnels, 11 tagged features at zoom 13). On box B the bake counts 194 shallow ways, the tiles hold 188 tagged pieces at zoom 13 (163 groups after joining pieces that share a vertex).
    • Heights, grades and kinds: byte-equal on the fixture and on box B; plan digests (records, faces, far) equal on 256 of 256 cells; the levels census equal on 3,448 of 3,448 box B cells.

    I could not edit this issue's body from here; this comment holds the deviations.


    Generated by Claude Code

  4. timohueser commented on Nov 12, 2026

    @timohueser
    OwnerAuthor

    Correction after the merge of GP12.8 part A (#3382), from its proofs and its review (crossings/REVIEW-3382.md).

    The body of this issue says or implies that part A (the bake keeps the tunnel tag on a tunnel that the shallow rule turns into a ground way) unblocks the gallery places R02 (Kriens), W5 and R11. That is wrong. The motorway tunnels at those three places are of the kind tunnel in every bake (the demo data, round 1 and the new bake); the shallow rule never touched them. Their faults come from the road heights of the demo data and from the old tunnel drawing. On round-1 heights R02 is whole (crossings/gallery/r1-vs-today/).

    What part A does give: on the test box 194 shallow tunnels (mostly short tunnels under buildings) keep their tag, as tunnel=yes on a ground kind, so that the step that draws tunnels can see them. No reader reads that tag today.

    For the step that first reads the tag (#3345): tiles of feature revision 15 that were baked before #3382 do not carry it. That step must depend on a rebake (the revision 16 of #3337 or a later one) or raise the revision itself; otherwise regions on older tiles silently keep their shallow tunnels as ground ways.

    Also wrong in the body of #3349: "or the mapped value" (the tag's value is always yes) and that the ground kinds' keep lists include tunnel (they do not; the tag is written by the shallow rule itself).


    Generated by Claude Code

  5. timohueser commented on Nov 13, 2026

    @timohueser
    OwnerAuthor

    Solver points for part B of this step, from the owner's notes on checkpoint 5 (ground-plan 768d39e) and the diagnosis in cp5-notes/REPORT.md on timosPC. None is confirmed with a solver run yet.

    • Lucerne cycleway under the A2 (47.05445, 8.29627). The owner: the cycleway "should sit under all the roads. But it can't because the bridges also all sit a little too low". The deck chain falls to 426.7 m at the A2 tunnel portal, 6 m under the terrain. The rows that hold it low: a bridge never sags below the line between its chain ends; a crossing that asks more does not raise where the bridge lands; the tunnel sink row. Proposed rule: a bridge end that meets a tunnel is not a landing; clearance rows may lift it and the tunnel follows within its grade.
    • The A2 at Kriens and Luzern-Süd (47.0073, 8.3047). The owner: good now, but further on the motorway and the path beside it "cut a little deep into the ground", where they lie on the ground in reality; "look into it if it's a quick fix". The A2 lies 2.7 to 3.2 m under the terrain about 60 m from the portal, because the tunnel sinks a bore plus 1 m under the roads above it. Proposed rule: the sink row is hard only at the ladder's least room and soft up to full room, or the mouth becomes an open cut.
    • The footbridge with steps over the tracks in Lucerne. The owner: "why is it so high?" The joint of steps and footbridge stands 20 m over the rails (454.5 m); the rail clearance asks only for 440.9 m. The row that lifts it is not found; it needs a solver probe.

    Generated by Claude Code

  6. timohueser commented on Nov 14, 2026

    @timohueser
    OwnerAuthor

    A finding of GP12.3b part B (#3482) for this step's bake work: the Brunnen stack (p08-brunnen-stack-eye, -obl).

    What the viewer shows. The walkway under the road deck shows only where it leaves the road deck's footprint. Under
    the road deck it has no edge and no railing of its own.

    What the device builds. debug --storeys on box B at revision 19 (46.9908, 8.6107, 60 m): the storey mesh of the
    cell has parapets but no railing triangle in its square, so the walkway has no free outline of its own there.

    Most likely cause (not proven by a run that prints the storey of each way). The storey chain lifts a group only at
    a crossing that a cell owns. A walkway that runs along under a road deck has no crossing in the graph, so both decks
    lie on storey 1, and the one sheet of storey 1 gives the overlap to the road.

    Proposed rule for the bake. A deck whose stroke lies over another deck's stroke by more than a slab is one storey
    higher. This is the general form of the self-crossing case: an overlap, not only a crossing.


    Generated by Claude Code

  7. timohueser commented on Nov 14, 2026

    @timohueser
    OwnerAuthor

    A second note from the fix round of GP12.3b part B (#3482), on abutments.

    A bridge's abutment is now concrete, not stone: a step wall beside a bridge's ground stretch (a stub; its record line
    carries records::BRIDGE_GROUND), and a step wall within 3 m of a deck's stroke over storey 0 (its ceiling line, as at
    a junction at the deck's end; near_deck of plan/corners.wgsl). Their height is unchanged: where the stub or a
    junction lies at the deck's height over a low road, the wall stands taller than checkpoint 5's slopes
    (p-R11-hergiswil-tunnel, p-W1-link-over-cycleway). The owner flagged both views; their shape is this step's.


    Generated by Claude Code

  8. timohueser commented on Nov 15, 2026

    @timohueser
    OwnerAuthor

    From GP12.4 step 1 (pull request #3488, the tunnel rules A and B in the bake's levels): the closed tunnel mouths of
    test box B on the tiles of that bake (the census of 1,014 portals, the terrain that the bake reads). 20 stay closed,
    not 19:

    Cause Portals
    No cover within 30 m of the tag end (heights) P0005, P0075, P0171, P0172, P0501, P0539, P0623, P0727, P0820, P1006
    A way on top with too little room at the mouth (heights) P0193, P0295
    A path at the floor's height 1.6 m inside a bore that holds only by the lift (heights) P0692
    A station subway under a platform (a door is right) P0282, P0306
    The levels see no tag end at the portal (a node-map fault and a fork at the portal; see #3345) P0134, P0205, P0215
    Other, as in the diagnosis P0622, P0726

    Data: /media/timo/OSM1/tmp/ground-plan/tunnels/step1/logs/census-head.json, table logs/census-table.md.


    Generated by Claude Code

  9. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    Two leftovers of #3353 (closed) belong to the storey and heights rules of this issue:


    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