Skip to content

TrailView parts P1: the bake places the tunnel parts in the feature tiles #3678

Closed

Description

@timohueser

Status: approved

Part of #3651.

TL;DR

Goal: The feature bake decides the openings of each chain of tunnel ways, and the kind of part and the numbers at each opening, and writes them into the feature tiles as two new kinds of feature. Each opening record names the end of its OSM way exactly, so that the ground plan can draw the road up to an opening that lies inside the tunnel way.
Problem: Today the bake decides only the states of levels: from each end, a tunnel is open (O) up to the first point with room (at most 300 m), then a bore (B) for 30 m. No record says where a tunnel opens or which part stands there, so the device derives it.
Decision: A new module parts in host/obc-trailview-features runs after the levels pass. It finds the openings, measures the ground of the ground plan there and selects a part by the ladder of the epic. It writes a tunnel-tube line of two vertices per chord of each chain with a part, and a tunnel-end point per drawn opening, with values from a new table data/trailview/parts.json; each tunnel way gets a tag parts with the kinds of its chain's ends. A new function of the ground plan crate, graph::open, makes the stretch from the end of an OSM way to an opening that lies inside it a ground way; the measure uses it here, the viewer from P4 on. features_format stays 4. The tag levels of a tunnel way does not change.
Rejected: One line per chain with the numbers of both ends in its tags: a tile holds pieces of a long line, and a piece cannot tell a cut from a real end. New tunnel states in levels: without the feature bores nothing reads them (Facts). A match of a record to its way by distance: two tunnels can cross at other depths. The checks of the ladder: they need the builder of P3 (P7).
Systems: trailview
Contracts: specs/trailview-features.md (two new kinds, the tag parts of a tunnel way), specs/vectors/trailview-features.*
Size: L (a stored format, a new module of more than 500 lines, a layer revision)

Facts

  • The bake places all features, then levels::tags builds each zoom-16 cell of each zoom-13 tile with a road way with graph::build, and write adds the tags by feature id with Tile::bytes_with (bake.rs). The id of a way is its index in ways of bake.
  • level_tags::merge calls tunnel_states, which walks each chain (the extents, tag ends and links of Found) with open_max_m and body_m of plan.json. TunnelFound.tag marks an end where no tunnel way goes on; it does not say whether another way meets it.
  • Without the feature bores, graph::build_with never splits a tunnel way at the lines of its levels (graph/mod.rs, the call of level_tags::split with tunnels): a tunnel way keeps Level::Tunnel whole and draws no ground. The viewer links no bores, so it reads no tunnel way's levels. Storey 0 of faces reads no feature of the crate but bores. level_tags::split shows how a piece is cut at metres along its stroke (insert) and given another level.
  • A shallow tunnel under what the terrain leaves out (a building) already becomes a ground way in the bake (structures::shallow).
  • roads::polyline gives a way's curve with at most 10 m between vertices. roads.json gives per class bore_m (rail 6.5 m, road 5 m, path 2.6 m), half_m and grade.
  • A tile keeps each segment of a line that meets its square grown by 40 m whole, and one more vertex at each end. Heights are stored in centimetres. PLANNER_TRAILVIEW_FEATURES has revision 25 (planner.rs).

Plan

