Skip to content

TrailView ground plan GP5: the WASM bridge, the plan worker, the timing page and the debug draw of the faces #3100

Closed

Description

@timohueser

Status: approved
Part of #3096. One pull request into ground-plan.
Depends on: #3112 (GP3)

TL;DR

Goal: With ground=plan in the address, a worker builds the ground plan of each cell near the eye in WASM, plan=faces draws its faces and edges over the view, the HUD shows the build times, a timing page measures a cell build in any browser, and CI proves that the native build and the WASM build give the same bytes for every fixture cell, from the same request bytes as the viewer's.
Problem: The crate (GP1 to GP4) runs only natively, and it has no entry that builds a whole cell. TrailView loads no WASM (epic, Facts). Nobody can see the faces in the viewer, nobody knows the time of a cell build in a browser or on the iPhone, no guard limits the size of a bridge for the crate, and no check compares the native and the WASM output (epic, section 14, check 7).
Decision: The crate gains build_cell (graph, then faces) and a transport module: one request codec over GP1's CellInput, one flat output and one digest, so the viewer, the timing page, the native check and a later iOS library use the same bytes. A new thin wasm-bindgen crate obc-ground-plan-bridge in builder/ground-plan-wasm, built by builder/build-wasm-bridges.sh into builder/web/src/lib/trailview/plan/pkg, with a budget in builder/wasm/wasm_size_guard.py. A Plan module on the main thread picks the cells, names their inputs with the bridge's wanted (GP1's Terrain::wanted), and sends the inputs to one plan worker. The worker returns the stats, the stage times, the digests and, when the debug draw is on, a debug mesh. The debug draw is its own render pass on the canvas after the resolve; it hides a face only where the scene lies more than 50 m in front of it.
Rejected:

  • Add the crate to obc-builder-bridge: TrailView would load the builder core (478 kB gzip), and the two budgets would mix.
  • Build cells on the main thread: one synchronous build blocks the frames. The main thread calls only wanted and vocabulary.
  • Share the road worker: GP19 deletes it.
  • WASM threads: the site host forbids them (.github/workflows/deploy-site.yml:42-52).
  • A new value of debug= for the faces: every index above 4 goes to the ground debug colours (terrain/terrain.wgsl:121, ground/look.wgsl:869), and every debug view hides the corridors (roads/corridor.wgsl:146).
  • Draw the faces in the scene pass with a depth test: corridors, houses and trees stand over the terrain and hide the faces from above, and the TAA and finish() change the colours of the debug tool.
  • A request codec or an input walk in TypeScript: a second copy of the codec and of GP1's Terrain::wanted, to keep equal by hand.
  • Triangulate the faces for the debug draw in the crate: the crate gets its triangulation only in GP7; earcut is already a dependency of the viewer (builder/web/package.json:27, terrain/water-mesh.ts:6).
  • A committed file of digests for check 7: every later item changes it.
  • The timing page on the release path: the time mixes network and decode with the build. Prepared request files time only the build.
    Systems: trailview
    Contracts: docs/design/trailview.md: owns gains builder/ground-plan-wasm/**. No spec changes: the request and the flat output live inside one build and are never stored across builds.
    Size: L (the epic says M): about 750 lines of Rust with tests, about 1,300 lines of TypeScript and WGSL, CI and tooling edits; no change to the old path's behaviour.

Facts

Paths under builder/web/src/lib/trailview/ unless they start with another top folder.

  • The one bridge today: wasm-pack build builder/wasm --release --target web --out-dir ../web/src/lib/core/pkg (builder/build-wasm-bridges.sh:7-9); crate-type = ["cdylib", "rlib"] and wasm-opt = ['-Oz'] (builder/wasm/Cargo.toml:9,46). Its loader passes { module_or_path } to the generated init (lib/core/bridge.ts:13).
  • The size guard holds one budget per module and one package folder per module (builder/wasm/wasm_size_guard.py:20-22,31-35); its GOVERNS lists builder/wasm/** and host/obcm-assemble/** (:9).
  • CI builds the bridges once in the job wasm-bridges and uploads each package (.github/workflows/ci.yml:753-786). The jobs web, web-browser and desktop-frontend download them (ci.yml:1030,1098,1147). The weekly TrailView job builds no bridge (.github/workflows/test-weekly.yml:35-57).
  • tools/test_plan.py:66-69 names the package of wasm-bridges, and a test pins it to the packages of the build script (tools/tests/test_selection_plan.py:740-746). BRIDGES and BRIDGE_PACKAGE (tools/test_plan.py:746-747) are the package folders and the package that local_setup builds for (:806). local_setup builds the bridges only for a job whose needs holds wasm-bridges (:762); the job wasm-bridges itself needs only selection (:66-69).
  • One module and one heap per realm; a worker loads its own instance (lib/core/bridge.ts:10-21, lib/assemble/assemble.worker.ts:1-7). A worker blocked in a synchronous WASM call cannot read its inbox, so a cancel terminates it (assemble.worker.ts:4-7). Workers are ES modules (builder/web/vite.config.ts:79-87).
  • Roads builds owners 300 m before they come into range (roads/roads.ts:24), keeps 32 MiB of meshes (:30), and marks a failed owner FAILED until it is trimmed (:226-248). GP19 deletes roads/.
  • A stored tile decodes to four pages of 256² r16 codes with an offset and a scale per page: tilePages and pageData (stream/heights.ts:19-39), in the decode worker (stream/decode-worker.ts:5-12). The scale is a JS number (f64, heights.ts:37); GP1's StoredPage holds f32 offset and scale. The pages module sends the pages to the GPU and keeps only the encoded bodies (terrain/pages.ts:452, :492-496).
  • A feature tile body can be gzip; features.ts gunzips it with DecompressionStream (stream/features.ts:80-81). featureTiles hands out a copy of each body (stream/terrain.ts:146).
  • Terrain makes Roads with pages.body (terrain/terrain.ts:222), lets it build once the pages about the eye are idle (:448-449), and waitForIdle waits for road meshes (engine.ts:330).
  • scale is a page option outside View: scaleOf(search) (resolve/targets.ts:16-19); formatView keeps every parameter that is not part of a view (view.ts:66-81). shoot.mjs opens trailview.html${view} (shoot.mjs:47).
  • The route drapes on the surface with stand_height in its vertex stage (route/route.wgsl:85-87); a vertex of unknown height takes the eye's ground (route.wgsl:119). The route binds the frame, the surface, an empty group and the features (route/route.ts).
  • The scene depth is reversed Z, depth = NEAR / distance along the view; a later pass reads it (structures/light-pools.wgsl:2-3,31,95). The resolve writes the canvas after the scene pass (engine.ts:637-639).
  • distances(eye, node) includes the eye's height above the ground (terrain/lod.ts:65-75).
  • wasm-bindgen 0.2.125 and serde are in the workspace (Cargo.lock); GP1 gives the crate serde_json; earcut 3 is in builder/web/package.json:27.
  • The README of TrailView is at its prose budget; tables and code do not count (tools/prose.py, tools/testing/prose-baseline.json). It states no noise band for flight times.
  • GP1: one zoom-13 feature tile per cell; StoredPage holds levels 13 and 14 with f32 offset and scale; the debug tool is the cargo example debug, its palette in examples/debug/draw.rs.

Design

Words of this item

  • Request: the bytes of one cell's inputs: the cell key, its zoom-13 feature tile, its stored terrain pages.
  • Flat plan: the crate's output as flat integer arrays, the stats as JSON, and a digest.
  • Debug draw: plan=faces in the address: the faces as fills and the edges as lines over the view.
  • Vocabulary: the names and colours that the crate states once: stages, surfaces, owners, height rules, edge kinds.

1. The cell entry and the transport (host/obc-ground-plan/src/cell.rs, src/transport.rs)

The crate owns the entry and the codec, so the bake, the WASM and a later iOS library read one format. It has no browser code.

Entry (cell.rs): build_cell(input: &CellInput, rules: &Rules, now: &mut dyn FnMut() -> f64) -> CellBuild, in GP1's to GP3's names:

  1. graph::build(input.key, input, rules);
  2. build_faces(&graph, features of input, rules, input.key, 0, true). GP4's sidewalks run inside it, as its phases (a) to (e).
  • CellBuild { key, graph: GraphStats, faces: FacePlan, times: Vec<f64> }. The bridge's CellPlan wraps it.
  • The entry calls now() (milliseconds) before step 1 and after each step, and keeps the differences as times, one per stage in vocabulary order (graph, faces). Invariant: no output byte depends on the clock. A caller that does not time passes &mut || 0.0.
  • The entry builds level 0 only. GP12 adds the deck levels.

Request (little-endian, 4-byte aligned):

Field Type
magic b"OGPR"
cell x, y u32, u32 (zoom 16)
tile length u32, u32::MAX when the archive holds no tile
tile the plain format-4 bytes of key.feature_tile() (never gzip), zero padding to 4
page count u32
per page level: u32 (13 or 14), x: u32, y: u32, offset: f32, scale: f32, 65,536 × u16 codes (row by row from north, 0xFFFF unknown)
  • Request { key: CellKey, tile: Option<Vec<u8>>, pages: Vec<StoredPage> }, with encode(&self) -> Vec<u8>, decode(&[u8]) -> Result<Request, String> and input(self) -> Result<CellInput, String> (GP1's CellInput::new).
  • Invariant: the encoding is canonical. encode sorts the pages by (level, x, y). decode refuses a wrong magic, a truncation, trailing bytes, a page that Terrain::wanted(key) does not name, a page with another count of codes, and a repeated page. So equal inputs give equal bytes, and the order in which the viewer collects inputs cannot change a result.
  • A page is GP1's StoredPage: the viewer's PageData with offset and scale rounded to f32.

Flat plan (Flat::of(&CellBuild)), field for field from GP3's FacePlan, all integers in the cell frame (1/16 world unit):

  • vertices: Vec<i32>: x, y pairs (FacePlan.vertices).
  • An owner is 4 words: kind (index into owners), id (the WayId, JunctionId or FeatureId as u32; u32::MAX for Terrain), the dm of Bend (i64, low word first; 0 else). An f64 is two words of its bits, low first.
  • faces: Vec<u32>, 15 words per face: id, owner, surface code, level (i8 as i32 bits), height rule code, material and crossing (u32::MAX for none), rank, inside (0 or 1), reach_m (f32 bits), first ring, ring count.
  • rings: Vec<u32>, 2 words per ring: first index into ring_vertices, count. The first ring of a face is its outer ring; the others are holes.
  • ring_vertices: Vec<u32>: indices into vertices.
  • edges: Vec<u32>, 6 words per edge: a, b, left, right, kind code, flags.
  • corners: Vec<u32>, 14 words per CornerArc: owner, centre, radius_m, t_a, t_b, first point, point count; corner_points: Vec<i32>: the x, y pairs of the arcs.
  • The second of GP4 and GP5 to merge adds GP4's output: a kerb word per face (u32::MAX for none), markings (per zebra face: face id, origin (i64) and along (f64), two words each) and kerbs (per KerbProfile: rise_m, then the count and the words of its kerb edges, tapers and drops).
  • stats: String: {"graph": GraphStats, "faces": FaceStats, "inputs": {"pages": n, "tile": bool, "request": "<digest>"}} as JSON. The stats types derive serde::Serialize; every stat is an integer, so no NaN can reach the bytes.
  • canonical_bytes() -> Vec<u8>: b"OGPP", the cell, then each array with its u32 length, then the stats bytes. Times are not in it.
  • digest() -> String: FNV-1a 64 over the canonical bytes, 16 hex digits. The request digest is the same hash over the request bytes. It finds a difference; it is no security hash.
  • Every later item that adds output (pieces, floors, the plan layer, objects) adds it to Flat and the canonical bytes, so check 7 covers it.

Vocabulary (vocabulary() -> String, JSON): {"stages": [...], "surfaces": [{"name", "colour"}], "owners": [...], "rules": [...], "edges": [{"name", "colour"}]}, in code order. The colours are #rrggbb. GP5 moves the debug tool's palette from examples/debug/draw.rs into src/debug.rs (constants only, no dependency) and adds colours for the edge kinds there. The tool and the vocabulary read it, so the debug tool and the viewer show the same colours.

2. The debug tool: requests

GP1's debug tool gains one command:
obc exec cargo run --release -p obc-ground-plan --example debug -- requests --out DIR (--places NAMES | --all) [--runs N]

  • --places takes place names as the tool's --places does; --all takes Fixture::cells().
  • For each cell: the tile key.feature_tile() and the pages Fixture::pages(&Terrain::wanted(key)) as a Request; DIR/<x>-<y>.bin; N native builds (default 5) with an Instant clock.
  • DIR/index.json: [{ "cell": [x, y], "file", "places": [names], "request": digest, "digest", "native": { "<stage>": median ms, "total": median ms } }].

3. The bridge (builder/ground-plan-wasm)

Package obc-ground-plan-bridge, a member of the root workspace. crate-type = ["cdylib", "rlib"]. Dependencies: obc-ground-plan; on wasm32: wasm-bindgen, console_error_panic_hook. wasm-opt = ['-O3']: the cell build time on a phone is the epic's first risk, and the file loads once and stays in the cache.

Exports (all under cfg(target_arch = "wasm32")):

  • start(): the panic hook.
  • vocabulary() -> String.
  • wanted(x: u32, y: u32) -> Vec<u32>: Terrain::wanted of the cell, 7 words per page: level, page x, page y, then PageKey::tile(): tile z, x, y and the quadrant.
  • class CellRequest: new(x: u32, y: u32), set_tile(bytes: &[u8]), add_page(level: u32, x: u32, y: u32, offset: f32, scale: f32, codes: &[u16]), to_bytes() -> Vec<u8>.
  • build(request: &CellRequest) -> Result<CellPlan, JsError> and build_bytes(bytes: &[u8]) -> Result<CellPlan, JsError>: both go through Request::decode (so the viewer's request meets the same checks) and call build_cell with the embedded rules and a clock from performance.now() (an extern import, which exists in workers and in Node).
  • class CellPlan: vertices() -> Vec<i32>, faces(), rings(), ring_vertices(), edges() -> Vec<u32>, stats() -> String, times() -> Vec<f64>, digest() -> String.
  • Gotcha: wasm-bindgen objects hold WASM memory until free(); the worker frees each in a finally.
  • No threads, no atomics, no getrandom. Check 7 finds a HashMap order or a float that differs between the two builds.

builder/ground-plan-wasm/check.mjs DIR: loads the package in Node (initSync with the bytes of *_bg.wasm), runs build_bytes once for each entry of DIR/index.json, compares the digest with the native one, prints cell digest native-ms wasm-ms, and exits 1 on any difference or error. builder/ground-plan-wasm/check-bytes.sh runs requests --all --runs 1 into a temporary folder, fails when the folder is larger than 512 MiB (about 320 cells at the largest request), runs check.mjs on it, then writes index.json without the files and times as builder/web/src/lib/trailview/plan/pkg/native.json. So the package artifact carries the native digests to the browser jobs (section 8).

The size guard: wasm_size_guard.py gains the module ground-plan with PKG_DIRS["ground-plan"] = builder/web/src/lib/trailview/plan/pkg, its budget, its advice (cargo tree -p obc-ground-plan-bridge --target wasm32-unknown-unknown), and GOVERNS gains builder/ground-plan-wasm/** and host/obc-ground-plan/**. The budget: the size of GP5's head build (raw WASM, and gzip WASM plus glue), each rounded up to the next 16 KiB, with the commit in a comment. A later item that raises it (GP7 adds spade) gives the reason in its pull request, as the guard's docstring says.

4. The inputs of a cell (plan/inputs.ts)

cellInputs(cell: Node, wanted, features, stored): Promise<CellInputs | 'empty'>, on the main thread, where wanted is the bridge's export, features is the FeatureTiles getter and stored is pages.body.

  • Feature tile: the zoom-13 tile that holds the cell (GP1: the 40 m buffer of format 4 holds the cell and its margin). If the tile is absent, the result is 'empty' and no worker runs.
  • Terrain: for each page of wanted(cell), the body of its stored tile (z, x, y), each tile once. An absent tile gives no page.
  • Failure: a fetch that fails (an error, not an absent tile) fails the cell. The cell is never built with a page left out, because then it would differ from the GPU pages and from the native build.
  • No import from roads/ (GP19 deletes it).

5. The plan worker (plan/plan-worker.ts)

  • On start, with {type: 'start', module: WebAssembly.Module} from Plan: init({ module_or_path: module }), start(), then it posts {type: 'ready'}. If init fails, it posts {type: 'ready', error}.
  • Build message {type: 'build', id, cell: {x, y}, tile?: ArrayBuffer, terrain: {z, x, y, body}[], pages: Uint32Array, debug: boolean}, where pages is wanted(cell). The tile comes transferred; terrain bodies come as copies, because the pages module keeps them.
    1. Gunzip the tile if it starts with 1f 8b (as stream/features.ts:81).
    2. Decode each terrain body with imagePixels and tilePages, the code of the decode worker, so the codes are the GPU's codes. A worker-local cache keeps the pages of the last 16 tiles (8 MiB), keyed z/x/y.
    3. For each wanted page, its tile's quadrant; a null quadrant (no known height) is left out. add_page with Math.fround of the offset and the scale, as GP1's StoredPage.
    4. build(request). Then the stats, the times, the digest, the WASM memory size (memory.buffer.byteLength of the init output) and, if debug, the debug mesh (section 7).
    5. Post {id, ok: true, stats, times, digest, heap, debug?: {fills: ArrayBuffer, edges: ArrayBuffer}} with the buffers transferred. On a JsError, post {id, error}. On any other throw (a trap: a panic, out of memory), post {id, error, trapped: true}; the instance is then not safe to use again.
  • Time message {type: 'time', id, request: ArrayBuffer, runs} for the timing page: build_bytes runs + 1 times; the first run is the cold one. It posts {id, cold, runs: number[][], digest, heap, counts}, where runs[i] holds the stage times and the total.

6. The plan on the main thread (plan/plan.ts)

class Plan, made by Terrain beside Roads only with the switch:
new Plan(features: FeatureTiles | undefined, stored: (z, x, y) => Promise<ArrayBuffer | undefined>, bounds: [west, north, east, south] (world units), changed: () => void, stop: AbortSignal).

  • It compiles the WASM file once (WebAssembly.compileStreaming), inits a main-thread instance from the module for wanted and vocabulary (no build runs there), and posts the module to the worker. So the file downloads and compiles once.

Constants, each with its reason in a comment:

  • BUILD_M = 600: the mesh range of the epic (section 8).
  • AHEAD_M = 300: as AHEAD_M of roads/roads.ts:24, about 20 s of a car.
  • AHEAD_COS = 0.5: "ahead" is within 60° of the view direction.
  • KEEP_M = 1000: a cell drops past this distance. It is 100 m past BUILD_M + AHEAD_M, so a cell at the edge does not build again when the eye moves to and fro.
  • KEPT_BYTES = 32 * 2 ** 20: the CPU bytes of the records, as MESH_BYTES of roads/roads.ts:30.
  • HEAP_LIMIT = 55 * 2 ** 20: the epic's worker heap (section 15). WASM memory never shrinks, so a worker past it ends after its current build and a new one starts.

update(eye: {x, y, unit, above}, ahead: [number, number] | undefined, build: boolean): boolean, called by Terrain.update next to roads.update, with the same build flag (roadsFree):

  1. Wanted cells: every level-16 node whose square meets bounds and whose LOD distance distances({anchor, above}, node)[0] is below BUILD_M, by distance; then every node with a distance from BUILD_M to BUILD_M + AHEAD_M whose middle lies ahead, by distance. ahead is the eye's horizontal view direction as a unit vector in world units (x east, y south); it is undefined when its horizontal part is below 0.1 of the forward vector, such as at pitch −89, and then no cell counts as ahead. Nodes outside 0 ≤ x, y < 2^16 are never wanted.
  2. Records: built (stats, times, digest, an optional debug mesh, its bytes), empty, or failed (the message). Records are kept in priority order while their bytes stay below KEPT_BYTES; a wanted cell past the budget is not asked for. A record whose cell is past KEEP_M drops. When the debug draw is on, a built record without a debug mesh counts as missing, and its new build replaces it when it arrives.
  3. Dispatch: one worker holds at most two jobs: one runs, one waits, so the worker does not idle while the main thread collects inputs. While it holds fewer and build is true, the first wanted cell without a record and not pending collects its inputs (section 4) and goes to the worker. No job goes out before ready.
  4. Results: a result for a cell past KEEP_M drops. A trapped result makes the cell failed, terminates the worker and starts a new one; the waiting job goes back to "not asked". A worker whose heap passes HEAP_LIMIT ends the same way after its job, with no failure. Each restart counts.
  5. Returns true when the set of drawn debug meshes changed (the engine's newContent).

loading: true while a wanted cell within BUILD_M has no record. False when the bridge failed to start, so waitForIdle never hangs.

stats: PlanStats: { cells, building, failed, restarts, ready, build: {median, p95, stages: Record<string, number>}, heap, debugVertices, digests: Record<"x-y", {request, plan}>, error? }. build is over the last 32 builds. ready is the time from the first frame in which a cell within BUILD_M has no record to the next frame in which every one has a record; after a jump, it is the time to a complete view. heap is the largest heap of a worker. digests holds each built record.

debug: boolean: set by the engine from View.plan.

7. The debug draw (plan/debug.ts, plan/debug.wgsl)

debugMesh(flat, vocabulary, cell): { fills: Int32Array, edges: Int32Array }, in the worker. A vertex is 3 words: x and y in world units (i32), the colour as sRGB bytes with alpha (red lowest).

  • Fills: each face with a surface other than terrain goes through earcut (outer ring and holes, in the face's coordinates). Each triangle is clipped to the squares of a grid of FILL_GRID_M = 2.8 (a convex clip, then a fan), so no edge is longer than the diagonal, 4 m. The count grows linearly with the area and the length: a 400 × 6 m strip gives about 1,150 triangles. The colour is the surface colour with alpha FILL_ALPHA = 0.5. The terrain faces get no fill: they cover the rest of the cell, and their triangles would be hundreds of metres long.
  • Edges: every edge, from vertex a to b, in the colour of its kind, as segments of at most EDGE_STEP_M = 2, alpha 1; a CellBorder edge has alpha 0.4.
  • Metres per unit come from metresPerUnit at the cell's middle. World units are cell origin + round(point / 16). Rounding to 2.5 cm cannot hide a fault: the faces are at least GP3's minimum width wide.
  • Why the steps: each vertex drapes on the drawn surface, and a long triangle between draped vertices leaves the surface. From 60 m, a height error of 1 m at 50 m from the middle moves a point by 0.8 m on the screen; at 4 m steps, the error is a few centimetres.
  • A face that earcut gives no triangles draws its edges only. The worker counts such faces in stats.debug.unfilled, so a broken face never hides.

class PlanDebug (owned by Plan): two vertex buffers (gpu.buffer('plan', …), made larger by 1.5 when too small), filled again only when the set of drawn meshes changes: every built record within KEEP_M with a debug mesh. A failed record adds a red outline of its cell square (made on the main thread, same steps), so a failed cell is never invisible.

debug.wgsl (// #include ../terrain/drawn-mesh.wgsl, Frame as in route.wgsl):

  • vertex input @location(0) at: vec2i (sint32x2), @location(1) colour: vec4f (unorm8x4).
  • s = lod_space(vec2f(at - surface.anchor)), h = stand_height(s, at) plus LIFT_M = 0.05, the position as eye_space of route.wgsl. A vertex of unknown height takes the eye's ground (route.wgsl:119) and passes known = 0, else 1. The vertex also passes its distance along the view.
  • fragment: it discards where the interpolated known is below 1, so a primitive with an unknown vertex draws nothing. It reads the scene depth at its texel at render scale (textureLoad, reversed Z) and discards where it lies more than HIDDEN_M = 50 past the scene: a hill hides the faces behind it, but no house or tree hides a face from above. Else the premultiplied colour.
  • Two pipelines: triangle-list and line-list; target gpu.format; blend one, one-minus-src-alpha; no depth attachment, no culling.
  • Groups as route.ts: the frame, the surface, the scene depth in place of the empty group, the features.

drawDebug(encoder, canvas: GPUTextureView, depth: GPUTexture, surface, features): one render pass after this.resolve.encode in engine.ts, with loadOp: 'load' on the canvas texture. So the faces show with the debug tool's colours, at the canvas resolution, and the scene's TAA does not touch them. The frame's view_proj holds the TAA jitter, so the overlay moves by less than a pixel while a still view gathers its frames.

8. The switch, the address, the engine and the HUD

  • view.ts: groundPlanOf(search: string): boolean, true for ground=plan. It is a page option as scale is: read once, because it decides which workers exist. PLAN_VIEWS = ['off', 'faces'] as const; View.plan: PlanView, default 'off'; parseView reads plan, formatView writes it when it is not 'off'. The list leaves room for a later mesh view (GP7).
  • trailview.ts: TrailView.start(canvas, gpu, release, view, scaleOf(location.search), groundPlanOf(location.search)). TrailView.start gains plan = false as its last parameter; the planner (lib/planner/trailview-start.ts:36) passes nothing.
  • engine.ts: passes plan to Terrain; keeps plan in extras; sets terrain.plan.debug; attaches PlanDebug with the late passes (engine.ts:421); draws it after the resolve when extras.plan === 'faces'; adds plan to stats(); waitForIdle also waits while terrain.plan?.loading; exposes readonly groundPlan: boolean.
  • terrain/terrain.ts: readonly plan?: Plan, made with pages.body and the bounds; update calls plan.update beside roads.update and adds its result to newContent. Without the switch, no Plan, no worker and no WASM request exist.
  • hud.ts, only with the switch: a line plan 14 cells · 1 building · 0 failed · 0 restarts · build 82 ms (graph 11 · faces 64) · ready 1240 ms · heap 31 MiB, a select plan: off | plan: faces, and the bridge's start error on the ! line.
  • The old path stays as it is: with ground=plan and plan=off, the view draws as without the switch. The corridors still draw (GP9 replaces them).

9. The timing page (builder/web/plan-timing.html, src/plan-timing.ts)

  • The address: requests (a folder URL that holds index.json, required), runs (1 to 50, default 5), cells (optional, x-y names separated by commas).
  • It starts one plan worker, the same module as the viewer's, and sends one time message per cell, one after the other. It needs no WebGPU.
  • It shows the user agent, navigator.hardwareConcurrency, the size of the WASM file (resource timing), and per cell: the places, the faces and edges, the cold build, the median and p95 per stage and in total, the native median and the ratio, the heap, and whether the digest equals the native one. Then a summary: the median and p95 over the cells of the per-cell median, the largest heap, and the count of equal digests. So the page also runs check 7 on Safari's engine.
  • A button copies the result as JSON; window.planTiming holds it, with done: true at the end.
  • The page is not in any build: the dev server serves it. The owner runs npm run dev -- --host in builder/web and opens http://<host>:5173/plan-timing.html?requests=/@fs/<repository>/.artifacts/ground-plan/requests/; server.fs.allow already holds the repository root. The requests command prints this address.

10. Edge cases

  • Empty input: no feature tile for the cell gives an empty record and no build. A tile with no way in the cell gives the plan that the crate gives (a terrain face or none); the debug draw shows the cell border only.
  • Release bounds: cells outside the bounds are never wanted. A cell at the bounds builds with the pages that exist.
  • Absent terrain: absent pages or unknown codes give unknown heights; the crate's reader handles them (GP1). The faces of GP3 and GP4 do not read the terrain, so the debug draw is complete there; a primitive with a vertex of unknown height does not draw.
  • Failed fetch: the cell fails and shows a red square. It builds again only after it drops past KEEP_M and comes back, as Roads does.
  • Trap or out of memory: the cell fails, the worker restarts, the other cells build. The crate must not panic (the rules decide every case), but a panic never stops the view.
  • Request refused (decode or CellInput::new fails): the cell fails with the message; the worker goes on.
  • High eye: with above above BUILD_M, no cell is wanted and loading is false.
  • Debug draw switched on: the kept cells build again with debug meshes, nearest first; old records stay until then.
  • plan=faces without ground=plan: nothing draws and the HUD shows no plan line.
  • Faces with holes, cell borders: holes go to earcut; the cell border edges are faint, so neighbour cells show their shared border.
  • Faces behind a hill: the depth read hides them; faces less than 50 m behind a surface still show.

11. Interfaces with the other items

  • GP1 gives CellInput::new, StoredPage, Terrain::wanted, PageKey::tile, the fixture loader and the debug tool; GP5 adds requests and moves the palette into src/debug.rs.
  • GP2 gives graph::build and GraphStats; GP3 gives build_faces, FacePlan and FaceStats. GP5 flattens them without changing them.
  • GP4's sidewalks run inside build_faces; the second of GP4 and GP5 to merge adds kerb, marking and kerbs to Flat (section 1).
  • GP7 adds pieces and floors to Flat, the canonical bytes and the build result; it uses the timing page and ready, and it sets the worker count and the time gates.
  • GP9 adds the GPU pools of the pieces to Plan and turns off the corridors under the switch.
  • GP10 adds the plan layer; GP12 the deck levels; GP16 and GP17 add objects.
  • No rule-table field changes in GP5.

Plan

  1. host/obc-ground-plan/src/cell.rs: build_cell, CellBuild. src/transport.rs: Request (encode, decode, canonical order, input), Flat::of, canonical_bytes, digest, vocabulary. src/debug.rs: the palette, with edge colours. Cargo.toml: serde with derive; GraphStats and FaceStats derive Serialize. Tests: section Verification.
  2. GP1's debug tool: the command requests (section 2); draw.rs reads the palette of src/debug.rs.
  3. builder/ground-plan-wasm/: Cargo.toml, src/lib.rs (the exports of section 3), check.mjs, check-bytes.sh, README.md. Root Cargo.toml: the member.
  4. builder/build-wasm-bridges.sh: a third wasm-pack build builder/ground-plan-wasm --release --target web --out-dir ../web/src/lib/trailview/plan/pkg --out-name obc_ground_plan_bridge. .gitignore: the folder. builder/wasm/wasm_size_guard.py: the module ground-plan, its budget and GOVERNS.
  5. tools/test_plan.py: "obc-ground-plan-bridge" in the packages of wasm-bridges; the new folder in BRIDGES; BRIDGE_PACKAGE becomes BRIDGE_PACKAGES with both packages, tested with any(...). local_setup also counts the job wasm-bridges itself as needing the build, and after the build it runs check-bytes.sh when plan/pkg/native.json is absent or a bridge changed. tools/tests/test_selection_plan.py: a test that local_setup(["wasm-bridges"]) on a checkout with no packages gives the build and the check. tools/testing/suites.toml: suite ci.ground-plan-bytes, route ordinary, command bash builder/ground-plan-wasm/check-bytes.sh, jobs ["wasm-bridges"], rust_packages = ["obc-ground-plan-bridge"], triggers builder/ground-plan-wasm/**, host/obc-ground-plan/**, data/trailview/** (the crate embeds it) and builder/web/tests/browser/trailview/fixture/**.
  6. .github/workflows/ci.yml, job wasm-bridges: actions/setup-node@v4 (Node 22); the guard step for --module ground-plan; the step bash builder/ground-plan-wasm/check-bytes.sh after the build, every time the job runs, because native.json must reach the browser jobs; the upload obc-ground-plan-bridge-pkg. Jobs web, web-browser, desktop-frontend: its download. .github/workflows/test-weekly.yml, job trailview: the Rust toolchain, wasm-pack@0.15.0 and bash builder/build-wasm-bridges.sh and check-bytes.sh before npm ci.
  7. docs/design/trailview.md: owns gains builder/ground-plan-wasm/**.
  8. view.ts (groundPlanOf, PLAN_VIEWS, View.plan), src/trailview.ts, engine.ts, terrain/terrain.ts (section 8).
  9. plan/inputs.ts (cellInputs), plan/plan.ts (Plan, wantedCells(eye, ahead, bounds) as a pure function, PlanStats), plan/plan-worker.ts.
  10. plan/debug.ts (debugMesh, PlanDebug), plan/debug.wgsl.
  11. hud.ts: the plan line and the select.
  12. builder/web/plan-timing.html, builder/web/src/plan-timing.ts.
  13. tests/browser/trailview/shoot.mjs and flight.mjs: --query Q appends &Q to each view; shoot.mjs adds plan: {cells, failed, ready, heap} to its JSON line when the stats hold a plan.
  14. Tests (Verification), then the READMEs: the TrailView README gets rows in its tables only (Layout: plan/; The address: ground, plan; Shots and flights: --query, the timing page command).
  15. Measurements and pictures; the pull request with Mode: change #<this issue> and Requirements: none.

Files

  • host/obc-ground-plan/src/cell.rs, src/transport.rs, src/debug.rs: create: the entry, the request codec, the flat plan, the digest, the vocabulary, the palette.
  • host/obc-ground-plan/src/lib.rs, Cargo.toml, the stats types of GP2 and GP3: change: the modules, serde, Serialize.
  • host/obc-ground-plan/examples/debug/main.rs, draw.rs: change: the command requests, the palette from the library.
  • builder/ground-plan-wasm/Cargo.toml, src/lib.rs, check.mjs, check-bytes.sh, README.md: create: the bridge, check 7 and how to run it and the timing page.
  • Cargo.toml: change: the member. Cargo.lock: change.
  • builder/build-wasm-bridges.sh: change: the third build.
  • builder/wasm/wasm_size_guard.py: change: the module ground-plan.
  • .gitignore: change: builder/web/src/lib/trailview/plan/pkg/.
  • tools/test_plan.py, tools/tests/test_selection_plan.py, tools/testing/suites.toml: change: the job's packages, the folders, local_setup, the suite.
  • .github/workflows/ci.yml, .github/workflows/test-weekly.yml: change: build, guard, check 7, uploads and downloads.
  • docs/design/trailview.md: change: owns.
  • builder/web/src/lib/trailview/view.ts, view.test.ts: change: plan, groundPlanOf, their test.
  • builder/web/src/trailview.ts, engine.ts, terrain/terrain.ts, hud.ts: change: the switch, the draw, the stats, the HUD.
  • builder/web/src/lib/trailview/plan/inputs.ts, plan.ts, plan-worker.ts, debug.ts, debug.wgsl: create.
  • builder/web/src/lib/trailview/plan/debug.test.ts, plan.test.ts: create.
  • builder/web/plan-timing.html, builder/web/src/plan-timing.ts: create: the timing page.
  • builder/web/tests/browser/trailview/shoot.mjs, flight.mjs: change: --query, the plan line.
  • builder/web/tests/browser/trailview/smoke.test.js: change: one test with the switch.
  • builder/web/src/lib/trailview/README.md: change: table rows only.

Verification

  • Checks:
    • obc test -p obc-ground-plan and obc test -p obc-ground-plan-bridge: the request round trip; two requests with the same inputs in another order encode to the same bytes; decode refuses each malformed case of section 1, a page that wanted does not name among them; vocabulary() parses and lists one colour per surface and per edge kind; Flat::of keeps every field of FacePlan (a face with each owner kind, material, crossing, rank, inside, reach_m, a corner arc and edge flags round-trips); the digest of a fixture cell is the same for two builds and for two different clocks.
    • obc exec cargo clippy -p obc-ground-plan -p obc-ground-plan-bridge --all-targets -- -D warnings and obc exec cargo clippy -p obc-ground-plan-bridge --target wasm32-unknown-unknown -- -D warnings (the WASM exports compile only there).
    • Check 7: npm run build:wasm in builder/web, then obc exec bash builder/ground-plan-wasm/check-bytes.sh: every fixture cell gives the same digest natively and in WASM. CI runs it in wasm-bridges. The pull request states the step's time and the folder's size; past 5 minutes it reports the cost to the owner.
    • python3 builder/wasm/wasm_size_guard.py --module ground-plan: inside the budget.
    • In builder/web: npx vitest run src/lib/trailview:
      • plan/debug.test.ts: debugMesh on a square with a hole and on a 400 × 6 m face: the fill area equals the face area to 0.1 %, no fill triangle edge is longer than 4 m, no edge segment is longer than 2 m, a terrain face has no fill, a face that earcut cannot fill counts in unfilled, and the 400 × 6 m face has at most 1,300 fill triangles (the clip of section 7 gives about 1,150 there; the gate holds the count linear).
      • plan/plan.test.ts: wantedCells orders by distance, puts the cells ahead after the near cells, takes none past BUILD_M + AHEAD_M, none outside the bounds and none for an eye 700 m above the ground. With the real package (initSync with the bytes of plan/pkg/*_bg.wasm, as test-support/core.ts loads the builder core): wanted of a cell lists pages of levels 13 and 14 only; a CellRequest with the tile of specs/vectors/trailview-features.bin for a cell under it gives stats.inputs = {pages: 0, tile: true, …}, rings and edges that index inside vertices, and the same digest twice.
      • view.test.ts: plan survives formatView and parseView; groundPlanOf is true only for ground=plan.
    • npm run check, npm run check:wgsl.
    • smoke.test.js, one new test, not @gpu: the village view of the smoke with &ground=plan&plan=faces at 480 × 300: after waitForIdle(), stats().plan has failed = 0, cells ≥ 1 and debugVertices > 0, the page has no error, and for each cell of stats().plan.digests the request digest and the plan digest equal those of plan/pkg/native.json. If the file is absent, the test fails and names check-bytes.sh. So the viewer's inputs (the tile, the WebP decode, the f32 rounding, wanted) equal the native ones, and the worker and the WASM asset survive the Vite build. The pull request states its time on SwiftShader.
    • obc suites check; cargo fmt --all; obc prose --check.
  • Measurements:
    • Size: bash builder/build-wasm-bridges.sh && python3 builder/wasm/wasm_size_guard.py --module ground-plan: raw and gzip of the head build, the budget of section 3.
    • Native and WASM time: obc exec cargo run --release -p obc-ground-plan --example debug -- requests --places v06,v12,v17,i07-hairpin,b45-bridge-junction --out .artifacts/ground-plan/requests, then the timing page in Chrome on the GTX box with runs=5, nice'd and alone on the machine. A table per stage: native median, Chrome median, ratio; the cold build; the largest heap; equal digests n/N. No gate: GP7 sets the gates.
    • Viewer: ready, heap and the largest debugVertices of a cell from the shoot.mjs lines of the five places below, on the GTX box.
    • The switch when off: once, a request log of the page without the switch shows no request of obc_ground_plan_bridge_bg.wasm and no plan worker, so no plan code runs. flock /tmp/trailview-gpu.lock node trailview/flight.mjs --gpu, the walk and drive flights, one run without the switch and one with --query ground=plan: the pass medians as a report, with no gate (the README states no noise band for flights, and with plan=off the plan draws nothing).
  • Pictures: flock /tmp/trailview-gpu.lock node trailview/shoot.mjs --gpu --views trailview/road-views-top.json --width 1920 --height 960 for v06-road-path-broken-top, v12-good-town-junctions-top, v17-sharp-corners-top, i07-hairpin-top and b45-bridge-junction-top (a views file with these five), three times: without the switch (before), with --query ground=plan (must equal before, to the noise of the README), and with --query 'ground=plan&plan=faces'. The same five from road-views.json at eye height with --query 'ground=plan&plan=faces'. One slider page of before and faces, with the debug tool's picture of each place beside it. The owner looks for: the faces in the viewer equal the debug tool's faces in shape and colour; the fills lie on the roads, tracks and paths of the view; the faces of two cells meet at the faint border with no gap and no overlap; no red square; at eye height, the faces follow the surface and no face shows through a hill. The timing page's output in Chrome on the GTX box, as a picture and as JSON.

Done when

  • bash builder/build-wasm-bridges.sh builds the third package, and the guard holds its budget in CI.
  • Check 7 passes in CI over every fixture cell, and the smoke test finds the viewer's request and plan digests equal to the native ones.
  • A page without ground=plan loads no plan WASM and starts no plan worker.
  • With ground=plan, the HUD shows the plan line; with plan=faces, the five places show their faces from above and at eye height, and the shots without plan=faces equal the old ones.
  • The timing page runs in Chrome on the GTX box, and the bridge README tells the owner how to open it on the iPhone.
  • All checks of Verification pass; the measurements and the pictures are in the pull request; the owner has looked at the pictures at the checkpoint of wave 4.

Out of scope

  • The mesh, its pieces and floors, the triangle counts and the time gates: GP7.
  • The far stamp: GP8.
  • The pools of the pieces, the ownership in the terrain, the range of the draw, turning off the corridors under the switch: GP9.
  • The plan layer and the readers: GP10.
  • Deck levels: GP12. Objects and edge features: GP16, GP17.
  • The worker count and the cell size: GP7, from its timings.
  • A static library for the iOS app.

Questions for the owner

Owner decision (2026-11-03): every recommendation in this section is accepted.

  1. The timing page on the iPhone runs from the Vite dev server on the home Wi-Fi (npm run dev -- --host, plain HTTP, the request files from .artifacts/ of timosPC). Is that acceptable, or must it be published with the site? Recommendation: the dev server; the page and its files never ship.

Epic note: Section 3 says that the viewer hands over the terrain samples "from its terrain decode worker". The pages module keeps no CPU copy of the codes (terrain/pages.ts:492-496 sends them to the GPU). So the plan worker decodes the cached tile bodies itself with tilePages, the decode worker's code; the codes are the same.

Epic note: Section 14, check 7, names no item. GP5 adds it, because GP5 adds the WASM build.

Review notes

  • Kept in part: README noise band for the flight gate: the TrailView README states none for flight times. The gate goes; the request log proves that the switch off runs no plan code.
  • Kept in part: longest-edge bisection: a sketch gives 4,374 triangles for a 400 m sliver at any width (length to the power 1.58). Section 7 clips to a 2.8 m grid: 1,146 for 400 × 6 m, gated.
  • Kept in part: depth slack 1 m: at 1 m, trees and houses hide faces from above (see Rejected). The slack is 50 m: hills hide faces, houses and trees do not.

Deviations in the implementation (they replace the text above where they differ)

  • Request: a cell reads one to four zoom-13 tiles (CellKey::feature_tiles, GP1). The request holds tile count: u32, then per tile column: u32, row: u32, length: u32, the bytes and zero padding to 4, in feature_tiles order; absent tiles are left out. decode also refuses a tile that feature_tiles does not name, a repeated tile, an order other than canonical and padding that is not zero. The bridge has CellRequest.add_tile(column, row, bytes) (no set_tile) and feature_tiles(x, y). A cell is empty only when none of its tiles exists.

  • Entry: build_cell(bytes, rules, now) -> Result<CellBuild, String>: stage input (decode, CellInput::new), then graph, then (GP3) faces.

  • Digest: FNV-1a 64 over the canonical bytes and the Debug text of the whole graph. It costs about as much as the graph build, so CellPlan.digest() is lazy; the worker computes it only for a build with the debug draw, and PlanStats.digests holds only those.

  • Flat: it also holds the graph: samples (x, y), ways (6 words: id, family, level, flags, first sample, count), points (5 words: kind, network, x, y, owned), crossings (5 words: x, y, kind, source, owned). The stats JSON is written from GraphStats::counters(); no serde derive.

  • Files: the GPU part of the debug draw is plan/draw.ts; plan/debug.ts is the mesh only, so the worker bundle takes no WGSL. start() runs at init.

  • Phase B (ground-plan GP5 phase B: the faces stage, the face words and the face debug draw #3136): build_cell(bytes, rules: &faces::Rules, now); stages input, graph, faces. Flat.faces: FaceWords holds the face arrays: vertices, faces (13 words: id, owner kind, owner id, surface, level, rule, material, crossing, rank, inside, reach_m bits, first ring, ring count; GP3's Owner has no Bend), rings (2), ring_vertices, edges (6), corners (12 words: owner kind, id, centre x, y, radius_m as two words, t_a, t_b, first point, count), corner_points. The vocabulary's surfaces carry fill (#rrggbbaa, null for terrain) and junction_surfaces the junction fills. The debug draw fills each face with trapezoids in the squares of the 2.8 m grid (slabs at the heights where an edge ends or leaves a square, walls paired by the even-odd rule), not with earcut; unfilled also counts a face whose fill differs from its area by more than 0.1 %, and the strip gate is 1,500 triangles. The size budget is the merged head (with GP3R's records) plus 5 %, rounded up to 16 KiB: 1,456 KiB raw, 560 KiB gzip, because the old budget fails CI; the 5 % is headroom for the stages before GP7, which sets the budget.

Activity

  1. timohueser commented on Nov 3, 2026

    @timohueser
    OwnerAuthor

    Deviation from GP1 (PR #3117), for this sub-issue: obc_ground_plan::terrain::pages_from_terrarium returns Result<_, String> on a wrong page size instead of a panic. The WASM bridge must pass the error to the worker.

  2. timohueser commented on Nov 3, 2026

    @timohueser
    OwnerAuthor

    Deviation from GP1 (PR #3117), for this sub-issue: Terrain::new(key, pages) takes the cell key and keeps only the pages that Terrain::wanted(key) lists, so heights depend on the cell alone. Terrain::height is defined only inside the cell grown by its margin and answers None past level 13; handle None, do not query outside that square.

  3. timohueser commented on Nov 3, 2026

    @timohueser
    OwnerAuthor

    Implementation plan

    Two phases. Phase A uses the stages that ground-plan has today (input, graph). Phase B adds the faces of GP3 after GP3 merges.

    Crate (host/obc-ground-plan)

    • transport.rs: Request { key, tiles: Vec<(column, row, bytes)>, pages }. A cell reads one to four zoom-13 tiles (CellKey::feature_tiles, GP1), so the request holds a tile list, not one tile (deviation). Absent tiles are left out. encode sorts the tiles in feature_tiles order and the pages by (level, x, y). decode refuses: a wrong magic, a truncation, trailing bytes, a tile that feature_tiles does not name, a repeated tile or page, a page that Terrain::wanted does not name, a page with another count of codes.
    • cell.rs: build(bytes, rules, now) -> Result<CellBuild, String>: stage input (decode, CellInput::new), stage graph (graph::build); GP3 adds stage faces. One time per stage from now(). No output byte reads the clock.
    • Flat: integer arrays of the graph for the debug draw (way samples, ways, points, crossings); phase B adds the face arrays of the issue. canonical_bytes(); digest() is FNV-1a 64 over the canonical bytes and the Debug text of the whole WayGraph (every float in round-trip form), streamed into the hash with no copy. So check 7 sees every field of the graph.
    • stats: JSON by hand from GraphStats::counters(), so no serde derive is needed (the crossings map has tuple keys).
    • debug.rs: the palette (families, links, synthetic decks, crossings); the debug tool and vocabulary() read it.
    • Debug tool: requests --out DIR (--places NAMES | --all) [--runs N].

    Bridge (builder/ground-plan-wasm, obc-ground-plan-bridge): start, vocabulary, wanted, CellRequest (add_tile(column, row, bytes), add_page, to_bytes), build, build_bytes, CellPlan. wasm-opt -O3. check.mjs and check-bytes.sh (check 7), the size guard module ground-plan, CI and suites.

    Viewer (plan/): inputs.ts (tiles and terrain bodies of a cell), plan-worker.ts (gunzip, WebP decode with tilePages, build, debug mesh, time message), plan.ts (Plan, wantedCells, records, dispatch, restarts), debug.ts and debug.wgsl (overlay pass after the resolve; reads the scene depth; hides only past 50 m). Phase A draws the graph as lines: ways in their family colour, junctions and crossings as marks. Phase B adds the fills and edges of the faces. ground=plan is a page option; without it no plan code loads.

    Timing page: builder/web/plan-timing.html, served by the dev server only.

    Invariants: native and WASM give the same digest for each fixture cell; equal inputs give equal request bytes; without ground=plan the viewer requests no plan WASM and starts no plan worker.

  4. timohueser commented on Nov 4, 2026

    @timohueser
    OwnerAuthor

    Phase A merges alone as #3124 (owner decision): bridge, worker, timing page, switch, graph debug draw. Phase B is still open and comes after GP3 (#3112) merges: the faces stage in build_cell, the face arrays in Flat, the face debug draw, and the WASM size budget measured again with GP3's i_overlay 9.1.0 (headroom before phase B: about 1 %). This issue stays open until phase B lands.

  5. timohueser commented on Nov 5, 2026

    @timohueser
    OwnerAuthor

    Phase B is merged into ground-plan with PR #3136, after the first review (comment 6655555097), the fix round, the delta review (comment 6658348749) and green CI (the web-browser smoke test was rerun after a slow-runner timeout). The owner approved the WASM guard's 5 % headroom until GP7. This closes GP5.

    Open from the delta review (small): the guard docstring still says the headroom is for the stages before GP7 (move that to this issue); the PR body's "99 %" is 95 % raw and 94 % gzip; the fixture test reads face words by number; the smoke test 2 uses 44–52 % of its 540 s limit, so a slow runner can make it fail again.


    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