Repository navigation
Description
Status: approved
Part of #3651.
TL;DR
Goal: A new crate host/obc-trailview-parts makes, from the part records of a feature tile (P1), the meshes of the parts, the boxes in which the ground does not draw, the floor segments for the walking camera, and per vertex the share of daylight. The viewer's stamp code calls it as WASM, in the stamp worker and in the bake of trailview-stamps alike.
Problem: Nothing builds a part from the bake's numbers. Today's structures/tunnels.ts builds a portal of fixed sizes, and the share of daylight in a bore comes from a loop over the portal boxes in the shader.
Decision: A pure function crate, as obc-ground-plan is: no I/O, no threads, libm for its maths, data/trailview/parts.json embedded. A small WASM bridge builder/trailview-parts-wasm (package obc-trailview-parts-bridge). The stamp code imports its bytes as a data: URL (?url&inline), so the code loads the same way in a worker and in the Node bake. stamp_version covers the sources of the crate, the bridge and parts.json, not the bytes, and the stamp bundle refuses a bridge built from other sources. A structure vertex gets a 7th word, daylight. First kinds of part: arch and the tube.
Rejected: The builder in TypeScript: P7 builds the parts in the Rust bake, and the iOS app needs them later. The builder in the ground plan bridge: 2.0 MB that each stamp worker and the stamp bake would load. A bridge fetched by its URL: the stamp bake imports its module from a data: URL, where a relative file does not load. .wasm?inline: Vite 7 does not load it (Facts). The share of daylight in a free byte of an existing word: a road face uses all six words, so the value would need two places.
Systems: trailview
Contracts: specs/trailview-tiles.md (Stamps: a structure vertex has 7 words; what stamp_version covers)
Size: L (a new crate and bridge, a contract change, the guards of a new bridge)
Facts
trailview-stamps.mjsbuilds the bake module withstampBundleand imports it as adata:URL.stamp_versionis the start of the SHA-256 of its code (stamp-bundle.ts); the build hasconfigFile: false. The viewer reads no node of a layer whose version differs from its own.- Vite 7.3.6 (
builder/web/node_modules/vite/dist/node/chunks/config.js):wasmis not a known asset type, andvite:wasm-fallbackthrows on an id that ends in.wasm, so.wasm?inlinefails. With.wasm?url&inline, the asset plugin takes the id (urlRE),removeUrlQueryleaves?inline, andshouldInlinegivesdata:application/wasm;base64,…in a build. - The worker's job
stampsgives each node the boxes of the portals withinREACH_M(20 m) as 9 words (BOX: middle x, y, unit way in, depth, half-width, roof, floor, rise) and, on the owner level, the floor segments as 7 words (FLOOR); the jobmeshesgives an owner node its structure meshes (structures/node.ts).tunnels.tsportalBoxtakes the least rise over the vertices in the box and lifts the roof to clear the crown at each; its depthboxDepthcomes fromPORTAL_CELLSandMESH_TEXELSofRULES; a dark face (VOID, 0.7 m in) fills the opening where the terrain draws coarser than level 17. Only road bores have lamps; a track bore is lined in concrete, a path bore is rock. - A structure vertex has 6 words (
STRUCTURE_VERTEXofmesh.ts); a road face in a bore (PAINT | BORE) uses all of them, and all 8 flag bits are taken. The structure pool holds 16 MiB of vertices (structures.ts). - The ground plan bridge is 2.0 MB raw and loads by
fetchin the plan workers (plan/bridge.ts).stamp_sourcesofplanner.rshashes the viewer's TypeScript (notpkg/),data/trailview/*.jsonand three files; no Rust. - A new bridge must be known to:
ownsofdocs/design/trailview.md, the grouphostoffirmware/tools/dependency_rules.json,JOBS["wasm-bridges"],BRIDGESandBRIDGE_PACKAGESoftools/test_plan.py,builder/wasm/wasm_size_guard.py, the artifact steps of.github/workflows/ci.yml,.gitignore(review of web: TrailView decodes the ground tiles in WASM where Safari premultiplies #3673).
Plan
Units: the crate takes points in world units of the viewer (2^30 per side of the Web Mercator square, y down) as f64, and metres per unit by the formula of metresPerUnit of bins.ts.
- Proof first. The builder's first step: a module of about 10 lines that imports a small
.wasmwith?url&inline, decodes thedata:URL and callsinitSync, built once bystampBundleand imported bytrailview-stamps.mjsin Node, and once in the viewer's worker build. If either fails, stop and report before more work. - Table.
data/trailview/parts.jsongetsdesign:frame_m0.45,recess_m0.25,face_m0.8 (head wall thickness),arch_segments8,spring0.6,lamp_spacing_m10,lamp_m1.2,kerb_m0.15,daylight_m20,void_m0.7,portal_cells2,mesh_texels4,sleeper_m0.6,reach_m20,lift_m0.03,mitre_max3;looks: per lookface,frame,coping,wall,shellas#rrggbb(concrete#a9a69d #cbc8bf #d2cfc7 #a19e95 #9a978e, masonry#91857a #bdb2a2 #c2bbae #8a7f72 #857a6e, rock#7d776f #aaa49a #b0aaa0 #77716a #716b64, from the prototype); andinside, from today'stunnels.ts:tiles#dcdad3,arch_lining#7f7e7a,lining#8a877f,walk#a3a19b,rock#6f6a62,rock_floor#7d7262,lamp#fff3d6,void#0a0a0b. The step option of P1 keeps onlygroupsandbake, so these change no feature tile. A test instructures/parts.test.tsholdsportal_cells,mesh_texels,sleeper_mandvoid_mequal toRULES,SLEEPER_MandVOID_Mof the viewer. - Crate
host/obc-trailview-parts(dependenciesserde_json,libm):lib.rs:Rules::embedded() -> &'static Rules,Rules::parse(&str);enum Part { Arch, Pair, Rock, Box, Free },pub const BUILT: &[Part] = &[Part::Arch](the one place that says which kinds are built; P5 and P6 add theirs) andpub fn built(ends: &[Part]) -> bool;enum Section { Round, Box };struct End { at: [f64; 2], z: f64, part, heading, section, half, height, look, collar, face, left: Vec<f64>, right: Vec<f64>, foot, mate, way: [i64; 2], shift, mate_way: Option<[i64; 2]>, mate_shift }andEnd::from_tags(at, z, &BTreeMap<String, String>) -> Result<End, String>;struct Chord { a: [f64; 3], b: [f64; 3], section, half, height, look, class, road, along: Option<f64>, ends: [Part; 2], code: u32, marked: bool }andChord::from_tags, which leavescodeandmarkedto the caller.pub fn meshes(square: [f64; 4], ends: &[End], chords: &[Chord], rules: &Rules) -> Mesh,Mesh { vertices: Vec<u32>, indices: Vec<u32> }: the faces of each end whoseatthe square holds (half-open) and of each chord whoseait holds, so each face draws in one node. Only ends and chords of chains whoseendsare all inBUILT.pub fn volumes(square, ends, chords, rules) -> Volumes,Volumes { boxes: Vec<f64>, floors: Vec<f64> }: theBOXwords of each box whose rectangle (middle, way in, depth, half-width) meets the square grown byreach_m; theFLOORwords (a, b,z + lift_mat both,half) of each chord withinreach_m. The same rule ofBUILT.pub fn footprints(ends, chords, rules) -> Vec<Vec<[f64; 2]>>: per built end the ring round its head wall and wings (front to back) and its collar (both sides of the chords athalf + shell_m, tocollar). P4 reads it in the ground plan and in the stamp code.- An end finds its tube: the chord with a vertex within 0.5 m of
at, then the chords that share its vertices. - From this item on, the bake depends on the crate: it parses its option with the crate's
Rulesand takesPartfrom it. The bake never readsBUILT: the tiles hold the records of all ends.
- Vertex. Words, as today plus one: x, y (
i32), z (f32), colour and flags (u32),road(u32, snorm16 across and half over ±16 m),sleepers(f32,NO_SLEEPERS= −1e9 where none),daylight(f32).mesh.ts:STRUCTURE_VERTEX7,MeshBuilder.vertex(.., daylight = -1): −1 means "the shader's loop over the boxes" (P4), so today's tunnels keep their light;structures.ts: stride 28 and attribute 5 (float32at 24);structures.wgsl:@location(5) daylightinStructureIn, passed on. P4 makes the shader read it. - Tube (
tube.rs), per chord. Section: round springs atspring × heightwitharch_segments, box is a rectangle. At a vertex that two chords share, both rings lie in the mitre plane (the bisector of the two chord directions, its length at mostmitre_maxtimes the section, asmitreofbins.ts), so the tube has no gap at a bend; where the twoheights differ, a ring face closes the step in the crown. At an opening the ring is square to the chord. Inside by the group ofclass, as today'sbore: a road group gets the road (PAINT | BORE;codeandmarkedin the colour; across and half inroad; insleepersthe metres along the stroke,along+ metres froma, orNO_SLEEPERSwith noalong), a kerb ofkerb_m, a walk to the wall, walls intiles, the vault inarch_lining, and a lamp (LAMP,lamp_mlong) under the crown where the metres along pass a multiple oflamp_spacing_m; the rail group gets the track face (sleepers= metres along ÷sleeper_m) andliningwalls and vault, no lamps; the path group getsrock_floor,rock, no lamps. AllBORE.daylightper vertex: over the openings (each end'sat, and the mate's opening of a pair) whose heading line passes withinhalf + shell_m + 1beside the vertex,1 − smoothstep(0, daylight_m, m)withmthe metres in from that frame line, the largest one; 0 with none. - Arch (
arch.rs): the head wall (thicknessface_m) on the frame line, its frontrecess_mout from a frame ring offrame_mround the opening; its flat top atfacewith a coping ofcoping_m; the wings out to the lengths ofleftandright, their tops by the rows; the collar's outer shell (shell_mthick, lookshell) along the chords forcollarmetres. Every wall goes down tofoot. The dark face of today's portal stays: aVOIDface across the openingvoid_min, which the shader draws only where the terrain draws coarser than level 17. One box, by today's rule ofportalBoxover the chords: middleat, way in fromheading, depthmax(boxDepth, collar + 2)withboxDepth=(portal_cells + √2) × mesh_texels × 32world units in metres + 1, halfhalf + shell_m, rise the leastdz / sover the chord vertices in the box, floorz + lift_m, roofz + height + shell_mlifted by the largestdz − rise·sthere, so the roof clears the crown at each vertex. A crown that P2 lowers lies lower and is cleared too.Pair,Rock,BoxandFreegive nothing yet (P5, P6). - Bridge
builder/trailview-parts-wasm(wasm-bindgen,cdylibandrlib,wasm-opt -O3):meshes(input: &str) -> Vec<u32>returns the count of vertex words, the vertex words (each word's bits) and the indices;volumes(input: &str) -> Vec<f64>returns the count of box words, the boxes and the floors;footprints(input: &str) -> Vec<f64>returns the count of rings, then per ring its count of points and their x, y;built(parts: &str) -> booltells whether the kinds of a tagparts(orends) are all inBUILT.inputis JSON:{"square": [x0, y0, x1, y1], "ends": [{"at": [x, y], "z": z, "tags": {..}}], "chords": [{"a": [x, y, z], "b": [x, y, z], "tags": {..}, "code": c, "marked": m}]}.build-wasm-bridges.shbuilds it with--target webtobuilder/web/src/lib/trailview/structures/pkg, nameobc_trailview_parts_bridge. A README with its build andclippy --target wasm32-unknown-unknown. - Viewer
structures/parts.ts: imports./pkg/obc_trailview_parts_bridge_bg.wasm?url&inline, decodes the base64 of thedata:URL to bytes and callsinitSync({ module: bytes })once.partInput(list, tile, node)takes thetunnel-endandtunnel-tubefeatures of the tile in world units, asfeaturesofbins.tsconverts a line, and gives each chord thecodeandmarkedthatbins.tsgives a way of itsclassandsurface;partMeshesandpartVolumesreturn the arrays of step 3. P4 calls them. - Version.
stampBundlehashes its code with each inlineddata:application/wasm;base64,…string replaced by the SHA-256 of the sources: every file ofhost/obc-trailview-partsandbuilder/trailview-parts-wasm, anddata/trailview/parts.json.build-wasm-bridges.shwrites the same hash, taken when it builds, tostructures/pkg/sources.sha256;stampBundlestops with an error when that file is missing or holds another hash, so apkg/built from other sources never takes the checkout's version. The stamp bake does not build the bridge itself (trailview-stamps.mjsonly bundles), so this check is needed.stamp_sourcesofplanner.rsadds the same files, so a change that changes the version also bakes the layer again.specs/trailview-tiles.md(Stamps): whatstamp_versioncovers; a structure vertex has 7 words. The risk that stays: two builds of the same sources with another toolchain or other locked dependencies give one version and other bytes, which can draw a part a little differently in a baked node than in the worker. - Guards. Workspace
Cargo.toml(member, dependency);dependency_rules.jsongrouphost: both packages;docs/design/trailview.mdowns: both folders;tools/test_plan.py: the bridge inJOBS["wasm-bridges"],BRIDGES,BRIDGE_PACKAGES;wasm_size_guard.py: modulepartsinPKG_DIRS,BUDGETS(the CI size of this pull request plus 8 KiB gzip, raw by the same share),ADVICE,GOVERNS;ci.yml: its size step and its artifactobc-trailview-parts-bridge-pkgwhereobc-ground-plan-bridge-pkggoes;.gitignore: itspkg/;tools/testing/suites.toml: packageobc-trailview-partstriggered bydata/trailview/parts.json. - Tests. Crate: the box of an arch holds the inside section for its depth and clears the crown of each chord vertex in it; two chords at a bend share their ring's vertices;
daylightis 1 on the frame line and 0 fromdaylight_min; over four squares about an end and its chords, each face draws once. A footprint holds the head wall and the collar.stampBundlerefuses apkg/whosesources.sha256differs.structures/parts.test.ts: the bridge gives the box of the crate's test end from a feature tile with that record, and the equal constants of step 2.
Deviation in the build
The build is #3754. It deviates from the plan above in these points (after its review, fix rounds 1 to 3):
Chord.endsis[Option<Part>; 2], andbuilttakes&[Option<Part>]: the records namenone. A chain with anoneend is not built.- The bake's option holds only
groupsandbake. So the crate hasLadder(those two,Ladder::parse(&Value), the bake's rules) andRules(the ladder,design,looksandinside;Rules::parse(&str),Rules::embedded()). The bake takesPartas its kind of part. - The ring at an opening lies on the frame line (square to
heading), not square to the first chord, so the tube and the frame share their vertices exactly. - The frame of an arch (the head wall, the frame, the dark face, the first ring of the collar) follows the grade of the floor over the first
face_min. The top of the head wall tilts by that grade across its thickness. - The part closes its opening: a sill
lift_munder the floor from the front of the head wall to the frame line, across the hole, where no road can z-fight with it; at an opening the front of the tube's floor goes down to the sill; the walls of the tube stand on its floor; the back of the head wall has the outside of the collar's shell as its hole; the head wall and the shell go down to one level,footunder the opening's floor. A test holds the faces closed but at the foot and at the end of the collar. - The box starts at the front of the head wall, as the footprint does, and clears the crown of each chord vertex with the height of that chord, not with the height of the end.
- The inside of a tube comes from a field
boreper group inparts.json:road(the road,tiles,arch_lining, lamps),track(the track,lining) orrock(rock_floor,rock). A track keeps the kerb and the walk of today's bore. - The coping is a band of
coping_min the colourcoping, flush with the wall. A look has no colourwall. - The test that
stampBundlerefuses a package from other sources testsversionOf: the stamp bundle holds no WASM until P4 importsparts.ts. A second test holds the hash thatbuild-wasm-bridges.shwrites equal topartsSources()ofstamp-bundle.ts. The sources are the files that git tracks but the Markdown;.gitattributeskeeps their line endings.stampBundlerefuses a second inlined WASM module. bins.tsexportsworldPointandclassPaint(the surface code and the lines of a class and a surface), andmarkedtakes only the three fields that it reads.- The daylight of an opening reaches only the points in its section (half-width, shell and a metre to each side; from
footto the crown's shell over the tube's floor at that metre), from the front of its head wall todaylight_min. End::from_tagsandChord::from_tagstake the rules and fail on alookthat the rules do not have and on aclassin no group.alongis required.- The bake keeps the vertices of a tube at least
vertex_gap_m(1 m,bakeofparts.json) apart: the openings and the joins of the ways stay, and a point of the curve, then a point of a reach, nearer than that to a vertex is that vertex. The vertex that took the end of a way's reach takes that way's cap within its reach +vertex_gap_m, so a merged reach end keeps its cap; every other vertex keeps the plain reach. Features revision 29. - Faces that meet share the corners of their edges, by construction. One operation makes the faces between two polylines with other corners (a strip whose triangles go in the order of the share along each); the head wall's columns, top and ends, the walls of a tube and of a shell at a step, the sill, the reveal, the frame and the step faces use it. The outlines of the frame have a corner at the floor's height where the tube's wall stands on the floor; the sill is split where the pieces of the floor meet the frame.
Files
host/obc-trailview-parts/(Cargo.toml,src/{lib,tube,arch,footprint}.rs): create.builder/trailview-parts-wasm/(Cargo.toml,src/lib.rs,README.md): create.builder/web/src/lib/trailview/structures/{parts.ts,parts.test.ts}: create.mesh.ts,structures.ts,structures.wgsl: change: the 7th word.builder/web/vite/stamp-bundle.ts,data/trailview/parts.json,builder/build-wasm-bridges.sh,specs/trailview-tiles.md,host/obc-data-steps/src/planner.rs,host/obc-trailview-features/{Cargo.toml,src/parts/mod.rs}: change.Cargo.toml,firmware/tools/dependency_rules.json,docs/design/trailview.md,tools/test_plan.py,builder/wasm/wasm_size_guard.py,.github/workflows/ci.yml,.gitignore,tools/testing/suites.toml: change: guards.
Deviation from the epic
- The epic says that the WASM bytes become part of
stamp_version. Here the version covers the sources of the crate and the bridge andparts.json: two builds of the same sources can give other bytes (an unpinned toolchain, thewasm-optthatwasm-packdownloads, paths in panic texts), and a version that differs between the bake machine and the viewer's build makes the viewer refuse the whole layer, so both apps would lose their baked nodes.Cargo.lockstays out: it is the whole workspace's, and any unrelated bump would make the viewer refuse the baked layer.
Done when
- The proof of step 1, in the pull request.
obc test -p obc-trailview-parts,-p obc-trailview-features;obc exec cargo clippy -p obc-trailview-parts -p obc-trailview-parts-bridge --all-targets -- -D warnings, and the bridge forwasm32-unknown-unknown;cargo fmt --all;bash builder/build-wasm-bridges.sh;python3 builder/wasm/wasm_size_guard.py --module parts;python3 firmware/tools/check_dependencies.py;python3 -m unittest tools.tests.test_selection_plan;obc suites check.- In
builder/web:npx vitest run src/lib/trailview/structures/parts.test.ts src/lib/trailview/structures/structures.test.ts,npm run check,npm run check:wgsl. - The pull request gives the raw and gzip size of the bridge, and, before and after the 7th word, the bytes of the stamp layer of the fixture and the structure pool's use in the
walkflight.
Depends on #3678. Requirements: none
Generated by Claude Code
Activity
timohueser commentedon Nov 19, 2026
P1 (#3678): what changed for the readers of its records
The build of P1 deviates from its design in these points. The full list is under "Deviation in the build" in #3678.
tunnel. A chain goes on through each vertex where the ends of two such ways meet. An end opens only where no other such way has a vertex there. At a fork or a cross passage, the end has no part, and thetunnel-tuberecords run to that end vertex.tunnelin the map that the bake lays on the ground) belong to no chain. They have no records and draw on the ground, as on develop.endsandparts. The end behind the record's first vertex comes first, in the rising metres of its way.nonenames an end with no part of its own: same tube, under a building only, a vertex of unknown height, or a fork.leftandrightare at leastcoping_m. Thecollarof aboxis at most half the chain. Thecollarof apairis the larger of its two tubes. In a pair, the nearer opening moves onto the frame line of the other, so itsshift(ormate_shift) includes that move.pairrecords have tubes that overlap. Their axes are nearer than both outer half-widths, for example motorway carriageways 9 m to 13 m apart with ahalfof 6.6 m, or double tracks 3.6 m to 4 m apart. Rung 2 as designed (halfof the wider +same_tube_gap_m) does not take them into one tube. The builder of a pair must cut the two tubes where they meet, or rung 2 must change. The report to the owner gives the options.graph::openmatches the end vertex on the first or last vertex of a part. A cell whose grown square ends withinshiftof the vertex does not see it (the trim ofgraph::parts), so the stretch stays a tunnel there. This is more than 170 m from the square of that cell.Generated by Claude Code
timohueser commentedon Nov 20, 2026
From the review of #3732 (P1): a chain whose one end lies in the tube of a wider chain (rung 2,
none) and whose other end has a part keeps its owntunnel-tuberecords over its whole length. Near thenoneend, those chords run inside the wider tube, and the builder must not draw them there. This belongs with the question on #3683.Generated by Claude Code
timohueser commentedon Nov 20, 2026
P2 (#3679, #3737): what changed for the reader of the tube records
tunnel-tubehas the floor of P2 as itszand its ownheight: the lesser height of its two vertices, at most the tube's height and at leastleast_height_mof its group. On test box B, 132 stretches in 119 tubes are lower, the deepest by 1.02 m. Between two chords, the ring face of Plan 5 closes the step in the crown, as planned.tunnel-endkeeps theheightof its tube; only the chords get lower. At 93 of 948 drawn openings on test box B, the first chord is lower than theheightof itstunnel-end: 82box, 8arch, 1pair, 2free, up to 1.02 m (at abox). The builder must close that step between the frame and the first ring too, or take the lesser height for the frame. This is a deviation of P2: its design named only thezof atunnel-end.tunnel-tuberecords in place of 15,159.Generated by Claude Code
timohueser commentedon Nov 20, 2026
P2 (#3679, #3737) after its review: the height of an opening
This replaces the second point of my earlier comment here.
tunnel-endtakes the height of the tube's chord at its vertex, and itsfacereads that height. On test box B, no opening is higher than its first chord (0 of 948).tunnel-tubestill has its ownheight, the lesser of its two vertices. Between two chords of different height, the ring face of Plan 5 closes the step, as planned.tunnel-tuberecords in place of 15,159.Generated by Claude Code
timohueser commentedon Nov 20, 2026
Done in #3754 (merged).