Skip to content

TrailView parts P3: a crate builds the parts, and the stamp code runs it as WASM #3680

Closed

Description

@timohueser

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.mjs builds the bake module with stampBundle and imports it as a data: URL. stamp_version is the start of the SHA-256 of its code (stamp-bundle.ts); the build has configFile: 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): wasm is not a known asset type, and vite:wasm-fallback throws on an id that ends in .wasm, so .wasm?inline fails. With .wasm?url&inline, the asset plugin takes the id (urlRE), removeUrlQuery leaves ?inline, and shouldInline gives data:application/wasm;base64,… in a build.
  • The worker's job stamps gives each node the boxes of the portals within REACH_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 job meshes gives an owner node its structure meshes (structures/node.ts). tunnels.ts portalBox takes the least rise over the vertices in the box and lifts the roof to clear the crown at each; its depth boxDepth comes from PORTAL_CELLS and MESH_TEXELS of RULES; 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_VERTEX of mesh.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 fetch in the plan workers (plan/bridge.ts). stamp_sources of planner.rs hashes the viewer's TypeScript (not pkg/), data/trailview/*.json and three files; no Rust.
  • A new bridge must be known to: owns of docs/design/trailview.md, the group host of firmware/tools/dependency_rules.json, JOBS["wasm-bridges"], BRIDGES and BRIDGE_PACKAGES of tools/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.

  1. Proof first. The builder's first step: a module of about 10 lines that imports a small .wasm with ?url&inline, decodes the data: URL and calls initSync, built once by stampBundle and imported by trailview-stamps.mjs in Node, and once in the viewer's worker build. If either fails, stop and report before more work.
  2. Table. data/trailview/parts.json gets design: frame_m 0.45, recess_m 0.25, face_m 0.8 (head wall thickness), arch_segments 8, spring 0.6, lamp_spacing_m 10, lamp_m 1.2, kerb_m 0.15, daylight_m 20, void_m 0.7, portal_cells 2, mesh_texels 4, sleeper_m 0.6, reach_m 20, lift_m 0.03, mitre_max 3; looks: per look face, frame, coping, wall, shell as #rrggbb (concrete #a9a69d #cbc8bf #d2cfc7 #a19e95 #9a978e, masonry #91857a #bdb2a2 #c2bbae #8a7f72 #857a6e, rock #7d776f #aaa49a #b0aaa0 #77716a #716b64, from the prototype); and inside, from today's tunnels.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 only groups and bake, so these change no feature tile. A test in structures/parts.test.ts holds portal_cells, mesh_texels, sleeper_m and void_m equal to RULES, SLEEPER_M and VOID_M of the viewer.
  3. Crate host/obc-trailview-parts (dependencies serde_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) and pub 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 } and End::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 } and Chord::from_tags, which leaves code and marked to 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 whose at the square holds (half-open) and of each chord whose a it holds, so each face draws in one node. Only ends and chords of chains whose ends are all in BUILT.
    • pub fn volumes(square, ends, chords, rules) -> Volumes, Volumes { boxes: Vec<f64>, floors: Vec<f64> }: the BOX words of each box whose rectangle (middle, way in, depth, half-width) meets the square grown by reach_m; the FLOOR words (a, b, z + lift_m at both, half) of each chord within reach_m. The same rule of BUILT.
    • 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 at half + shell_m, to collar). 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 Rules and takes Part from it. The bake never reads BUILT: the tiles hold the records of all ends.
  4. 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_VERTEX 7, 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 (float32 at 24); structures.wgsl: @location(5) daylight in StructureIn, passed on. P4 makes the shader read it.
  5. Tube (tube.rs), per chord. Section: round springs at spring × height with arch_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 most mitre_max times the section, as mitre of bins.ts), so the tube has no gap at a bend; where the two heights differ, a ring face closes the step in the crown. At an opening the ring is square to the chord. Inside by the group of class, as today's bore: a road group gets the road (PAINT | BORE; code and marked in the colour; across and half in road; in sleepers the metres along the stroke, along + metres from a, or NO_SLEEPERS with no along), a kerb of kerb_m, a walk to the wall, walls in tiles, the vault in arch_lining, and a lamp (LAMP, lamp_m long) under the crown where the metres along pass a multiple of lamp_spacing_m; the rail group gets the track face (sleepers = metres along ÷ sleeper_m) and lining walls and vault, no lamps; the path group gets rock_floor, rock, no lamps. All BORE. daylight per vertex: over the openings (each end's at, and the mate's opening of a pair) whose heading line passes within half + shell_m + 1 beside the vertex, 1 − smoothstep(0, daylight_m, m) with m the metres in from that frame line, the largest one; 0 with none.
  6. Arch (arch.rs): the head wall (thickness face_m) on the frame line, its front recess_m out from a frame ring of frame_m round the opening; its flat top at face with a coping of coping_m; the wings out to the lengths of left and right, their tops by the rows; the collar's outer shell (shell_m thick, look shell) along the chords for collar metres. Every wall goes down to foot. The dark face of today's portal stays: a VOID face across the opening void_m in, which the shader draws only where the terrain draws coarser than level 17. One box, by today's rule of portalBox over the chords: middle at, way in from heading, depth max(boxDepth, collar + 2) with boxDepth = (portal_cells + √2) × mesh_texels × 32 world units in metres + 1, half half + shell_m, rise the least dz / s over the chord vertices in the box, floor z + lift_m, roof z + height + shell_m lifted by the largest dz − rise·s there, so the roof clears the crown at each vertex. A crown that P2 lowers lies lower and is cleared too. Pair, Rock, Box and Free give nothing yet (P5, P6).
  7. Bridge builder/trailview-parts-wasm (wasm-bindgen, cdylib and rlib, 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) -> bool tells whether the kinds of a tag parts (or ends) are all in BUILT. input is 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.sh builds it with --target web to builder/web/src/lib/trailview/structures/pkg, name obc_trailview_parts_bridge. A README with its build and clippy --target wasm32-unknown-unknown.
  8. Viewer structures/parts.ts: imports ./pkg/obc_trailview_parts_bridge_bg.wasm?url&inline, decodes the base64 of the data: URL to bytes and calls initSync({ module: bytes }) once. partInput(list, tile, node) takes the tunnel-end and tunnel-tube features of the tile in world units, as features of bins.ts converts a line, and gives each chord the code and marked that bins.ts gives a way of its class and surface; partMeshes and partVolumes return the arrays of step 3. P4 calls them.
  9. Version. stampBundle hashes its code with each inlined data:application/wasm;base64,… string replaced by the SHA-256 of the sources: every file of host/obc-trailview-parts and builder/trailview-parts-wasm, and data/trailview/parts.json. build-wasm-bridges.sh writes the same hash, taken when it builds, to structures/pkg/sources.sha256; stampBundle stops with an error when that file is missing or holds another hash, so a pkg/ built from other sources never takes the checkout's version. The stamp bake does not build the bridge itself (trailview-stamps.mjs only bundles), so this check is needed. stamp_sources of planner.rs adds the same files, so a change that changes the version also bakes the layer again. specs/trailview-tiles.md (Stamps): what stamp_version covers; 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.
  10. Guards. Workspace Cargo.toml (member, dependency); dependency_rules.json group host: both packages; docs/design/trailview.md owns: both folders; tools/test_plan.py: the bridge in JOBS["wasm-bridges"], BRIDGES, BRIDGE_PACKAGES; wasm_size_guard.py: module parts in PKG_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 artifact obc-trailview-parts-bridge-pkg where obc-ground-plan-bridge-pkg goes; .gitignore: its pkg/; tools/testing/suites.toml: package obc-trailview-parts triggered by data/trailview/parts.json.
  11. 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; daylight is 1 on the frame line and 0 from daylight_m in; over four squares about an end and its chords, each face draws once. A footprint holds the head wall and the collar. stampBundle refuses a pkg/ whose sources.sha256 differs. 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):

  1. Chord.ends is [Option<Part>; 2], and built takes &[Option<Part>]: the records name none. A chain with a none end is not built.
  2. The bake's option holds only groups and bake. So the crate has Ladder (those two, Ladder::parse(&Value), the bake's rules) and Rules (the ladder, design, looks and inside; Rules::parse(&str), Rules::embedded()). The bake takes Part as its kind of part.
  3. 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.
  4. 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_m in. The top of the head wall tilts by that grade across its thickness.
  5. The part closes its opening: a sill lift_m under 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, foot under the opening's floor. A test holds the faces closed but at the foot and at the end of the collar.
  6. 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.
  7. The inside of a tube comes from a field bore per group in parts.json: road (the road, tiles, arch_lining, lamps), track (the track, lining) or rock (rock_floor, rock). A track keeps the kerb and the walk of today's bore.
  8. The coping is a band of coping_m in the colour coping, flush with the wall. A look has no colour wall.
  9. The test that stampBundle refuses a package from other sources tests versionOf: the stamp bundle holds no WASM until P4 imports parts.ts. A second test holds the hash that build-wasm-bridges.sh writes equal to partsSources() of stamp-bundle.ts. The sources are the files that git tracks but the Markdown; .gitattributes keeps their line endings. stampBundle refuses a second inlined WASM module.
  10. bins.ts exports worldPoint and classPaint (the surface code and the lines of a class and a surface), and marked takes only the three fields that it reads.
  11. The daylight of an opening reaches only the points in its section (half-width, shell and a metre to each side; from foot to the crown's shell over the tube's floor at that metre), from the front of its head wall to daylight_m in.
  12. End::from_tags and Chord::from_tags take the rules and fail on a look that the rules do not have and on a class in no group. along is required.
  13. The bake keeps the vertices of a tube at least vertex_gap_m (1 m, bake of parts.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.
  14. 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 and parts.json: two builds of the same sources can give other bytes (an unpinned toolchain, the wasm-opt that wasm-pack downloads, 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.lock stays 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 for wasm32-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 walk flight.

Depends on #3678. Requirements: none


Generated by Claude Code

Activity

  1. timohueser commented on Nov 19, 2026

    @timohueser
    OwnerAuthor

    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.

    • Chains. 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. 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 the tunnel-tube records run to that end vertex.
    • Shallow tunnels (a way of the kind tunnel in 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.
    • ends and parts. The end behind the record's first vertex comes first, in the rising metres of its way. none names an end with no part of its own: same tube, under a building only, a vertex of unknown height, or a fork.
    • Numbers. Wall tops in left and right are at least coping_m. The collar of a box is at most half the chain. The collar of a pair is the larger of its two tubes. In a pair, the nearer opening moves onto the frame line of the other, so its shift (or mate_shift) includes that move.
    • Open for the owner. On test box B, 41 of the 65 pair records have tubes that overlap. Their axes are nearer than both outer half-widths, for example motorway carriageways 9 m to 13 m apart with a half of 6.6 m, or double tracks 3.6 m to 4 m apart. Rung 2 as designed (half of 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.
    • For P4: graph::open matches the end vertex on the first or last vertex of a part. A cell whose grown square ends within shift of the vertex does not see it (the trim of graph::parts), so the stretch stays a tunnel there. This is more than 170 m from the square of that cell.

    Generated by Claude Code

  2. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    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 own tunnel-tube records over its whole length. Near the none end, 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

  3. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    P2 (#3679, #3737): what changed for the reader of the tube records

    • Chord heights differ. Each tunnel-tube has the floor of P2 as its z and its own height: the lesser height of its two vertices, at most the tube's height and at least least_height_m of 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.
    • A step at an opening. The tunnel-end keeps the height of its tube; only the chords get lower. At 93 of 948 drawn openings on test box B, the first chord is lower than the height of its tunnel-end: 82 box, 8 arch, 1 pair, 2 free, up to 1.02 m (at a box). 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 the z of a tunnel-end.
    • More records. A tube has a vertex at each end of the window of a way on top. The zoom-13 tiles of test box B hold 18,398 tunnel-tube records in place of 15,159.

    Generated by Claude Code

  4. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    P2 (#3679, #3737) after its review: the height of an opening

    This replaces the second point of my earlier comment here.

    • No step at an opening. The floor now runs before the numbers of the openings. Each tunnel-end takes the height of the tube's chord at its vertex, and its face reads that height. On test box B, no opening is higher than its first chord (0 of 948).
    • Chords. Each tunnel-tube still has its own height, the lesser of its two vertices. Between two chords of different height, the ring face of Plan 5 closes the step, as planned.
    • More records. A tube gets a vertex where it enters and leaves the reach of a way on top. The zoom-13 tiles of test box B hold 20,567 tunnel-tube records in place of 15,159.

    Generated by Claude Code

  5. timohueser commented on Nov 20, 2026

    @timohueser
    OwnerAuthor

    Done in #3754 (merged).

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