Repository navigation
Description
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::tagsbuilds each zoom-16 cell of each zoom-13 tile with a road way withgraph::build, andwriteadds the tags by feature id withTile::bytes_with(bake.rs). The id of a way is its index inwaysofbake. level_tags::mergecallstunnel_states, which walks each chain (the extents, tag ends and links ofFound) withopen_max_mandbody_mofplan.json.TunnelFound.tagmarks an end where no tunnel way goes on; it does not say whether another way meets it.- Without the feature
bores,graph::build_withnever splits a tunnel way at the lines of itslevels(graph/mod.rs, the call oflevel_tags::splitwithtunnels): a tunnel way keepsLevel::Tunnelwhole and draws no ground. The viewer links nobores, so it reads no tunnel way'slevels. Storey 0 offacesreads no feature of the crate butbores.level_tags::splitshows 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::polylinegives a way's curve with at most 10 m between vertices.roads.jsongives per classbore_m(rail 6.5 m, road 5 m, path 2.6 m),half_mandgrade.- 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_FEATUREShas 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.
-
Table. Create
data/trailview/parts.json. Objectgroups, per group:classes(ofroads.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). Objectbake:margin_m0.6,margin_narrow_m0.3 (the inside half-width past the way'shalf_m, narrow wherebore_m≤ 3, asboreHalfoftunnels.ts),shell_m0.5,band_m0.6,coping_m0.3,face_over_crown_max_m6,cover_m0.5,wing_ground_m0.6,foot_m1,underpass_max_m60,pair_max_m40,pair_max_deg25,slab_m0.5,same_tube_gap_m1,same_tube_stagger_m6,rock_cover_max_m3,free_max_m40,junction_shift_max_m20. P3 addsdesign,looksandinside. -
Option.
kinds::part_rows(&Value) -> Valuekeepsgroupsandbake.planner.rspasses it as the optionpartsand sets revision 26.step.rsparses it intoparts::Rules, the new fieldpartsofbake::Options. -
Chains.
graph/level_tags.rsgetspub fn chains(found, links) -> Vec<Chain>, the walk oftunnel_statesas 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.mergeandtunnel_statesdo not change. -
Openings (a),
parts::openings. The pass reads the other ways at each end fromways(a way whose vertex lies on the end point, bygeometry::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 mostjunction_shift_max_m. A tunnel always has an opening at each end: an end that meets no way gets one too. -
Ground plan: open stretch.
host/obc-ground-plan/src/graph/open.rs:pub struct OpenEnd { way: GlobalPoint, shift_m: f64 }andfn open(cell, parts, input, samples, plan, ends: &[OpenEnd]) -> Plan: for each tunnel piece of a feature whose first or last vertex is exactlyway, it inserts a sampleshift_mmetres along the stroke from that vertex (assplitdoes) and gives the stretch betweenLevel::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 inbuild_withbefore the crossings, whatever the features;buildandbuild_levelledpass no ends. A test: a cut tunnel way gives a ground piece ofshift_mand a tunnel piece. -
Measure (b),
parts::measure::site(opening, cells) -> Site. For each cell that holds a point up tocollar_max_m + 2inside orwing_max_mbeside the frame line: the cell's input from the bake's tiles with the tags of the levels pass (Tile::bytes_with),graph::build_openwith the decks'edge_band_mand theOpenEnds of every opening of step 4,faces::records::near_under, and the height byfaces::heights::check::at; one cache of record words per job, aslevels::cells_of. The result depends only on the crate's sources and onbores, which builds bore covers on storey 0: theobc databinary does not enable it, the step writesground_plan_bores(obc_ground_plan::graph::BORES, nowpub) into its metrics so that a release shows it, and P8 deletes the feature. ASiteholds:half(half_m+ widening + margin) andheight(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 tohalf + 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 tagdeck) over the frame line. -
Ladder (c),
parts::ladderreturns 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:- A vertex of unknown height: no part.
- An end within
half + same_tube_gap_macross,same_tube_stagger_malong andpair_max_degof an end of a wider chain: no part. The wider chain's axis stays; itshalfgrows to the farthest edge of either way, plus the margin. - Shorter than
underpass_max_m, a way or a track on top:boxat both ends, insideheight = 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 ondevelop(out of scope in the epic). - An end that meets no way and is covered at its end vertex:
free. - An end whose first covered metre lies within
collar_max_m: an end of another chain of the same family (rail or not) withinpair_max_mandpair_max_deggivespair(the nearest pairs first, each end in one pair at most, astwinsoftunnels.ts); else apathorminorend covered withinrock_cover_max_mgivesrock; elsearch. - Else
free.
-
Numbers.
collar: metres to the first covered metre; forfree,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 mostheight + shell_m + face_over_crown_max_m, and under a deck's underside lesscoping_m.left,right: per metre out from the frame's outer edge, ground +coping_m− floor, at mostface; a row ends before the first metre whose ground lies under floor +wing_ground_m, or atwing_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, andleftandrightstart at the outer edges of the pair. -
Records,
parts::records, placed after the sea,min_zoom13. Atunnel-tubeline per chord of a chain with a part: the chain's curve (roads::polylineof 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.zis the floor, the road solver's height. Atunnel-endpoint per opening with a part, at the frame line's middle,zthe 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 sectionboth round, orboxfor an underpasshalf,heightboth inside half-width and height lookboth concrete,masonryorrockclass,surfacetube the roads.jsonclass and thesurfacetag (when it has one) of the chain's widest way: the inside and the paintroadtube the half-width of that way's carriageway alongtube its metres along its stroke at the first vertex; none on a way with no alignment endstube the partof the chain's two ends, the end at its first opening first, for examplearch freepartend arch,pair,rock,boxorfreeheadingend radians from x to y of world coordinates, into the tube (as Plan::tangent)collarend collar length; the shell length of freeface,left,rightend step 8; not on freefootend step 8 wayend the end vertex of the OSM way that the opening belongs to, x yin 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 exactshiftend metres along that way from wayto the opening (step 4); 0 where it did not movematepairmetres to the left from this axis to the mate's axis mate_way,mate_shiftpairwayandshiftof the mate's opening -
Tags of the ways.
writeadds to each tunnel way of a chain with a part, beside its other tags by id,parts: thepartof the chain's two ends, as the tube'sends. The taglevelsof a tunnel way: P1 to P7 do not write, change or read it; P8 deletes it withbores. -
Contract.
specs/trailview-features.md: three rows in the table of Structures (the two kinds and the tagparts), 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 atunnel-tubeand atunnel-endto the vectors. The ground plan ignores both kinds. -
Tests,
parts/tests.rs: each rung on a small chain; the tagswayandshiftof 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,BORESpublic.graph/open.rs: create.data/trailview/parts.json: create.tools/testing/suites.toml: add it to the triggers ofobc-trailview-features.host/obc-data-steps/src/planner.rs: change: optionparts, revision 26.specs/trailview-features.md,specs/vectors/trailview-features.{json,bin}: change.builder/web/tests/browser/trailview/fixture/: change: the feature tiles rebaked withmake-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; inbuilder/webnpx vitest run src/lib/trailview/stream/features.test.ts.- A test of the bake on the fixture shows that every
levelstag 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-endper 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,BandHinto the taglevelsof the tunnel ways. Here the tag stays as ondevelopuntil P8 deletes it: the viewer links noboresand so reads no tunnel way'slevels, 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 thetunnel-endrecord (way,shift) and ingraph::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, andwayis a vertex anyway.mergeandtunnel_statesdo not change;level_tags.rschanges only by the cut thatsplitandopenshare. -
Shallow tunnels. A shallow tunnel (a way of the kind
tunnelin 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
endsandparts. The end behind the record's first vertex comes first, in the rising metres of its way, so a single record reads it.nonenames an end with no part of its own (rung 1, rung 2, a building, a fork). -
Wall tops of
leftandrightare at leastcoping_m: the formula of Plan 8 gave tops under the floor where the ground falls at once. -
Face under a deck. A deck caps
faceonly where its underside lesscoping_mlies 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. Ofpair: 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, sowayandshiftstay 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::levelsruns 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.rsgives 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 (
shift0) 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 flagrock(true forminorandpath) andbake.narrow_bore_m3 (asboreHalfoftunnels.ts).
Requirements: none
Generated by Claude Code
Activity
timohueser commentedon Nov 19, 2026
Build: the algorithm and its invariants
Both unproven points hold (tests on the branch
claude/trailview-3678-parts-placements):graph::opencuts a tunnel wayshift_mfrom an end vertex with the code oflevel_tags::split(one shared assembly of the cut stretches). A test builds a tunnel with two open ends and the same tunnel with alevelstag "O 7.5 P B {len − 5} P O" underbores: the two graphs have the same ways and samples, bit for bit.openfinds the cut by the span lengths from the vertex, so it also holds on a way with no alignment.tiles::frame_pointuses 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 awholevertex.Algorithm (after the levels pass)
level_tags::chainswalks each chain from each tag end over single links, astunnel_states. The bake splits a chain where a feature is not of kindtunnel: 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.roads::polyline), joined, with the floor height, the metres along the chain and the stroke metres of each way.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 mostjunction_shift_max_m.levels::cells_of. Each cell that holds a point to read is built once per job:build_open(levelled, with theOpenEnds near the cell),records::near_under, thengraph::levelson the same graph for the ladders (after the faces, so the faces do not read them). Ground =check::aton 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.freelast.Invariants (one focused test each)
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)wayis the ground plan's own point of the vertex in every tile. (done)way= the end vertex andshift= the metres along to it. The ground plan cuts there.levelsof 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:
endsandpartsgive 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 isnone.boxis the first covered metre, at most half the chain. The collar of a pair is the larger of its two tubes.graph::partstrims spans more than two spans off a cell's grown square. A cell whose grown square ends withinshiftof 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
timohueser commentedon Nov 20, 2026
P1 is merged with #3732.
Generated by Claude Code