Repository navigation
Description
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
wantedandvocabulary. - 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;
earcutis 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:ownsgainsbuilder/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"]andwasm-opt = ['-Oz'](builder/wasm/Cargo.toml:9,46). Its loader passes{ module_or_path }to the generatedinit(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); itsGOVERNSlistsbuilder/wasm/**andhost/obcm-assemble/**(:9). - CI builds the bridges once in the job
wasm-bridgesand uploads each package (.github/workflows/ci.yml:753-786). The jobsweb,web-browseranddesktop-frontenddownload 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-69names the package ofwasm-bridges, and a test pins it to the packages of the build script (tools/tests/test_selection_plan.py:740-746).BRIDGESandBRIDGE_PACKAGE(tools/test_plan.py:746-747) are the package folders and the package thatlocal_setupbuilds for (:806).local_setupbuilds the bridges only for a job whoseneedsholdswasm-bridges(:762); the jobwasm-bridgesitself needs onlyselection(: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). Roadsbuilds 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 deletesroads/.- A stored tile decodes to four pages of 256² r16 codes with an offset and a scale per page:
tilePagesandpageData(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'sStoredPageholdsf32offset 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.tsgunzips it withDecompressionStream(stream/features.ts:80-81).featureTileshands out a copy of each body (stream/terrain.ts:146). TerrainmakesRoadswithpages.body(terrain/terrain.ts:222), lets it build once the pages about the eye are idle (:448-449), andwaitForIdlewaits for road meshes (engine.ts:330).scaleis a page option outsideView:scaleOf(search)(resolve/targets.ts:16-19);formatViewkeeps every parameter that is not part of a view (view.ts:66-81).shoot.mjsopenstrailview.html${view}(shoot.mjs:47).- The route drapes on the surface with
stand_heightin 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
serdeare in the workspace (Cargo.lock); GP1 gives the crateserde_json;earcut3 is inbuilder/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;
StoredPageholds levels 13 and 14 withf32offset and scale; the debug tool is the cargo exampledebug, its palette inexamples/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=facesin 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:
graph::build(input.key, input, rules);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'sCellPlanwraps it.- The entry calls
now()(milliseconds) before step 1 and after each step, and keeps the differences astimes, 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> }, withencode(&self) -> Vec<u8>,decode(&[u8]) -> Result<Request, String>andinput(self) -> Result<CellInput, String>(GP1'sCellInput::new).- Invariant: the encoding is canonical.
encodesorts the pages by(level, x, y).decoderefuses a wrong magic, a truncation, trailing bytes, a page thatTerrain::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'sPageDatawith offset and scale rounded tof32.
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 (theWayId,JunctionIdorFeatureIdasu32;u32::MAXforTerrain), the dm ofBend(i64, low word first; 0 else). Anf64is two words of its bits, low first. faces: Vec<u32>, 15 words per face:id, owner, surface code, level (i8asi32bits), height rule code,materialandcrossing(u32::MAXfor none),rank,inside(0 or 1),reach_m(f32bits), first ring, ring count.rings: Vec<u32>, 2 words per ring: first index intoring_vertices, count. The first ring of a face is its outer ring; the others are holes.ring_vertices: Vec<u32>: indices intovertices.edges: Vec<u32>, 6 words per edge:a,b,left,right, kind code,flags.corners: Vec<u32>, 14 words perCornerArc: owner,centre,radius_m,t_a,t_b, first point, point count;corner_points: Vec<i32>: the x, y pairs of thearcs.- The second of GP4 and GP5 to merge adds GP4's output: a
kerbword per face (u32::MAXfor none),markings(per zebra face: face id,origin(i64) andalong(f64), two words each) andkerbs(perKerbProfile: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 deriveserde::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 itsu32length, 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
Flatand 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]
--placestakes place names as the tool's--placesdoes;--alltakesFixture::cells().- For each cell: the tile
key.feature_tile()and the pagesFixture::pages(&Terrain::wanted(key))as aRequest;DIR/<x>-<y>.bin;Nnative builds (default 5) with anInstantclock. 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::wantedof the cell, 7 words per page: level, page x, page y, thenPageKey::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>andbuild_bytes(bytes: &[u8]) -> Result<CellPlan, JsError>: both go throughRequest::decode(so the viewer's request meets the same checks) and callbuild_cellwith the embedded rules and a clock fromperformance.now()(anexternimport, 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 afinally. - No threads, no
atomics, nogetrandom. Check 7 finds aHashMaporder 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}fromPlan:init({ module_or_path: module }),start(), then it posts{type: 'ready'}. Ifinitfails, it posts{type: 'ready', error}. - Build message
{type: 'build', id, cell: {x, y}, tile?: ArrayBuffer, terrain: {z, x, y, body}[], pages: Uint32Array, debug: boolean}, wherepagesiswanted(cell). The tile comes transferred; terrain bodies come as copies, because the pages module keeps them.- Gunzip the tile if it starts with
1f 8b(asstream/features.ts:81). - Decode each terrain body with
imagePixelsandtilePages, 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), keyedz/x/y. - For each wanted page, its tile's quadrant; a null quadrant (no known height) is left out.
add_pagewithMath.froundof the offset and the scale, as GP1'sStoredPage. build(request). Then the stats, the times, the digest, the WASM memory size (memory.buffer.byteLengthof the init output) and, ifdebug, the debug mesh (section 7).- Post
{id, ok: true, stats, times, digest, heap, debug?: {fills: ArrayBuffer, edges: ArrayBuffer}}with the buffers transferred. On aJsError, 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.
- Gunzip the tile if it starts with
- Time message
{type: 'time', id, request: ArrayBuffer, runs}for the timing page:build_bytesruns + 1times; the first run is the cold one. It posts{id, cold, runs: number[][], digest, heap, counts}, whereruns[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 forwantedandvocabulary(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: asAHEAD_Mofroads/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 pastBUILD_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, asMESH_BYTESofroads/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):
- Wanted cells: every level-16 node whose square meets
boundsand whose LOD distancedistances({anchor, above}, node)[0]is belowBUILD_M, by distance; then every node with a distance fromBUILD_MtoBUILD_M + AHEAD_Mwhose middle lies ahead, by distance.aheadis 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 outside0 ≤ x, y < 2^16are never wanted. - Records:
built(stats, times, digest, an optional debug mesh, its bytes),empty, orfailed(the message). Records are kept in priority order while their bytes stay belowKEPT_BYTES; a wanted cell past the budget is not asked for. A record whose cell is pastKEEP_Mdrops. When the debug draw is on, abuiltrecord without a debug mesh counts as missing, and its new build replaces it when it arrives. - 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
buildis 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 beforeready. - Results: a result for a cell past
KEEP_Mdrops. Atrappedresult makes the cellfailed, terminates the worker and starts a new one; the waiting job goes back to "not asked". A worker whoseheappassesHEAP_LIMITends the same way after its job, with no failure. Each restart counts. - 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
terraingoes throughearcut(outer ring and holes, in the face's coordinates). Each triangle is clipped to the squares of a grid ofFILL_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 alphaFILL_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
atob, in the colour of its kind, as segments of at mostEDGE_STEP_M = 2, alpha 1; aCellBorderedge has alpha 0.4. - Metres per unit come from
metresPerUnitat the cell's middle. World units arecell 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
earcutgives no triangles draws its edges only. The worker counts such faces instats.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)plusLIFT_M = 0.05, the position aseye_spaceofroute.wgsl. A vertex of unknown height takes the eye's ground (route.wgsl:119) and passesknown = 0, else 1. The vertex also passes its distance along the view.- fragment: it discards where the interpolated
knownis 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 thanHIDDEN_M = 50past 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-listandline-list; targetgpu.format; blendone,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 forground=plan. It is a page option asscaleis: read once, because it decides which workers exist.PLAN_VIEWS = ['off', 'faces'] as const;View.plan: PlanView, default'off';parseViewreadsplan,formatViewwrites it when it is not'off'. The list leaves room for a latermeshview (GP7).trailview.ts:TrailView.start(canvas, gpu, release, view, scaleOf(location.search), groundPlanOf(location.search)).TrailView.startgainsplan = falseas its last parameter; the planner (lib/planner/trailview-start.ts:36) passes nothing.engine.ts: passesplantoTerrain; keepsplaninextras; setsterrain.plan.debug; attachesPlanDebugwith the late passes (engine.ts:421); draws it after the resolve whenextras.plan === 'faces'; addsplantostats();waitForIdlealso waits whileterrain.plan?.loading; exposesreadonly groundPlan: boolean.terrain/terrain.ts:readonly plan?: Plan, made withpages.bodyand the bounds;updatecallsplan.updatebesideroads.updateand adds its result tonewContent. Without the switch, noPlan, no worker and no WASM request exist.hud.ts, only with the switch: a lineplan 14 cells · 1 building · 0 failed · 0 restarts · build 82 ms (graph 11 · faces 64) · ready 1240 ms · heap 31 MiB, a selectplan: off | plan: faces, and the bridge's start error on the!line.- The old path stays as it is: with
ground=planandplan=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 holdsindex.json, required),runs(1 to 50, default 5),cells(optional,x-ynames separated by commas). - It starts one plan worker, the same module as the viewer's, and sends one
timemessage 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.planTimingholds it, withdone: trueat the end. - The page is not in any build: the dev server serves it. The owner runs
npm run dev -- --hostinbuilder/weband openshttp://<host>:5173/plan-timing.html?requests=/@fs/<repository>/.artifacts/ground-plan/requests/;server.fs.allowalready holds the repository root. Therequestscommand prints this address.
10. Edge cases
- Empty input: no feature tile for the cell gives an
emptyrecord 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_Mand comes back, asRoadsdoes. - 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 (
decodeorCellInput::newfails): the cell fails with the message; the worker goes on. - High eye: with
aboveaboveBUILD_M, no cell is wanted andloadingis false. - Debug draw switched on: the kept cells build again with debug meshes, nearest first; old records stay until then.
plan=faceswithoutground=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 addsrequestsand moves the palette intosrc/debug.rs. - GP2 gives
graph::buildandGraphStats; GP3 givesbuild_faces,FacePlanandFaceStats. GP5 flattens them without changing them. - GP4's sidewalks run inside
build_faces; the second of GP4 and GP5 to merge addskerb,markingandkerbstoFlat(section 1). - GP7 adds pieces and floors to
Flat, the canonical bytes and the build result; it uses the timing page andready, and it sets the worker count and the time gates. - GP9 adds the GPU pools of the pieces to
Planand 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
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:serdewithderive;GraphStatsandFaceStatsderiveSerialize. Tests: section Verification.- GP1's debug tool: the command
requests(section 2);draw.rsreads the palette ofsrc/debug.rs. builder/ground-plan-wasm/:Cargo.toml,src/lib.rs(the exports of section 3),check.mjs,check-bytes.sh,README.md. RootCargo.toml: the member.builder/build-wasm-bridges.sh: a thirdwasm-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 moduleground-plan, its budget andGOVERNS.tools/test_plan.py:"obc-ground-plan-bridge"in the packages ofwasm-bridges; the new folder inBRIDGES;BRIDGE_PACKAGEbecomesBRIDGE_PACKAGESwith both packages, tested withany(...).local_setupalso counts the jobwasm-bridgesitself as needing the build, and after the build it runscheck-bytes.shwhenplan/pkg/native.jsonis absent or a bridge changed.tools/tests/test_selection_plan.py: a test thatlocal_setup(["wasm-bridges"])on a checkout with no packages gives the build and the check.tools/testing/suites.toml: suiteci.ground-plan-bytes, routeordinary, commandbash builder/ground-plan-wasm/check-bytes.sh, jobs["wasm-bridges"],rust_packages = ["obc-ground-plan-bridge"], triggersbuilder/ground-plan-wasm/**,host/obc-ground-plan/**,data/trailview/**(the crate embeds it) andbuilder/web/tests/browser/trailview/fixture/**..github/workflows/ci.yml, jobwasm-bridges:actions/setup-node@v4(Node 22); the guard step for--module ground-plan; the stepbash builder/ground-plan-wasm/check-bytes.shafter the build, every time the job runs, becausenative.jsonmust reach the browser jobs; the uploadobc-ground-plan-bridge-pkg. Jobsweb,web-browser,desktop-frontend: its download..github/workflows/test-weekly.yml, jobtrailview: the Rust toolchain,wasm-pack@0.15.0andbash builder/build-wasm-bridges.shandcheck-bytes.shbeforenpm ci.docs/design/trailview.md:ownsgainsbuilder/ground-plan-wasm/**.view.ts(groundPlanOf,PLAN_VIEWS,View.plan),src/trailview.ts,engine.ts,terrain/terrain.ts(section 8).plan/inputs.ts(cellInputs),plan/plan.ts(Plan,wantedCells(eye, ahead, bounds)as a pure function,PlanStats),plan/plan-worker.ts.plan/debug.ts(debugMesh,PlanDebug),plan/debug.wgsl.hud.ts: the plan line and the select.builder/web/plan-timing.html,builder/web/src/plan-timing.ts.tests/browser/trailview/shoot.mjsandflight.mjs:--query Qappends&Qto each view;shoot.mjsaddsplan: {cells, failed, ready, heap}to its JSON line when the stats hold a plan.- 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). - Measurements and pictures; the pull request with
Mode: change #<this issue>andRequirements: 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 commandrequests, 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 moduleground-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-planandobc test -p obc-ground-plan-bridge: the request round trip; two requests with the same inputs in another order encode to the same bytes;decoderefuses each malformed case of section 1, a page thatwanteddoes not name among them;vocabulary()parses and lists one colour per surface and per edge kind;Flat::ofkeeps every field ofFacePlan(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 warningsandobc 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:wasminbuilder/web, thenobc exec bash builder/ground-plan-wasm/check-bytes.sh: every fixture cell gives the same digest natively and in WASM. CI runs it inwasm-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:debugMeshon 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 thatearcutcannot fill counts inunfilled, 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:wantedCellsorders by distance, puts the cells ahead after the near cells, takes none pastBUILD_M + AHEAD_M, none outside the bounds and none for an eye 700 m above the ground. With the real package (initSyncwith the bytes ofplan/pkg/*_bg.wasm, astest-support/core.tsloads the builder core):wantedof a cell lists pages of levels 13 and 14 only; aCellRequestwith the tile ofspecs/vectors/trailview-features.binfor a cell under it givesstats.inputs = {pages: 0, tile: true, …}, rings and edges that index insidevertices, and the same digest twice.view.test.ts:plansurvivesformatViewandparseView;groundPlanOfis true only forground=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=facesat 480 × 300: afterwaitForIdle(),stats().planhasfailed = 0,cells ≥ 1anddebugVertices > 0, the page has no error, and for each cell ofstats().plan.digeststhe request digest and the plan digest equal those ofplan/pkg/native.json. If the file is absent, the test fails and namescheck-bytes.sh. So the viewer's inputs (the tile, the WebP decode, thef32rounding,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 withruns=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,heapand the largestdebugVerticesof a cell from theshoot.mjslines 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.wasmand 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 withplan=offthe plan draws nothing).
- Size:
- Pictures:
flock /tmp/trailview-gpu.lock node trailview/shoot.mjs --gpu --views trailview/road-views-top.json --width 1920 --height 960forv06-road-path-broken-top,v12-good-town-junctions-top,v17-sharp-corners-top,i07-hairpin-topandb45-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 fromroad-views.jsonat 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.shbuilds 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=planloads no plan WASM and starts no plan worker. - With
ground=plan, the HUD shows the plan line; withplan=faces, the five places show their faces from above and at eye height, and the shots withoutplan=facesequal 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.
- 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 holdstile count: u32, then per tilecolumn: u32,row: u32,length: u32, the bytes and zero padding to 4, infeature_tilesorder; absent tiles are left out.decodealso refuses a tile thatfeature_tilesdoes not name, a repeated tile, an order other than canonical and padding that is not zero. The bridge hasCellRequest.add_tile(column, row, bytes)(noset_tile) andfeature_tiles(x, y). A cell isemptyonly when none of its tiles exists. -
Entry:
build_cell(bytes, rules, now) -> Result<CellBuild, String>: stageinput(decode,CellInput::new), thengraph, then (GP3)faces. -
Digest: FNV-1a 64 over the canonical bytes and the
Debugtext of the whole graph. It costs about as much as the graph build, soCellPlan.digest()is lazy; the worker computes it only for a build with the debug draw, andPlanStats.digestsholds 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 fromGraphStats::counters(); noserdederive. -
Files: the GPU part of the debug draw is
plan/draw.ts;plan/debug.tsis 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); stagesinput,graph,faces.Flat.faces: FaceWordsholds the face arrays:vertices,faces(13 words: id, owner kind, owner id, surface, level, rule, material, crossing, rank, inside,reach_mbits, first ring, ring count; GP3'sOwnerhas noBend),rings(2),ring_vertices,edges(6),corners(12 words: owner kind, id, centre x, y,radius_mas two words,t_a,t_b, first point, count),corner_points. The vocabulary'ssurfacescarryfill(#rrggbbaa, null for terrain) andjunction_surfacesthe 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 withearcut;unfilledalso 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
timohueser commentedon Nov 3, 2026
Deviation from GP1 (PR #3117), for this sub-issue:
obc_ground_plan::terrain::pages_from_terrariumreturnsResult<_, String>on a wrong page size instead of a panic. The WASM bridge must pass the error to the worker.timohueser commentedon Nov 3, 2026
Deviation from GP1 (PR #3117), for this sub-issue:
Terrain::new(key, pages)takes the cell key and keeps only the pages thatTerrain::wanted(key)lists, so heights depend on the cell alone.Terrain::heightis defined only inside the cell grown by its margin and answersNonepast level 13; handleNone, do not query outside that square.timohueser commentedon Nov 3, 2026
Implementation plan
Two phases. Phase A uses the stages that
ground-planhas 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.encodesorts the tiles infeature_tilesorder and the pages by(level, x, y).decoderefuses: a wrong magic, a truncation, trailing bytes, a tile thatfeature_tilesdoes not name, a repeated tile or page, a page thatTerrain::wanteddoes not name, a page with another count of codes.cell.rs:build(bytes, rules, now) -> Result<CellBuild, String>: stageinput(decode,CellInput::new), stagegraph(graph::build); GP3 adds stagefaces. One time per stage fromnow(). 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 theDebugtext of the wholeWayGraph(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 fromGraphStats::counters(), so noserdederive is needed (the crossings map has tuple keys).debug.rs: the palette (families, links, synthetic decks, crossings); the debug tool andvocabulary()read it.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.mjsandcheck-bytes.sh(check 7), the size guard moduleground-plan, CI and suites.Viewer (
plan/):inputs.ts(tiles and terrain bodies of a cell),plan-worker.ts(gunzip, WebP decode withtilePages,build, debug mesh,timemessage),plan.ts(Plan,wantedCells, records, dispatch, restarts),debug.tsanddebug.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=planis 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=planthe viewer requests no plan WASM and starts no plan worker.timohueser commentedon Nov 4, 2026
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 inFlat, 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.timohueser commentedon Nov 5, 2026
Phase B is merged into
ground-planwith 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