Words: the frame line is the line across the way where the tube starts. The cover at a station is the least ground over three points across it (the centre and both outer walls, at half + shell_m), less the floor. A station is covered when its cover is at least height + shell_m + cover_m. left is the side to the left of the way into the tube.

  1. Table. Create data/trailview/parts.json. Object groups, per group: classes (of roads.json), look, collar_max_m, wing_max_m, least_height_m. Values from the prototype: motorway (motorway, trunk and their links: concrete, 30, 8, 4.5), road (primary to living_street, road: concrete, 25, 5, 4.0), minor (service, track: concrete, 15, 4, 3.2), path (path, footway, cycleway, bridleway, steps, pedestrian, via_ferrata: rock, 10, 2, 2.4), rail (rail, light_rail, narrow_gauge, rack, funicular: masonry, 20, 5, 4.8). Object bake: margin_m 0.6, margin_narrow_m 0.3 (the inside half-width past the way's half_m, narrow where bore_m ≤ 3, as boreHalf of tunnels.ts), shell_m 0.5, band_m 0.6, coping_m 0.3, face_over_crown_max_m 6, cover_m 0.5, wing_ground_m 0.6, foot_m 1, underpass_max_m 60, pair_max_m 40, pair_max_deg 25, slab_m 0.5, same_tube_gap_m 1, same_tube_stagger_m 6, rock_cover_max_m 3, free_max_m 40, junction_shift_max_m 20. P3 adds design, looks and inside.

  2. Option. kinds::part_rows(&Value) -> Value keeps groups and bake. planner.rs passes it as the option parts and sets revision 26. step.rs parses it into parts::Rules, the new field parts of bake::Options.

  3. Chains. graph/level_tags.rs gets pub fn chains(found, links) -> Vec<Chain>, the walk of tunnel_states as a function of its own: per chain its feature ids in walk order with their metres from and to, and the point of each end. merge and tunnel_states do not change.

  4. Openings (a), parts::openings. The pass reads the other ways at each end from ways (a way whose vertex lies on the end point, by geometry::key) and their outer half-widths (options.widths.way(kind, tags, false).outer_m()). Each chain end gets an opening at its end vertex. Where three or more ways meet there, it moves in along the chain to the first metre where both ends of the frame line lie outside the outer half-width of each other way at that node, at most junction_shift_max_m. A tunnel always has an opening at each end: an end that meets no way gets one too.

  5. Ground plan: open stretch. host/obc-ground-plan/src/graph/open.rs: pub struct OpenEnd { way: GlobalPoint, shift_m: f64 } and fn open(cell, parts, input, samples, plan, ends: &[OpenEnd]) -> Plan: for each tunnel piece of a feature whose first or last vertex is exactly way, it inserts a sample shift_m metres along the stroke from that vertex (as split does) and gives the stretch between Level::Ground, so it crosses, joins and takes its cut and fill as the ground way that it is. graph::build_open(cell, input, rules, levelled: Option<f64>, ends) runs it in build_with before the crossings, whatever the features; build and build_levelled pass no ends. A test: a cut tunnel way gives a ground piece of shift_m and a tunnel piece.

  6. Measure (b), parts::measure::site(opening, cells) -> Site. For each cell that holds a point up to collar_max_m + 2 inside or wing_max_m beside the frame line: the cell's input from the bake's tiles with the tags of the levels pass (Tile::bytes_with), graph::build_open with the decks' edge_band_m and the OpenEnds of every opening of step 4, faces::records::near_under, and the height by faces::heights::check::at; one cache of record words per job, as levels::cells_of. The result depends only on the crate's sources and on bores, which builds bore covers on storey 0: the obc data binary does not enable it, the step writes ground_plan_bores (obc_ground_plan::graph::BORES, now pub) into its metrics so that a release shows it, and P8 deletes the feature. A Site holds: half (half_m + widening + margin) and height (bore_m) of the widest way of the chain, one section for the whole tube; the cover per metre inside; the ground per metre along the frame line out to half + shell_m + wing_max_m; the lowest ground under these; the crossings where the chain is the lower way (Crossing::ladder, room_m); whether a building ring holds the centre line; the lowest underside of a bridge deck (its height less its tag deck) over the frame line.

  7. Ladder (c), parts::ladder returns per end every kind that fits, in the order of the rungs; the records take the first, and P7 takes the next one after a failed check:

    1. A vertex of unknown height: no part.
    2. An end within half + same_tube_gap_m across, same_tube_stagger_m along and pair_max_deg of an end of a wider chain: no part. The wider chain's axis stays; its half grows to the farthest edge of either way, plus the margin.
    3. Shorter than underpass_max_m, a way or a track on top: box at both ends, inside height = clamp(least room_m − slab_m − shell_m, least_height_m, bore_m). Under a building only: no part; the tunnel way stays undrawn, as on develop (out of scope in the epic).
    4. An end that meets no way and is covered at its end vertex: free.
    5. An end whose first covered metre lies within collar_max_m: an end of another chain of the same family (rail or not) within pair_max_m and pair_max_deg gives pair (the nearest pairs first, each end in one pair at most, as twins of tunnels.ts); else a path or minor end covered within rock_cover_max_m gives rock; else arch.
    6. Else free.
  8. Numbers. collar: metres to the first covered metre; for free, min(free_max_m, half the chain, that metre), 0 at a covered end. face: max(height + shell_m + band_m, highest ground on the frame line − floor + coping_m), at most height + shell_m + face_over_crown_max_m, and under a deck's underside less coping_m. left, right: per metre out from the frame's outer edge, ground + coping_m − floor, at most face; a row ends before the first metre whose ground lies under floor + wing_ground_m, or at wing_max_m, and has one value at least. foot: the lowest ground − foot_m − floor. In a pair, the frame line of the opening farther in holds both openings, and left and right start at the outer edges of the pair.

  9. Records, parts::records, placed after the sea, min_zoom 13. A tunnel-tube line per chord of a chain with a part: the chain's curve (roads::polyline of its ways, joined) from opening to opening, with a vertex at each opening, gives the chords; each record has two vertices, in the direction of rising metres along the stroke of its way. A line of two vertices stays whole in each tile that it meets, so a record knows its own metres and needs no knowledge of a cut. z is the floor, the road solver's height. A tunnel-end point per opening with a part, at the frame line's middle, z the floor there: two per box chain, one per arch, rock or free end, one per pair (at the opening of the lower feature id; the mate's opening has none). Tags, metres with at most 2 decimals, rows separated by a space:

    Tag On Value
    section both round, or box for an underpass
    half, height both inside half-width and height
    look both concrete, masonry or rock
    class, surface tube the roads.json class and the surface tag (when it has one) of the chain's widest way: the inside and the paint
    road tube the half-width of that way's carriageway
    along tube its metres along its stroke at the first vertex; none on a way with no alignment
    ends tube the part of the chain's two ends, the end at its first opening first, for example arch free
    part end arch, pair, rock, box or free
    heading end radians from x to y of world coordinates, into the tube (as Plan::tangent)
    collar end collar length; the shell length of free
    face, left, right end step 8; not on free
    foot end step 8
    way end the end vertex of the OSM way that the opening belongs to, x y in frame units of the ground plan (2^34 per side): the vertex as the zoom-13 tile stores it (quarter units times 32; whole units times 128 on a way with no alignment), so the reference is exact
    shift end metres along that way from way to the opening (step 4); 0 where it did not move
    mate pair metres to the left from this axis to the mate's axis
    mate_way, mate_shift pair way and shift of the mate's opening
  10. Tags of the ways. write adds to each tunnel way of a chain with a part, beside its other tags by id, parts: the part of the chain's two ends, as the tube's ends. The tag levels of a tunnel way: P1 to P7 do not write, change or read it; P8 deletes it with bores.

  11. Contract. specs/trailview-features.md: three rows in the table of Structures (the two kinds and the tag parts), and a section "Tunnel parts" ("Parts" names the parts of a geometry) with the ladder, the tags and the place of the kinds in the order of features. Add a tunnel-tube and a tunnel-end to the vectors. The ground plan ignores both kinds.

  12. Tests, parts/tests.rs: each rung on a small chain; the tags way and shift of a moved opening; a record keeps its two vertices and its tags after a tile cut.

