Skip to content

TrailView ground plan: tunnel openings, bridge ends and level crossings break often because the device derives each shape #3651

Open
6 of 11 issues completed

Description

@timohueser

Status: approved

Part of #3096. The owner chose the direction on 2026-11-18, approved the TL;DR below, and approved the approach again after the pictures of the prototype.

TL;DR

Goal: Each tunnel end, underpass and level crossing of TrailView is one of a small set of finished parts. The data bake selects the part, sets its size and its place, and the device only draws it. A tunnel always has an opening and goes through, and a bridge always has a passage below it.

Problem: On the new roads (the TrailView view with the address switch ground=plan), the device derives the shape of each tunnel opening from the general rules for the ground. 266 of 1,014 test entrances fail after about ten rounds of work: concrete triangles between twin tubes, fins beside an opening, slabs in an opening, a tunnel that stops at a wall after 30 m. The bake and the device decide the same facts, and the device decides them two times (in Rust and in the shader), so the answers sometimes differ.

Decision:

  1. Parts. A part is a 3D model that code makes from a few numbers (width, height, lengths, wall heights). The set has about 13 kinds of part for tunnel ends (see Facts) and 3 for level crossings. Concrete, masonry and rock are looks from a rule table, not kinds of part.
  2. The part fits the hill. The bake does not change the stored terrain. It measures the terrain at each opening and sets the numbers of the part: the frame of the opening has a fixed design; the collar (the first metres of the tube, which stand out of the hill) is as long as the hill needs; the walls rise to the ground. Where the hill does not cover the tube, the tube shows its own outer shell.
  3. The device removes the ground inside the part. The terrain draws nothing in the volumes of a part (the rule that today's app has for its portal boxes). The ground plan (the mesh of the ground near the eye on the new roads) gets a face that the part owns, where it makes no ground. The part is a closed solid that goes into the ground, so no gap opens and nothing is in the opening, at every level of detail.
  4. An underpass is one part: both openings, the tube and the wing walls, under the way, the track or the building on top. Its height comes from the room under that way. Half of all tunnel ends are underpasses.
  5. The tube goes through, from opening to opening on the line of the way, with one cross-section, a lamp at regular distances, and a light value per vertex that falls with the distance from the nearest opening. Between its openings the floor of a tube touches nothing else, so the bake lowers it under a way that crosses on top. The way on top is never cut. The placement holds this floor; the heights of the way in the tiles do not change, so today's app draws what it draws now.
  6. The bake proves each choice. It builds the place with the selected kind of part and runs checks (the opening is clear, the wall heights are in range, the part is closed against the ground). If a check fails, it takes the next simpler kind of part. The last one is a free tube end: its shell reaches below the lowest ground under it, so it needs nothing from the ground. The bake checks it too, and a failure there fails the gate of the bake; it is not passed in silence. The kind of part can change in this way. The kind of structure never changes: a tunnel stays a tube with two ends.
  7. One answer for each fact. The bake decides where a tunnel opens, the shape and the size of the opening, the floor heights in the tube, the light in it, the end line of a bridge deck and the place of crossing equipment. The device decides only what depends on the eye: what it draws, and at which detail.
  8. Bridges get only the bake rule "a bridge keeps its passage" now (TrailView features: a short bridge over a way loses its deck (the passage below is walled up) #3639). A part for bridge ends comes after the tunnel parts prove the method, and only if it removes the faults of TrailView ground plan: a deck and its ground stub meet on one line (shards at deck ends) #3484.
  9. Level crossings get their equipment as parts here (a barrier with a raised arm, a light with a cross, a cross). The rails through the road belong to the railway step of the road rebuild (TrailView ground plan GP13: railways and steps: rails, sleepers, rack and cable, platforms, level crossings with gates and lights, step treads #3106).

Rejected:

Systems: trailview; planner-map-baking if the meshes get a layer of their own.
Contracts: specs/trailview-features.md (the records of the placed parts, the tunnel states of the tag levels), specs/trailview-tiles.md (the baked structure meshes).
Size: L (the feature bake, the ground plan crate, the viewer, a contract change)

Facts

From develop 6140c65 and from a census of test box B (Central Switzerland, feature tiles of revision 25). The census files are on the owner's PC: /media/timo/OSM1/tmp/ground-plan/parts/census/ (CENSUS.md, tunnel-ends.csv, level-crossings.csv, bridges.csv, pics/INDEX.md).

Today's code:

  • Today's app (no switch) has a fixed portal and a tube through the whole tunnel with a lamp each 10 m: structures/tunnels.ts. The terrain draws nothing in the box of a portal: terrain/portal-box.wgsl. Its faults: the sizes are constants, the portal stands at the end of the OSM way whatever the terrain does, and the opening is a dark face where the terrain draws coarser than level 17.
  • The new roads build tunnels in the ground plan crate behind the feature bores (host/obc-ground-plan: faces/mod.rs, faces/cover.rs, mesh/shell.rs, graph/levels.rs, graph/level_tags.rs), with a second copy of the height rules in terrain/heights.wgsl and plan/corners.wgsl. The feature is off in the viewer on develop.
  • The bake already makes meshes for the device: the layer trailview-stamps holds the structure meshes of each zoom-15 node (specs/trailview-tiles.md, section Stamps). Bridges, tunnels and galleries are about 25 kB (gzip) for a zoom-13 tile that has structures.
  • The bake already adds point features with a solved height (bridge-pier, catenary-mast), and the viewer draws point kinds as instances. The kind level-crossing is in the tiles with its barrier, light and saltire tags. Nothing draws it.
  • The road solver holds the end of a tunnel within 5 m of the terrain (specs/trailview-features.md, Heights). So at the end of the OSM way the floor is near the terrain, and the hill reaches the crown only some metres inside.

The census:

  • 1,403 tunnel ends in 636 chains (tunnel ways that meet end to end).
  • 690 ends (49 %) are underpasses: a chain shorter than 60 m with a way, a track or a building on top. 431 are for paths, 318 for roads and tracks, 23 for railways. 196 lie under a building only; there the terrain gives no room, so the height must come from the building.
  • 563 ends (40 %) are entrances into a hill. The distance from the end of the OSM way to the first point where the terrain covers the crown over the full width: median 4 m, 75 % within 10 m, 90 % within 17 m, 6 % past 25 m, 8 % never. Roads and motorways have the largest values (median 7 m to 8 m, 90 % within 29 m to 37 m).
  • 339 ends have a parallel end within 30 m. 180 of them are in the same tube (a footway that OSM maps beside the road, a second track, two carriageways nearer than their widths). 159 are separate tubes (motorways: median 15 m to 19 m apart; railways: 7 m).
  • 99 ends meet no way, 74 lie under a bridge deck, 77 are at a junction, 49 meet a bridge (31 of them motorways), 307 have a low way or building on top within 30 m.
  • A second table of the census gives each end one kind of part, by the first rule that fits; it sums to 1,403 ends. Its classes are not those of the lines above (a box also takes the short chains with nothing on top and some entrances with a low way on top): path underpass 431, road underpass 318, rail underpass 23; road arch 78, wide arch for a motorway 50, twin head wall 30, rail arch for one track 63, rail arch for two tracks 32, narrow rail arch 32, path arch 53; path opening in rock 106, track opening in rock 21; free tube end 80; gallery end 41; a footway in a road tube, which needs no part, 45. 132 of the ends (9 %) have a property that their kind fits badly.
  • Level crossings: 232 places (road 82, service 62, track 27, path only 53). 44 have barriers in their tags, 81 have the tag "no", 21 have a light. On the new roads no rails draw, at a crossing or elsewhere.
  • Bridges: 2,296 chains. The known faults on the new roads are 74 bridges with no deck (TrailView features: a short bridge over a way loses its deck (the passage below is walled up) #3639), and shards and fins at some deck ends (TrailView ground plan: a deck and its ground stub meet on one line (shards at deck ends) #3484). In 8 sample places the new roads draw most bridge ends better than today's app.

The phone:

Prototype

A prototype rendered 11 places of test box B with parts (2026-11-18; branch claude/parts-prototype-throwaway, never merges). A script took the part and its numbers for each of the 1,403 tunnel ends from the feature tiles and the stored terrain, by general rules. The viewer drew the parts from that file. Each sheet shows today's app, the new roads of develop, the prototype with a collar (the opening stays at the end of the OSM way) and the prototype with the opening moved into the hill. The pictures and the notes on each are on the owner's PC: /media/timo/OSM1/tmp/ground-plan/parts/proto/pics/INDEX.md, sheets-full/; the rules and the numbers: parts/proto/STATE.md, data/place-stats.md.

What it showed:

  • The ground in the part is solved. The box rule of the terrain, and the same boxes for the mesh of the ground plan, gave a clear opening at each place. No wall, slab or slope was in an opening.
  • Correct: a road into a bank (386), a road into a hillside with the hill 24 m inside (217), a rail entrance (492), a road underpass as one box (194; the road on top is whole), a track underpass (18), a free tube end along a cliff (622).
  • Not correct: the two openings of a pair of tubes got two head walls that do not join (717, 642). At a motorway entrance a tree stands in the opening (539). The wing walls of an underpass end in a high face (194). A free tube end at 499 ends at a ragged edge of the ground.
  • The collar is better than the opening in the hill. Where the hill covers the tube within about 5 m, the two look the same. Past that, the opening in the hill needs a cutting with walls of 8 m (median) and more than 11 m at one end in ten. A collar is not visible from the road up to about 10 m. At 24 m on a hillside it looks like a gallery.
  • The stored terrain has no cut for the road. Measured on it, the hill in front of an opening buried the head wall. The prototype needed walls beside the road in front of the opening.

What the build takes from it:

  1. The opening stays at the end of the OSM way, with a collar up to a limit of its class. The limits of the prototype are the start: motorway 30 m, road 25 m, service way and track 15 m, path 10 m, railway 20 m; the collar of 24 m at place 217 is one of the pictures that the owner approved. An end that needs more gets the free tube end. With these rules the 1,403 ends are: 368 arch entrances, 120 ends in pairs, 310 underpasses (one part for the two ends of a chain; the second end is in the 359 below), 203 free tube ends (156 in a chain that the hill never covers, 47 past the limit), 359 ends with no part of their own (310 second ends of underpasses, 49 ways in the tube of a wider way), 43 with no part (galleries, no heights).
  2. The bake measures the hill against the ground with the road's cut in it, not against the stored terrain.
  3. A pair of tubes is one part with one head wall. An underpass is one part.
  4. No plant and no object stands in the volumes of a part.
  5. The checks of the bake test a real property (the opening is clear, a wall is not higher than a limit). In the prototype the wall heights had a cap, so no check could fail.
  6. The looks need work: the colours, the ends of the wing walls, the frame.

Plan

This change is an epic. Each line below becomes one sub-issue and one pull request into develop. A sub-issue gets its own short design before its build. The sizes are estimates.

Words: a placement is the record of one placed part: its kind, its point and direction, and its numbers. A chain is the tunnel ways that meet end to end. The ladder is the ordered list of parts that the bake tries for a place.

  • TrailView features: a short bridge over a way loses its deck (the passage below is walled up) #3639 P0: the bake never makes a bridge a ground way (rules 1 and 2 of that issue, and no lower limit for the length of a deck). It does not depend on the other items. (S)
  • TrailView parts P1: the bake places the tunnel parts in the feature tiles #3678 P1 Placements in the bake. A new module parts in host/obc-trailview-features works on each chain in three steps. (a) The openings: at the two ends of the OSM chain, moved along the way only past the paved outline of a junction at the end. (b) The measure: the width of the way, a parallel tube, what is on top and the room below it, a deck above, and the ground along the first metres of the tube and beside the approach. The ground is the height function of obc-ground-plan for the cells there, built with the ways that end at the openings of step (a); the bake links that crate now and builds each cell for the tag levels, so this adds no new dependency. This ground has the cut of the road in it and is what the device builds. (c) The ladder: the kind of part and its numbers. The limits and sizes of each class and kind of part come from a new table data/trailview/parts.json, which is an option of the step. The module writes the placements into the feature tiles as features of new kinds with tags; features_format stays 4 if the tags hold them. The tag levels of a tunnel way then holds a portal line P at each opening of its placement and the state B between them; a chain with no placement has the state H; the state O of a tunnel and the open stretch go. Rules: a pair of tubes is one placement; an underpass is one placement for the chain; a way in the tube of a wider way has none. specs/trailview-features.md gets a section Parts, and the test vectors get a tile with placements. A new revision of the layer. (L)
  • TrailView parts P2: the bake lowers the floor of a tube under the ways on top #3679 P2 The floor of a tube. In the same module, a pass fixes the floor heights of each chain between its openings: under each way and track on top, the crown lies at least a slab below it; where the grade limit of the class does not allow that, the section gets lower, to the least height of its class. The way on top never moves and is never cut. The floor is a row of heights in the placement. The heights of the tunnel way in the tiles stay as the road solver made them, so today's app does not change. This replaces the rule of TrailView features: a tunnel portal lies behind the last point where a way on top has no room #3635. Depends on P1. (M)
  • TrailView parts P3: a crate builds the parts, and the stamp code runs it as WASM #3680 P3 The builder of the parts. A new crate host/obc-trailview-parts (a pure function with no I/O and no threads, as obc-ground-plan is) makes from the placements and the lines of a zoom-15 node: the meshes of the parts in the vertex layout of the structure meshes, the volumes in which the ground does not draw (a list of boxes in the form of today's portal box, several for one part), the floor segments for the walking camera, and per vertex the share of daylight, which falls with the distance to the nearest opening. The design of this sub-issue names the field of the vertex that holds that share; it adds no binding and no table of lights. First kinds of part: the arch entrance with a collar (road, wide, rail), the tube with lamps. The stamp code of the viewer calls the crate as WASM, in the stamp worker and in the bake alike: the bake of the layer trailview-stamps runs that code in Node, so a baked node stays equal to the node that the worker makes. The WASM bytes become part of stamp_version (builder/web/vite/stamp-bundle.ts), and specs/trailview-tiles.md says so. Depends on P1. (L)
  • TrailView parts P4: the new roads draw the parts #3681 P4 The viewer draws the parts on the new roads. With ground=plan, structures/node.ts takes the meshes of P3 in place of structures/tunnels.ts; the terrain takes the boxes of P3 for its box rule (terrain/terrain.ts, terrain/portal-box.wgsl, with a higher limit of boxes in view); the ground plan crate gives each part a face that the part owns and makes no ground in it (host/obc-ground-plan/src/faces), with no discard in the piece shader (as built: the bake cut is gone; the ground's triangles near a part's boxes drop their pixels in the boxes, and all other pieces draw without discard; the owner approved this on 2026-11-21); plants and objects keep out of the boxes; the walking camera reads the floor segments; the structure shader reads the share of daylight. The shader code stays plain, and the change gets one run on the owner's iPhone before it merges (TrailView on the iPhone: the terrain draws broken, the new roads do not start, and the first picture takes long #3656). Gates, measured against develop in the walk and drive flights: no new pass and no new draw per node; the frame time does not rise by more than the noise of the measure; the bytes of the stamp layer are reported, and a growth of more than 20 % needs the owner's word. The first pictures for the owner come from this item. Depends on P3. (L)
  • TrailView parts P5: the underpass part #3682 P5 The underpass part: one box for a chain under a way or a track, its two openings, its wing walls, its height from the room under the way on top. Depends on P4. (M) As built (TrailView parts P5: the underpass part #3769): one box part per chain; side-wall tops slope 1:1 into the bank, down to the coping; path underpasses are concrete. Known case: a head wall on a sloped line stands high (follow-up comment on this epic).
  • TrailView parts P6: the pair of tubes, the opening in rock and the free tube end #3683 P6 The pair part (one head wall for two tubes), the openings in rock for paths and tracks, and the free tube end. Depends on P4. (M)
  • TrailView parts P7: the bake checks each placed part #3684 P7 The checks of the bake. For each placement the bake builds the place with the crates of P3 and of the ground plan and tests it: no ground and no object in the opening, no wall higher than the limit of its class, the part closed against the ground. A failed check takes the next kind of part of the ladder. The free tube end is checked too; a failure there is counted and fails the gate. The count of 1,014 test entrances of the old method becomes a count over all ends of test box B, with a gate of 0 for ground or an object in an opening. Depends on P5 and P6. (M)
  • TrailView parts P8: the old tunnel code of the new roads goes #3685 P8 The old tunnel code of the new roads goes: the feature bores of host/obc-ground-plan (the faces, the cover and the lid, the shell, the end faces, the tunnel states O, B and H and their room tests in graph/levels.rs and graph/level_tags.rs), the tunnel terms of terrain/heights.wgsl and plan/corners.wgsl, the values open_max_m and body_m of data/trailview/plan.json. The item reports the size of the shaders before and after, for TrailView on the iPhone: the terrain draws broken, the new roads do not start, and the first picture takes long #3656. TrailView features: a tunnel portal lies behind the last point where a way on top has no room #3635 and TrailView ground plan: the ground over a tunnel must never replace a paved layer of a way on top #3595 close with it. Depends on P7. (M)
  • TrailView parts P9: level crossing equipment #3686 P9 Level crossing equipment. The bake places it at each place where a road, a service way or a track crosses a railway at grade, as point features with a heading; a crossing of a path alone gets none. One set stands at each approach of the way, on the right of the direction of travel, off the carriageway, before the first rail by a distance from parts.json. The set comes from the tags of the level-crossing point (the owner's rule of 2026-11-03 for a crossing with no tags): crossing:barrier full, half or double_half: a barrier with a raised arm and a light with a cross; no barrier tag or no, on a road: a light with a cross; on a service way or a track: a cross; crossing:light=yes adds the light. The viewer draws the sets as instances of kinds (builder/web/src/lib/trailview/kinds/, models/). Depends on P1 for the module only. (M)
  • TrailView parts P10: the guide, the looks and the pictures of all kinds #3687 P10 The end: the guide docs/content/software/trailview-roads.md gets a section on the parts; pictures of all kinds for the owner; the looks (the colours, the frame, the ends of the wing walls); the counts of P7 at their gates. Today's fixed portal (structures/tunnels.ts and the portal part of structures/node.ts) goes when the new roads are the default (TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110), not here. (M)

Not in this epic: a part for bridge ends (#3484). The owner decides on it after P7.

Order: P0 at any time. P1, then P2 and P3, then P4, which gives the first pictures. P5, P6 and P9 after P4, in any order. Then P7, P8, P10.

Files

Each sub-issue lists its own files. The areas:

  • host/obc-trailview-features/src/parts/: create: the measure, the ladder, the floor pass, the checks, the crossing equipment (P1, P2, P7, P9).
  • host/obc-trailview-features/src/bake.rs, tiles.rs, kinds.rs, stamps.rs: change: the new kinds, the placements in the tiles, the part meshes in the stamp layer (P1, P3, P9).
  • host/obc-trailview-parts/: create: the builder (P3, P5, P6). builder/ground-plan-wasm/ or a bridge of its own: change: the WASM entry (P3).
  • host/obc-ground-plan/src/faces/, graph/, mesh/: change: the face of a part (P4); delete: the feature bores (P8).
  • builder/web/src/lib/trailview/structures/, terrain/, plan/, kinds/, models/: change: the draw, the volumes, the camera floor, the kinds of the equipment (P4, P9); delete: the tunnel terms of the height shaders (P8).
  • data/trailview/plan.json, kinds.json, a new parts.json (the values of each kind and class: least height, collar limit, wall limit, looks): change and create (P1, P8).
  • specs/trailview-features.md, specs/trailview-tiles.md, specs/vectors/trailview-features.*: change (P1, P3).
  • host/obc-data-steps/src/planner.rs: change: the revision of planner/trailview-features (P1, P2).
  • docs/content/software/trailview-roads.md: change (P10).
  • builder/web/tests/browser/trailview/fixture/: change: the fixture tiles with placements (P1).

Done when

  • Each sub-issue has merged, and its checks pass: obc test -p obc-trailview-features, obc test -p obc-trailview-parts, obc test -p obc-ground-plan, and in builder/web the test files of the changed viewer modules.
  • The count of P7 over all tunnel ends of test box B is at its gate: no end has ground or an object in its opening, and no chain is drawn as anything other than a tube with two ends.
  • No way on top of a tunnel is cut in test box B (the part lidcut of the old count, over all ends).
  • The owner has seen labelled pictures of each kind of part, today's app | new roads, and has approved them. A pull request that changes how a tunnel or a bridge looks merges only after that.
  • Before a production update of the feature tiles, today's app is pictured before and after on the new tiles at tunnel entrances, underpasses and bridges.
  • The viewer with the parts compiles and draws on the owner's iPhone 13, or TrailView on the iPhone: the terrain draws broken, the new roads do not start, and the first picture takes long #3656 holds the reason why it does not yet.

Limits

  • The two costs that count are the frame time and the time to the first proper render. The target device is an iPhone 13, in a simple version with low detail if necessary. Memory on the phone counts too. Code size and bake time do not count much.
  • Most of the work belongs in the data bake. The device draws what the bake decided.
  • A structure never changes its kind.
  • The parts are general. No code names a coordinate.
  • The parts are simple and look finished. Round tunnel sections are the default; square sections exist too.
  • Imperfect road markings, rough banks and unusual crossings are acceptable. Torn ground, holes and hanging walls are not.
  • Today's app (no switch) does not change until the owner turns the new roads on for good. Its code path stays, and the items of the plan change no value of the tiles that it reads: the placements are new features, the floor of a tube is in the placement, and the tag levels is read only by the ground plan.

Out of scope

Requirements: none


Generated by Claude Code

Activity

  1. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    Two faults of the arch's geometry: #3762

    The review of P4 (a) (#3761) found two faults in the part that P3 builds. #3762 records them with a place on test box B
    and a proposed general rule for each:

    • The room folds where a chord turns tighter than its half-width.
    • Under a low deck, the head wall is lower than the opening's box.

    P4 does not repair them.


    Generated by Claude Code

  2. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    Follow-up from P5 (#3769): a head wall's top is one level at the highest ground on the opening's line + 0.3 m. On a sloped line (rail under a junction, 47.05705, 8.39532) it stands up to 7 m over the low side and its cap reaches the road. A possible general rule is in #3769 (issuecomment-7064879106): the top follows a line between the side walls' first tops, never under height + 1.1 m. It needs the mesh fold check to accept a peak in a wall top, and it changes 67 arch ends and 82 box ends on box B. The owner accepted the case as it is for now.

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