Files

  • host/obc-trailview-features/src/parts/{mod,measure,ladder,tests}.rs: create.
  • host/obc-trailview-features/src/{bake,lib,step,kinds,levels}.rs: change.
  • host/obc-ground-plan/src/graph/{level_tags,mod}.rs: change: chains, build_open, BORES public. graph/open.rs: create.
  • data/trailview/parts.json: create. tools/testing/suites.toml: add it to the triggers of obc-trailview-features.
  • host/obc-data-steps/src/planner.rs: change: option parts, revision 26.
  • specs/trailview-features.md, specs/vectors/trailview-features.{json,bin}: change.
  • builder/web/tests/browser/trailview/fixture/: change: the feature tiles rebaked with make-fixture.py.

Done when

  • obc test -p obc-trailview-features, -p obc-ground-plan, -p obc-data-steps; obc exec cargo clippy -p <each> --all-targets -- -D warnings; cargo fmt --all; in builder/web npx vitest run src/lib/trailview/stream/features.test.ts.
  • A test of the bake on the fixture shows that every levels tag is the same before and after P1.
  • The pull request gives the count of each rung over the 1,403 tunnel ends of test box B beside the prototype's (parts/proto/data/place-stats.md), with a reason for each difference over 10 %, and the bake time before and after.
  • Before a production update of the feature tiles: today's app pictured before and after on the new tiles at tunnel entrances, underpasses and bridges.

Deviation from the epic

  • The epic calls the new spec section "Parts"; that name already holds the parts of a geometry, so the section is "Tunnel parts".
  • The epic makes an underpass and a pair one placement each. The bake decides each as one placement, from one measure, but writes it as several records: a tunnel-end per drawn opening and the chords of each tube. A tile holds only what lies near it, and each record must stand alone in a tile.
  • The epic's P1 writes the portal lines P, B and H into the tag levels of the tunnel ways. Here the tag stays as on develop until P8 deletes it: the viewer links no bores and so reads no tunnel way's levels, and the placement already holds where each tunnel opens. The one fact that the ground plan needs, the open stretch to a moved opening, lives in the tunnel-end record (way, shift) and in graph::open.

Deviation in the build

  • Chains from the vertices (Plan 3). The bake builds the chains from the exact vertices of the ways of the kind tunnel: a chain goes on through each vertex where the ends of two such ways meet and no other such way has a vertex; an end opens where it meets no other such way. level_tags::chains (the walk of the cells' tag ends and links) is not added. Reason, measured on test box B: the cells' links come from the graph's snapping and two cells can see a node apart, so the walk put 14 ways in two chains, missed 10 real portals (one of them a 6.5 km trunk tunnel), and, with a filter of the false tag ends, lost 60 real portals. The vertices give one answer, and way is a vertex anyway. merge and tunnel_states do not change; level_tags.rs changes only by the cut that split and open share.

  • Shallow tunnels. A shallow tunnel (a way of the kind tunnel in the map that the bake lays on the ground, structures::shallow) belongs to no chain: it is a way on the ground in the new roads, so a chain that meets it opens there. The design counted these ends in rung 3 ("under a building only").

  • Forks. A chain end where another tunnel way has a vertex (a fork, a cross passage) is no opening: no part, and the tube record runs to that end vertex. The design gave each chain end an opening.

  • Order of ends and parts. The end behind the record's first vertex comes first, in the rising metres of its way, so a single record reads it. none names an end with no part of its own (rung 1, rung 2, a building, a fork).

  • Wall tops of left and right are at least coping_m: the formula of Plan 8 gave tops under the floor where the ground falls at once.

  • Face under a deck. A deck caps face only where its underside less coping_m lies over the floor: a way that goes on from the opening onto a bridge lies at the floor, not over the opening (it gave negative faces on test box B).

  • Collar. Of box: the first covered metre, at most half the chain. Of pair: the larger of its two tubes, after the move.

  • Shift. A junction moves an opening at most junction_shift_max_m, half the chain and the length of its own way, so way and shift stay on one way.

  • Pairs. Only two openings that both reach rung 5 pair. Where the nearer one's way does not reach the frame line of the other within those limits, it does not move.

  • Measure. graph::levels runs on the measure's graph after its faces, for the ladders of the ways on top only; the faces do not read them. The other ways' strokes for the junction shift are their polylines (roads::polyline).

  • Code. levels.rs gives the measure its cell reader and job pool (Reader, run). The measure builds each cell that it reads once (jobs by zoom-13 tile).

  • The point of a tunnel-end (Plan 9 says "at the frame line's middle"): the point lies on its own axis at its opening. For a single opening that is the middle of its frame line; the frame of a pair runs from the right edge of one tube to the left edge of the other, so its point is not the middle of the pair's frame.

  • Junction (Plan 4). "Three or more ways" counts arms: the end of another way is one arm, a vertex inside it two, so a tunnel that ends at the side of a through road (a T) moves in too.

  • Measure twice (Plan 6). The ladder reads a first measure with the stretches of all openings. The numbers read the stretches that the records open (the openings with a part, a pair's mate included): the openings near a stretch that the first measure opened otherwise, among them each moved pair, are measured again.

  • A pair that does not reach. Where the nearer opening's way does not reach the frame line of the other within pair_max_m, half the chain and its own way, the two are no pair: each takes its next kind.

  • Openings that would meet. Where the shifts of a chain's two openings would reach past each other, both openings stay at the ends of the chain (shift 0) and take the ladder as every other end, so each chain keeps its openings.

  • Second measure and kind. Where the ground of the second measure no longer fits the kind that the first measure chose (no cover, or cover past collar_max_m), the end takes its next kind, and a pair with such an end is no pair. The step's metrics count these ends.

  • parts.json (Plan 1) has two more values: a group flag rock (true for minor and path) and bake.narrow_bore_m 3 (as boreHalf of tunnels.ts).

Requirements: none


Generated by Claude Code

Activity

  1. timohueser commented on Nov 19, 2026

    @timohueser
    OwnerAuthor

    Build: the algorithm and its invariants

    Both unproven points hold (tests on the branch claude/trailview-3678-parts-placements):

    • (a) graph::open cuts a tunnel way shift_m from an end vertex with the code of level_tags::split (one shared assembly of the cut stretches). A test builds a tunnel with two open ends and the same tunnel with a levels tag "O 7.5 P B {len − 5} P O" under bores: the two graphs have the same ways and samples, bit for bit. open finds the cut by the span lengths from the vertex, so it also holds on a way with no alignment.
    • (b) tiles::frame_point uses the rounding of the tile cut itself. A test reads each tile with the ground plan's reader: every vertex is the same point, on ties of the quarter and the whole unit and on a whole vertex.

    Algorithm (after the levels pass)

    1. Chains. level_tags::chains walks each chain from each tag end over single links, as tunnel_states. The bake splits a chain where a feature is not of kind tunnel: a shallow tunnel is a way on the ground in the new roads, so it gets no part. A chain end is an opening when no tunnel way goes on there (a tag end) or when it borders such a ground way. An end where two or more tunnel ways go on (a fork in the hill) has no opening.
    2. Curve. The polyline of the chain's ways (roads::polyline), joined, with the floor height, the metres along the chain and the stroke metres of each way.
    3. Openings. At the end vertex. With two or more other ways at the vertex (geometry::key), the opening moves in to the first whole metre where both ends of the frame line (±(half + shell_m)) lie off the outer half-width of each other way, at most junction_shift_max_m.
    4. Same tube (rung 2) and pair candidates come from the positions and headings of the openings, before the measure. So the measure knows how far across and how far in to read.
    5. Measure. One job per zoom-13 tile, as levels::cells_of. Each cell that holds a point to read is built once per job: build_open (levelled, with the OpenEnds near the cell), records::near_under, then graph::levels on the same graph for the ladders (after the faces, so the faces do not read them). Ground = check::at on those records. Read: the cover each metre in; the frame row each metre across; the decks that cross the frame row; the ladders where a way of the chain is the lower way; the building rings over the centre line.
    6. Ladder → numbers → records. As in Plan 7 to 10. The ladder returns every kind that fits, in the order of the rungs, with free last.

    Invariants (one focused test each)

    • I1 open: the stretch from the vertex to the cut is a ground way and the rest stays a tunnel. An end at no tunnel vertex changes nothing. (done)
    • I2 way is the ground plan's own point of the vertex in every tile. (done)
    • I3 Each rung on a small chain gives its kind, and the list of kinds keeps the order of the rungs.
    • I4 A moved opening carries way = the end vertex and shift = the metres along to it. The ground plan cuts there.
    • I5 A tube record has two vertices in the rising metres of its way, and a tile cut keeps it and its tags whole.
    • I6 The tag levels of every way is the same before and after P1 (the bake test on the repo fixture).

    Case distinctions that remain, with the reason

    The rungs of the ladder (the design). A shallow chain (no part: the ground plan draws it on the ground). A fork end (no opening: the tube goes on). Chains with fewer than two openings write the tube from the end vertex.

    Open points for the build, decided as defaults. Each one goes under Deviation if it holds:

    • ends and parts give the end behind the first vertex of the record first, in the rising metres of its way, so a single record can read them. An end with no part of its own is none.
    • The collar of a box is the first covered metre, at most half the chain. The collar of a pair is the larger of its two tubes.
    • One limit for P4: graph::parts trims spans more than two spans off a cell's grown square. A cell whose grown square ends within shift of the end vertex does not see the vertex, so the stretch stays a tunnel in that cell. This is more than 170 m from the square of the cell. The measure is not affected: its cells hold the vertex.

    Generated by Claude Code

  2. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    P1 is merged with #3732.


    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