Repository navigation
Description
Rewritten to the one road model (#3096); the previous body is in this issue's edit history.
Status: approved
Part of #3096. One pull request into ground-plan; a second one only for path B.
Depends on: #3103 (GP9, and through it #3100 GP5, #3101 GP7, #3102 GP8). The look half of the hand-over waits for #3104 (GP11's mesh look).
TL;DR
Goal: Every reader of the ground's height and mask stands on the ground that draws, near and far: plants, rocks, trees, dressing, houses, lamps, light pools, structures, the route, the water ribbons and the eye. Plants keep off every water body, streams included. Over the last 40 m of R_eff the pieces fade into the far look with no jump of height or look.
Problem: After GP9, the pieces draw height_at at GP7's vertices, and the pages hold height_at at their texel centres (GP8). The readers read the pages (drawn_height, plain_height, stand_height, mask_at). The two samplings of one function differ by the mesh's chords, creases, steps and kerbs, and inside the kept water and structure footprints the pages hold the kept stamps while the mesh draws plain ground (GP7 section 2). The previous body closes the gap with a plan layer: a raster of the mesh per level-18 node in the crate, a 32 MiB GPU pool, a 24 MiB packed store, a keep-off distance transform. In the one model the pages already hold the same function and the model's mask, so the plan layer may be unnecessary. No run has measured the difference, at the readers or at the hand-over.
Decision:
- Measure first. The difference between the drawn mesh and the height that the readers read from the pages, at the readers' points, in the fade band at
R_eff, near steps and kerbs, inside the kept footprints, and on open road; once with level 18 and once with level 17 as the finest level. - Path A (the difference is inside the tolerance that the owner sets): no plan layer. The readers read the pages as today. GP10 adds the step rule (a read near a named step uses only the corners on its own side), the pieces' dither over the last
FADE_M, and plants off water (the kept water stamps' gates until GP14, then the water labels of the records). - Path B (outside the tolerance): the plan layer of the previous body, below, with its faces from GP3's plans in place of GP6's window.
- The hand-over: the same measurement in the fade band gives the heights; the hand-over views give the look (GP11's mesh look against B).
Rejected:
- The plan layer before a measurement: 32 MiB of GPU memory, 24 MiB of CPU memory, a crate raster and a distance transform per node, to close a gap that may be inside a tolerance.
- The readers on
height_atper object: a record walk per plant on the GPU; not measured, and the pages already hold it. - Corner radii in the far look (the previous section 13): the far look reads GP3's corners from the records (GP8).
- A gate on the crate's step rule alone: the viewer reads texel segments, not the crate's exact step edges, so only a run with the viewer's rule proves the GPU rule.
- The previous body's rejected items stand for path B.
Systems: trailview
Contracts: none on path A. Path B: tread_bare_m in roads.json.
Size: M on path A (a measurement tool, the step rule, the fade, the stream gates; about 400 to 700 changed lines); L on path B.
Facts
drawn_heightandplain_heightreturn the drawn terrain triangle (mesh_height) of the pages, at the node's level: on a level-18 node a triangle of 1.63 m between grid vertices, each the bilinear of four texels (terrain/drawn-mesh.wgsl:99-107,terrain/drawn-height.wgsl:157-200).stand_heighttakes the morphed bilinear pastMESH_HEIGHT_M= 400 m.- On the new path the pages hold
height_atat every texel centre, bounded by today's water and structure stamps (GP8 section 1). GPU = Rust within 2 mm (GP6). - GP7's mesh: paved faces at most 4 m edges near and 8 m far; slope and terrain faces on the level-18 grid; vertical faces at every named step; the mesh deviates from the function by p99 ≤ 1 cm and max ≤ 3 cm on paved labels near (GP7 M8). Inside the kept footprints (river banks, deck troughs, bore covers) the mesh draws
height_at, the pages the kept stamps (GP7 section 2). The floors lie at least 5 cm under the mesh, and no reader reads the floored terrain. - On usual screens and every phone the first quality step removes level 18 (epic, Facts), so level 17 (0.81 m texels, 3.25 m cells) is the finest page there.
- GP8's feature mask holds the core distance, the walk byte, across, the surface code (low 4 bits) and the flags (WALL from the no-room rule, TAKEN, FORDED; high 4 bits). GP8 reserves two bits for GP10's step rule (
STEP_E,STEP_S, GP8 section 1). Today's stamp marks no stream TAKEN (terrain/bins.ts:961). - GP9 stops the far look at
surface.plan_rangewith a hard edge; GP10 owns the fade. - A plan holds the faces of its own cell only; GP7 reads the neighbour cells' plans for its margin (GP3, TrailView ground plan GP3: faces of ways and junctions: carriageways, tight bends, junction areas, mouths, rail beds #3112; GP7 section 2).
Design
1. The measurement (step 1)
- Mesh height: the crate gives the height of GP7's drawn mesh at a point: the triangle under it, in the range that GP9 draws there (
nearover level-18 nodes,farover level-17 nodes), fromCellMesh. - Read height: what the reader reads on the new path:
drawn_height,plain_heightandstand_height, read back from the GPU by a probe (model-probe.mjs, one GPU user at a time) at the same points, with the pages of the same view. - Points, over the fixture views of Pictures and every 200 m along the walk and valley-drive flights, within
R_eff:- a 0.41 m grid over the owned region, classed by label (paved, slope, terrain), by the distance to the nearest step edge of GP7's mesh (0–0.41 m, 0.41–1.63 m, farther), and inside a kept footprint (river banks, deck troughs, bore covers, shore ramps: GP7 section 2) as a class of its own;
- the census's samples (
scripts/road-census.ts): the points where objects and plants stand today; - the fade band (
R_eff− 40 m toR_eff), with the same classes; - kerbs (once GP4 has them) and walls of each named rule.
- Two runs: finest level 18 and finest level 17 (
finest=17). - With and without the step rule (section 3): the first table computes the rule in the crate from GP7's step edges, so the choice of path does not wait for the rule's GPU encoding. After the GPU encoding lands, the table runs again with the viewer's rule (the probe reads with the stamp's step bits), and the gate is on that run.
- Output: per class, p50, p95, p99 and max of |mesh − read|, and the worst ten points with pictures. The viewer-side twin: GP9's piece fragment draws the
surfaceview in magenta where |drawn_height(s) − h| passes the tolerance on interior triangles wherepiece_shareis 1, andflight.mjs --surface Ncounts magenta pixels.
2. The tolerance (proposed; the owner sets it before the PR merges)
- Farther than one level-18 cell (1.63 m) from a step edge: p99 ≤ 2 cm and max ≤ 5 cm.
- Within 1.63 m of a step edge, with the step rule: max ≤ 5 cm on the point's own side.
- Inside a kept footprint: reported, not gated, until GP12 and GP14 make the footprints records; the owner sees the worst points.
- Reason: 5 cm is the floors' margin under the mesh, and GP7's own deviation from the function is up to 3 cm on paved faces.
3. Path A: the readers on the pages
- One function under the three reads (
ground_heightof path B's section B.9), with no plan-layer branch:terrain_height(s, u, how)as today. - The step rule: a read whose quad a named step crosses uses only the corners on the point's own side, renormalised (path B's rule of section B.9, on the pages). GP10 designs the encoding before coding: the stamp marks each texel segment (east, south) that a named step crosses, in GP8's two reserved bits (
STEP_E,STEP_S). The design goes into this issue first, with the cost per stamp job. - The fade:
piece_fade(s) = 1 − smoothstep(R − FADE_M, R, length(vec3f(s, surface.above)))with R =surface.plan_range; GP9'spieces cutdiscards whereplan_dither(pixel) ≥ piece_fade(s); the far look paints exactly the discarded pixels (paint_share= 1 −piece_fadewith the same dither). Path B's section B.8, without the plan layer. - The readers in the fade band read the pages, as everywhere: no mix.
- Plants off water, until GP14: the kept water stamps set TAKEN also where a texel centre lies within r outside the water's edge, r the half diagonal of the texel. Streams get TAKEN on the new path:
takenwhere a texel centre lies within h + r of a stream segment (round joins and ends), at levels 16 to 18; tunnel parts stay out. After GP14 the water labels of the records decide. points.wgsl: noband_facelift on the new path (no band).- The eye: the probe reads
drawn_heightas today.
4. Path B: the plan layer
The previous body's sections 1 to 11 and 14 to 17, below as B.1 to B.17, with three changes: (1) the faces come from the cell's plan and its neighbours' plans, not from GP6's window, with a check that the plans read cover the cell plus 13.1 m; (2) the far look of the previous section 12 is GP8's B, and the previous section 13 (corner radii) goes; (3) the frame gates follow GP8's clock rule. Path B goes into a second PR under this issue.
5. The hand-over at R_eff
- Heights: the measurement of section 1 in the fade band, at finest 18 and 17. Gate: the tolerance of section 2.
- Look: the hand-over views (for v11, v12, junction0, t-tertiary, x-tertiary, j-tt-a, b45-bridge-junction and i07-hairpin, five views at the LOD distances 540, 570, 590, 610 and 640 m), shot with GP11's mesh look. The owner judges the junction shapes, the lines, the shoulders and sidewalks (GP8 question 6), the walls and the slopes between 540 and 640 m. A difference becomes a finding for GP8 (B's rules) or GP11 (the mesh's rules), never a third rule at the hand-over.
- The walk flight at eye height: no pop at the horizon.
6. Mask reads
kept_offreads GP8's feature mask as today: the core distance less the walk, TAKEN and the way bit. Near the eye the mask holds the records' core (carriageway, shoulder, sidewalk once GP4 has them, verge), so plants keep off what the mesh draws.- The census counts plants in water and objects on ways (Verification).
Invariants and how each is proven
| Invariant | How it holds | Proof |
|---|---|---|
| A reader stands on the drawn ground within the tolerance | path A: the pages hold the same function; path B: the plan layer samples the mesh | section 1's table with the viewer's rule; --surface count 0 |
| No read takes the other side of a step | the step rule | section 1 with the viewer's rule; worst points near walls and kerbs |
| No height jump at the hand-over | the same function on both sides of the fade | section 1 in the fade band; the walk flight |
| Plants keep off water | TAKEN within h + r (streams) and within r (other water) | the census: plants in water 0 |
Plan
- The measurement tool: the crate's mesh height at points (
CellMesh), the probe of the three reads, the classes (kept footprints included), the table (section 1). Run it at GP9's head. Post the table on this issue and get the owner's tolerance. - Path A or path B by the table.
- Path A: the step rule's design on this issue, then its stamp bits and read; the table again with the viewer's rule; the fade; the stream and water gates;
points.wgsl. - The hand-over views with GP11's mesh look.
- Tests and checks;
cargo fmt --all.
Files (path A)
host/obc-ground-plan/examples/debug/or a test helper: change: mesh height at points.builder/web/tests/browser/trailview/model-probe.mjs: change: the three reads at points.terrain/stamp.wgsl,terrain/bins.ts: change: the step bits, the stream records and the water gates on the new path.terrain/drawn-mesh.wgsl,terrain/features.wgsl,terrain/plan-layer.wgsl(onlypiece_fade,piece_share,plan_dither): change or create.- GP9's
plan/piece.wgsl,plan/pieces.ts: change: the fade, thesurfaceview. instances/points.wgsl: change: noband_faceon the new path.tests/browser/trailview/handover-views.json: create.flight.mjs:--surface N.census.mjs:--plan.
Verification
- Checks:
obc test -p obc-ground-plan(the mesh height at points against hand cases), clippy, fmt; inbuilder/web:npx vitest run src/lib/trailview,npm run check,npm run check:wgsl; the old path pixel-equal toground-plan's head before this PR. - Measurements:
- Section 1's table at finest 18 and 17, with and without the step rule, and again with the viewer's rule. Gate: the owner's tolerance (section 2) on the viewer's run for path A; else path B.
flight.mjs --gpu --surface 10on both flights: 0 magenta pixels.- The census (
node trailview/census.mjs --gpu --plan): plants in water 0 over the known samples; objects on ways reported against GP0's count on develop. - Frame:
flight.mjs --gpu --toggle waysby GP8's clock rule (interleaved runs against GP9's head, shares scaled to one clock): the road share stays within GP9's gate, and the reader passes (plants, forest, rows, dressing, instances, houses, structures, water) do not grow against GP9's head by more than the spread. - The stamp per job against GP9's head (the step bits and the stream records): reported.
- Pictures (with and without the switch, 1920 × 960,
shoot.mjs --gpu, one slider page; the implementer looks at each):- v02-stream-path-shrubs, v10-signpost-bench, v15-stuff-on-road, residential-night, residential-curve-eye, residential-15m, main-road-15m, main-road-eye, i07-hairpin-eye, i07-hairpin-top, stream-main-road-eye, stream-culvert-main-road. The owner looks for: no plant, rock or tree in a stream or on a carriageway; benches, signposts, lamps and light pools on the drawn ground, not floating or sunk; house bases on the ground beside the road; the route on the mesh; no plant floating at a wall's foot; the eye on the road;
- the ten worst points of section 1, at 2×, and the worst points inside kept footprints;
- the hand-over rows (section 5).
Done when
- The measurement table is on this issue, and the owner set the tolerance.
- Path A: every reader reads the pages through one function, with the step rule; the viewer's table holds the tolerance; the
--surfacecount is 0; the census counts 0 plants in water; the hand-over shows no jump; the frame and reader gates hold. Path B: its done-when below. - The old path is pixel-equal.
- The PR shows the pictures and the hand-over rows, and carries
Mode: change #3114andRequirements: none.
Out of scope
- The mesh's looks, the paint off on the mesh, normals and facets: GP11. The far look and its rules: GP8.
- Water records, beds, banks and surfaces near the eye: GP14. Fords and culverts as faces: GP15.
- What a reader on a bridge deck reads: GP12. Lamps, posts, guardrails and point kinds: GP16, GP17.
Questions for the owner
- The tolerance (section 2). Recommendation: away from steps p99 ≤ 2 cm and max ≤ 5 cm; near steps with the step rule max ≤ 5 cm on the point's side; inside kept footprints reported until GP12 and GP14.
- Path B's memory (32 MiB GPU, 24 MiB CPU) if the table asks for it: as before.
What changed from the previous body, and why
- Measure first. The pages hold the same function as the mesh (GP8), so the plan layer may be unnecessary. The previous design stays as path B, with its faces from GP3's plans.
- The hand-over is measured for heights and judged for the look with GP11; the corner radii question goes, because the far look reads GP3's corners.
- Kept footprints are a class of the measurement: there the pages and the mesh differ until GP12 and GP14.
- Plants off water: the stream and water gates now act on GP8's kept water stamps; GP14's water labels replace them.
- Frame gate: the owner's whole-road rule (GP9) by GP8's clock rule, plus the reader passes against GP9's head.
- Kept: the readers' list, the step rule, the fade with its dither, the census and the surface count, the hand-over views, the old path pixel-equal.
Path B in full (built only if the table asks for it)
Path B: the plan layer (the previous body's design, with its faces from GP3's plans)
Inside path B, "section N" means B.N.
Rejected for path B:
- Rasterize the pieces into the layer on the GPU: no CPU memory, but the mask needs a distance transform on the GPU and data that the mesh does not hold (buildings, water, the tread of trodden ways). The native checks could not test it, and the epic puts the layer in the crate.
- Put the layer into the page arrays and the mask pool: no new binding, but it couples the plan to the page slots. The epic gives the layer textures of its own.
- Today's four mask channels (edge, sidewalk byte, across, surface code) per texel: 6 bytes per texel with the height, and a projection onto the nearest way's curve at each texel. The placement reads need only the keep-off distance and the flags.
- A storage buffer for the node map: group 3 counts in every reader pipeline, and the include tree of
forest.wgslalready declares 9 storage buffers over its entry points, against a limit of 8 per stage. - Raw layers on the CPU: 256 KiB per node, 150 to 450 live nodes: 38 to 112 MiB.
- Build a layer on request from the kept cell: the worker would keep the meshes of every held cell.
- Heights from the height rules instead of the mesh: a blend and a slope evaluation per texel, and not what draws.
- The nearest texel everywhere: terraces of 0.2 m on a slope of 1. A hash per point for heights in the fade: an object jumps.
- Corner radii in the far look now: at eye height a corner at 600 m is less than a pixel (Design 13). They come only if the owner asks for them from the handover rows.
- Step and crease flags on the four corners of a quad: a quad between two crossed quads gets four flagged corners with no edge in it, and the checks then skip it.
B.1 The plan layer (crate)
PlanLayer (the epic's type) has these fields:
node: NodeKey: the level-18 node (x, y).offset: f32,step: f32: metres; height =offset + code × step.texels: Vec<u32>: 65,536 texels, row-major. Indexj × 256 + i, i east, j south, the same order as a page.
The cell build makes one layer for each level-18 node that holds at least one owned level-17 cell. A level-18 node lies in exactly one cell, so no two cells write one layer. A node with no owned cell has no layer. The layer is the last product of the cell build, after the mesh (GP7). The crate frame holds the texel centre of level-18 texel t at t × 256 + 128 in 1/16 world units: exact integers.
B.2 The texel
| Bits | Name | Meaning |
|---|---|---|
| 0-15 | height code | round((h − offset) / step), 0 to 65,534; 0xFFFF = UNOWNED: the texel lies outside the owned region, or its height is unknown |
| 16-23 | keep code | round(255 × distance_code(d)) of stamp.wgsl, with d the signed distance to the keep-off region (section 4) |
| 24-31 | flags | FORDED 0x04, TAKEN 0x08 (the page mask's flag values), WAY 0x10, STEP_E 0x20, STEP_S 0x40, CREASE 0x80; 0x01 and 0x02 stay 0, because flags & 15 is the page mask's flags |
STEP_E and STEP_S are per segment: a step edge (a vertical face at level 0 higher than 1 cm: kerb, wall, headwall, portal, unrelated owners) crosses the segment from this texel's centre to the next centre east (south). CREASE is per quad: it marks the quad whose lowest i and j corner is this texel. So no flag reaches a quad that no edge crosses.
offset is the least known height of the layer. step = max((highest − least) / 65534, 0.0001) m. A node with 300 m of relief gets steps of 4.6 mm. The crate holds MASK_RANGE_M = 12.75 and MASK_KNEE_M = 0.5, as MASK_RANGE and MASK_KNEE of stamp.wgsl. All arithmetic is f64 through libm, so native and WASM give the same bytes.
B.3 Heights
- The source is the drawn mesh of the cell at level 0: the interior triangles of the range that GP9 draws over a level-18 node (
near;farfor a cell built withnear: false) and the strip triangles at morph 0. Where a cell drawsfarover a near layer, the surface count (Measurements) covers the difference. The strip's outer vertices take the heights that GP7 computes for the floors at morph 0. Deck triangles (level > 0) and vertical faces take no part. - For each triangle, the texel centres in its box that lie inside it by the half-open rule of the integer edge functions (top-left rule) take the barycentric height of its three vertices. So each centre takes exactly one triangle.
- A centre in an owned level-17 cell takes a height. Every other centre is UNOWNED. An owned centre that no triangle holds is a hole. It stays UNOWNED and counts in
holes(a hard check, target 0). - So the layer is the drawn mesh sampled at 0.41 m. On a plane it is exact. Where mesh edges cross a quad (the square between four texel centres), bilinear reading departs from the mesh by at most 0.1025 × g m (a quarter of a texel times g), with g the sum of the gradient jumps of those edges. With the quantization and a float margin, the bound of a quad is
0.1025 × g + 0.01m.
B.4 The keep-off distance
- Keep-off region K: the union of the faces, at every level, whose surface is carriageway, shoulder, sidewalk, corner fill, crossing, rail bed, platform, seat or deck. Two exceptions: a trodden way, and a junction whose arms are all trodden. They give, in place of their faces, the tread band of each trodden way: the band of half-width
tread_bare_m(section 15) about its centre curve, cut to the way's own faces. A way is trodden by the rule ofstamp-core.wgsl:695(Facts). - So
d(the distance to K) reproduceskept_off: on a road, the distance past its sidewalk; on a trail,|across| − 0.45. - K comes from one
i_overlayunion of integer polygons. A tread band is an offset of the centre polyline, cropped to the plans that GP10 reads (the cell's and its neighbours'), never to the cell line. - Faces past the cell border: K takes every face within 13.1 m (the distance margin below) of the cell, from the cell's plan and its neighbours' plans (a plan holds its own cell's faces, GP3; GP7 reads the same plans). A check asserts that the plans read cover the cell plus 13.1 m.
- Reach, against GP1's
MARGIN_M= 192 m: the heights sample the mesh inside their own node and add no reach. A texel's d reads faces within 13.1 m of the cell, and a face depends on data within F = 100 m (GP2's room decision reads 70 m, GP3's corner 30 m from it): the keep-off chain is 13.1 + 100 = 113.1 m ≤ 191 m. A water band reads its line within 13.1 +HALF_MAX_M(15 m) + 2 m (a curve off its chord) = 30.1 m ≤ 191 m. GP1's reach table lists both chains. GP10 adds no margin. - Distance: a vector distance transform per node over its 256 × 256 texels plus a margin of 32 texels (13.1 m). Each texel holds one boundary segment of K. Seeds: each texel whose square a segment passes through (the grid walk) holds the nearest of those segments. Two raster passes (forward, then backward, 4 neighbours each, Danielsson's order) give a texel a neighbour's segment where that segment is nearer by the exact point-to-segment distance. Metres come from the Mercator scale at the texel row. The sign is negative where the centre lies in K (a scanline fill of K with the same half-open rule). Clamp to ±12.75 m and code it. WAY is set where d < 12.75 m.
- Cost: fixed per node, about 8 × 320² = 0.8 million distance evaluations, so about 13 million per cell of 16 nodes, independent of the segment lengths. Reported: the evaluations per cell.
B.5 Flags
- TAKEN: the texel's square overlaps a water polygon or a building polygon. A point reads the texel whose square holds it (
mask_attakes the nearest texel), so every point in water or in a building reads TAKEN. The square overlap is exact: the centres inside by scanline, plus every square that a polygon edge passes through (an integer grid walk). - Water polygons:
water_extent(features) -> Vec<Polygon>. Each stream, river and canal line part that is not a tunnel (the tiles keep culverts and buried streams as tunnel parts,specs/trailview-features.md:204-212) gives its band: an offset with round joins at its half-widthh, the samehthat the ribbon draws and that the census samples. Each lake, pond, river area and sea polygon gives itself. Lines are cropped to the cell plus the margin of section B.4 (13.1 m plus the band's reach), not to the cell. GP14 builds its water faces from this function, so the mask and the water faces always agree. - Buildings: the building polygons of the decoded tiles (GP1), as
bins.ts:1000takes them. - FORDED: a texel in K whose square overlaps the water polygon of a stream that crosses the texel's way with crossing type ford (GP2's
Crossing). - STEP_E, STEP_S: the grid walk of each step edge over the texel segments (section 2). Readers use them (section 9).
- CREASE: the quad's sum g of gradient jumps (section 3) passes 0.3. Only there can the bilinear error pass 3.1 cm (0.1025 × 0.3). Only the surface view reads it (Verification).
B.6 Packing, store and GPU pool (viewer)
- Posting: the plan worker (GP5) receives the layers with the cell's output and packs each one: the 16-bit height codes become row-wise differences to the left texel (wrapping; the first texel of a row against the first texel of the row above), the 4 byte planes follow one another, then
CompressionStream('deflate-raw'). It posts{node, offset, step, packed}and keeps nothing. - Store:
PlanLayerson the main thread keeps the packed layers by node, with their cell. A cell that GP9 drops takes its layers with it. A rebuilt cell replaces its layers. The cap isPLAN_STORE_BYTES= 24 MiB: over it, the layer farthest from the eye leaves. If a node within the resident range then has no layer,PlanLayersasks the worker once to build its cell again, and counts it inrebuilds. - Resident range: a node is wanted when its square lies within
range + RESIDENT_MARGIN_M(52 m, half a node) of the eye in the LOD metric. The nearest wanted nodes, up toPLAN_PAGES= 128, hold a page of the textureplan(r32uint, 256 × 256 × 128, 32 MiB, poolplan). A node that is no longer wanted gives its page to the nearest wanted node without one. The wanted nodes past the first 128 get no page and count inshortage. Up toPLAN_UPLOADS= 4 pages per frame (1 MiB) unpack (DecompressionStream, then the inverse filter) and go up withwriteTexture, nearest first. - Why 128: at 47° N, 129 level-18 nodes touch a disc of 600 m, and only owned nodes need a page. If the walk or drive flight counts a shortage nearer than
R_eff − 40 m,PLAN_PAGESrises to 160 (40 MiB). A shortage in the fade band costs nothing visible. - Device loss:
lost()frees the GPU state; the store refills the pool. - Old path: without the switch,
planis one 1 × 1 × 1 texture andplan_rangeis 0. The store stays empty. - Stats:
{resident, wanted, shortage, storeBytes, rebuilds, uploads}, next to GP9's piece stats in the HUD and the flight output. - New content:
PlanLayers.newContentis true in a frame after an upload or a change of the map words.Terrain.newContenttakes it, as GP9's step 9, so the houses (structures/houses.ts:327) and every other reader that refits onchanged(engine.ts:575) refit on the new ground also when the eye stands still.
B.7 Group 3
gpu/layouts.ts gives features two entries, visible to all stages: binding 3 plan_texels: texture_2d_array<u32> and binding 4 plan: Plan (uniform). No storage buffer is added. The include tree of forest.wgsl then declares 14 sampled textures; the limit is 16.
struct Plan {
origin: vec2i, // the level-18 node at slot (0, 0) of the map
map: array<vec4u, 256>, // 32 × 32 slots, one u32 each: bits 0-15 page + 1 (0: none); bit 16 DRAWS
scales: array<vec4f, PLAN_PAGES / 2>, // per page (offset, step), two pages per entry
}
The map is a window of 32 × 32 level-18 nodes about the eye's node: at least 830 m in each direction up to 70° N, more than the range and its margin. PlanLayers.write() writes the uniform when it changes, before the frame's passes, so every compute and draw of a frame reads one state.
The range is GP9's surface.plan_range (R_eff; 0 on the old path and below level 17), so the plan and GP9 read one number.
DRAWS is set exactly for GP9's candidates with d < R_eff (GP9 section 6: the leaves of rule.split, without the frustum cull, so readers out of view read the same ground); a level-17 candidate sets it on its four level-18 children. GP10 adds one condition to GP9's drawable(node): the plan page of each owned level-18 node in its square is resident. A refusal cuts R_eff, so by GP9's invariant I1 no node within R_eff draws a piece or a floor without its layer, and the floors (within floor_range = R_eff − 40 m) never hold a node that DRAWS leaves out.
B.8 Share and fade
New file terrain/plan-layer.wgsl, included by features.wgsl:
piece_fade(s) = 1 − smoothstep(R − FADE_M, R, length(vec3f(s, surface.above))), with R =surface.plan_rangeand GP9'sFADE_M= 40 m. It is 0 when R is 0.piece_share(s) = piece_fade(s)where the DRAWS bit of the level-18 node of s is set, else 0.- GP9's
pieces cutpipeline discards a pixel wheredither(pixel) >= piece_fade(s), in place of its cut at the range. Only parts that reach pastfloor_rangedraw there; thepiecespipeline keeps no discard and its early depth test. - GP9's floor stops at
floor_range, wherepiece_fadefalls below 1. In the fade band the terrain takes its far-stamped heights and its paint, as the epic says. On the new path no corridor holds a way, somasks.heldstays 0 andpaint_shareis 1: the terrain paints every way that it shows. plan_dither(t: vec2i) -> f32: an integer hash of a level-18 texel in [0, 1), fixed in the world.
B.9 Height reads
plan_texel(t): the node ist >> 8, the slot isnode − plan.origin. Outside the window or with no page it gives UNOWNED; elsetextureLoad(plan_texels, t & 255, page − 1, 0).x.plan_height(s):t = texel_of(s, 18). The four texels of the quad come from onetextureGatherwithquad_samplerwhere they lie in one page, else from fourplan_texel. If any code is 0xFFFF it gives NONE. The four texels hold the STEP bits of all four quad segments. With none set, it gives the bilinear height. Else the corners on the side of the nearest corner N are N and each corner that N reaches over uncrossed segments; it gives the bilinear of those corners with their weights renormalised. Next to the edge the error is at most the side's gradient times 0.29 m (one corner); a dropped corner's weight is at most 0.086 one texel from the edge, and the fixture check gates those points at the bound of section 3.drawn-mesh.wgslgetsconst DRAWN = 0u, PLAIN = 1u, STAND = 2u, and:terrain_height(s, u, how):mesh_height(s, true)for DRAWN,mesh_height(s, false)for PLAIN; for STAND,mesh_height(s, false)withinMESH_HEIGHT_M, elsemorphed_ground(u, lod(s)).x. This is today's code, unchanged.ground_height(s, u, how):share = piece_share(s). If share > 0,p = plan_height(s). If p is known and share = 1, return p. Elseh = terrain_height(s, u, how). If p is known, returnmix(h, p, share)(p where h is unknown). Else return h.drawn_height(s),plain_height(s)andstand_height(s, u)returnground_heightwith DRAWN, PLAIN and STAND (u =surface.anchor + round(units_of(s))where the caller gives none).stand_groundtakes its height fromground_height(s, u, STAND)and keeps its slope fromSLOPE_LEVEL.
- So
ground_heightlies under the three, and withrange= 0 it returns today's value. Where the plan holds the ground it reads one gather in place of 9 to 49 vertices. - The terrain's own code tests the terrain, so it calls
terrain_height: thesurfaceview of the terrain fragment (terrain.wgsl:141),audit.wgsl(the stamp's checks), and GP9's floor and crack checks.
B.10 Mask reads
- Today's
mask_atbody becomespage_mask_at(s, top, roads), unchanged. The terrain's paint (ground/roads.wgsl:212,226) calls it. - New
mask_at(s, top, roads): ifpiece_share(s) > plan_dither(t)for the nearest level-18 texel t, andplan_mask(s, roads)covers s, return the plan's mask. Else returnpage_mask_at(s, top, roads). In the fade band each texel switches at its own distance. plan_mask(s, roads): the nearest texel must be owned, else it does not cover s. Withroads, where the nearest texel has neither WAY nor TAKEN, it covers s with an empty mask (level0), asmask_atstops today. Elseedgeis the bilinear mix of the four texels' keep codes, decoded withmask_metres(an unowned texel takes the nearest texel's code);awayandaxiscome from its rise, as inmask_at;kind = (WAY ? 1 : 0, flags & 15);level= 18;walk,half,across,sleepersandface= 0;troddenandmarked= false.- So
kept_offstays unchanged:edge − walkis d, and TAKEN and WAY act as today. The ribbons hide exactly on K and stay open at a ford. Until GP14 they run up to the face edge of every way, with no give-way margin. - The terrain's mask view (
terrain.wgsl:90) and the pieces' mask view showmask_at, which is what the readers read; TAKEN shows in blue.
B.11 The readers
| Reader | Reads | After GP10 |
|---|---|---|
water ribbons and lakes (water.wgsl) |
drawn_height, plain_height, mask_at |
plan where pieces draw |
| structures, anchors, houses, light pools, route | plain_height, stand_height |
plan |
eye clamp, probe, census (probe.wgsl) |
drawn_height, kept_off |
plan |
| plants, rows, forest, dressing, point instances | stand_height, stand_ground, kept_off |
plan |
points.wgsl beside a way |
drawn_height, band_face |
band_face only where piece_share(s) = 0 |
| culling boxes, species band | units_height of a coarse level |
pages (bounds, not placement) |
normals (drawn_normal) |
pages | pages |
| terrain paint and look | page_mask_at |
pages (GP11 turns the paint off on the mesh) |
terrain surface view, audit.wgsl |
terrain_height |
terrain |
B.14 Interfaces
- Takes from GP1: the decoded features of the tiles within
MARGIN_M(water lines withh, water areas, buildings), the frame and its Mercator scale, the cross-section reader, the debug tool. - Takes from GP2:
Way(kind, surface, curve) andCrossing(type ford). - Takes from GP3 and GP4:
Face(owner, surface, level, polygon) from the cell's plan and its neighbours' plans, over the cell plus 13.1 m. GP1's reach table asserts GP10's two chains (section 4). - Takes from GP7: the mesh (interior and strip triangles, the strip's heights at morph 0, the vertical faces), the owned level-17 cells, the cell's output, into which
layers: Vec<PlanLayer>goes. - Takes from GP5: the bridge and the worker protocol; the layers travel with the cell's output.
- Takes from GP8: the far look (B) and its kept water stamps (path A's plants off water).
- Takes from GP9: the node test, the piece list, the range, the floor, the piece fragment.
- Gives GP14:
water_extent, the one definition of a water body's polygon. - Gives GP12: the layer holds level 0 only. GP12 decides what a reader on a deck reads.
- Gives GP16 and GP17: every object that a reader stands on the ground stands on the drawn mesh.
B.15 Rule-table field
tread_bare_m in each class's cross-section of data/trailview/roads.json: metres, the half-width about the middle of a trodden way that plants keep off. Default 0.45 for the classes of kind path, 0 for the rest. Source: TREAD_CLEAR_M 0.7 − TREAD_GRACE_M 0.25 of features.wgsl, which the trail look also uses; a vitest ties the two. No feature-step rule reads it; only the ruleset digest changes.
B.16 Edge cases
- Empty cell, or a cell of water alone: no owned region, no layer. Readers read the terrain; GP8's TAKEN keeps plants off the water.
- Cell and node borders: a node lies in one cell. A quad across a node border reads the texels of both pages. The keep-off distance sees the next cell's faces through the neighbours' plans; the continuity check proves it.
- Owned border (the strip's outer edge): the next texel out is UNOWNED, so the quad gives NONE, and the reader reads the terrain, which equals the strip's outer vertices.
- A neighbour page that is not resident: its texels are UNOWNED. The reader falls back to the terrain for that quad.
- Kerbs, walls, headwalls, portals: a crossed quad reads its nearest corner's side (section 9), never the other side's height. Two edges in one quad (kerb and wall, hairpins) cut the side smaller; one corner is the least.
- Creases at a slope's top or foot: bilinear error up to 0.1025 × g, about 7 cm for a fill of 0.7 on flat ground, 22 cm for the steepest cut of 2.14, within 0.2 m of the crease.
- Hairpins: the wall between the legs is a step edge; plants at its foot stand on the lower side.
- Lowered kerb, driveway: no step edge, so bilinear.
- Bridges: decks are in K (trees keep off under a deck, as the page mask does today) but not in the heights. The ground under a deck is the layer. A lamp on a deck reads the ground until GP12.
- Tunnels: the portal is a step edge; above the bore the terrain.
- Fords, culverts: a ford is K and FORDED; a culvert is K and TAKEN.
- Junctions of trails only: their tread bands, so plants grow over the margins, as today.
- A tree just outside the owned region with a clearance past 6.5 m: the page mask decides; it differs from the plan only by what the page's texels cannot resolve.
- Culling boxes: they read pages. The plan differs from the far-stamped pages by at most a wall's height, less than the boxes' margin of the tallest plant.
- Unknown terrain: UNOWNED; the reader reads the terrain, also unknown.
- Level 17 as the finest level: the strip draws at morph 1 and the layer holds it at morph 0. They differ by the chord, a few cm. Finest level below 17:
range= 0, so no reader reads the layer. - Morph band of level 18 (390 to 480 m): the strip's outer vertices slide; same bound.
- Pool or store shortage: the farthest nodes lose their pieces and their reads together, and the far look shows them.
- A cell that arrives late: its pieces wait for their pages; until then the terrain and its readers agree.
B.17 When a rule cannot fit
Every texel gets a defined value. A hole is UNOWNED and counted, and the reader then reads the terrain. A distance past the range clamps. A quad that cannot be bilinear (UNOWNED, missing page) falls back to the terrain. The plan layer never makes a face; it only samples the mesh.
Plan, files, verification and done-when of path B: the previous body's (in this issue's edit history), with these changes: plan step 5 reads the faces and lines of the cell's plan and its neighbours' plans (section B.4) and asserts that they cover the cell plus 13.1 m; plan step 16 is GP8's far look (B), and the previous section 13 goes; the frame measurements follow GP8's clock rule in place of "clock held"; the page-creation gate compares with GP8's stamp jobs; the decision of section 13 leaves the done-when.
Generated by Claude Code
Activity
timohueser commentedon Nov 3, 2026
Note from GP0 (PR #3118): the view
plants-in-wateris not valid on the committed fixture: it needs--groundwith a ground bake of the fixture, which does not exist. Prove "plants off water" with another view or a fixture ground bake.timohueser commentedon Nov 4, 2026
GP8 deviations that affect GP10 (#3102, changed after the owner's rules):
seg ≤ max(h, 0.5 × texel), withsegthe distance to the segment (a capsule) of every STREAM segment, notinside && lateral ≤ …. So round joins and round ends are already in. GP10's change of the stream gate is then only the radius:h + rin place ofmax(h, 0.5 × texel). The facts line that says "a bend's outer wedge stays free" no longer holds; the edge texels still do until GP10 widens the radius.cpast the through road's middle; under the through road's carriageway the deeper carriageway takes the texel). Only a structure's end and a way's end that meets one is flat. The handover rows compare against this shape; the corners between arms stay sharp as before.Generated by Claude Code
timohueser commentedon Nov 4, 2026
Interface change from GP8 (owner approved, see #3102):
smoothstep(floor_range, plan_range, distance). GP9'svertex_mainandpiece_placepass the same snap flag, so terrain and strip vertices agree bit for bit. GP9 addsfloor_rangeandplan_rangetoSurfaceand counts strip vertices with a snap word ≠ 0 (target 0). I6 now reads: "No vertex withinfloor_rangemoves. No strip vertex moves."r(≤ 9 m) past an arm's own footprint, inside the corner's fan; GP6's owned region (I1) must cover this.acrosscode is finer (an asinh scale) on the new path only.Generated by Claude Code
timohueser commentedon Nov 5, 2026
DRAFT for review: a new body of GP10 for the one road model. This comment does not change the issue body. An independent reviewer reads it before the owner does.
Sources: the round's proposal (#3096 (comment), "GP10 measures first, then drops what it can"), its review (#3096 (comment), finding H4), the owner's decisions of 2026-11-05 (#3096 (comment)), the GP6 to GP9 drafts, and the approved body of this issue. The approved design of the plan layer stays as path B, word for word.
TrailView ground plan GP10: readers on the drawn ground: measure first, the hand-over at R_eff, the plan layer only if it is needed
Status: draft (one road model)
Part of #3096. One pull request into ground-plan; a second one only for path B.
Depends on: GP9 (and through it GP5, GP7, GP8). The look half of the hand-over waits for GP11's mesh look.
TL;DR
Goal: Every reader of the ground's height and mask stands on the ground that draws, near and far: plants, rocks, trees, dressing, houses, lamps, light pools, structures, the route, the water ribbons and the eye. Plants keep off every water body, streams included. Over the last 40 m of
R_effthe pieces fade into the far look with no jump of height or look.Problem: After GP9, the pieces draw
height_atat GP7's vertices, and the pages holdheight_atat their texel centres (GP8). The readers read the pages (drawn_height,plain_height,stand_height,mask_at). The two samplings of one function differ by the mesh's chords, creases, steps and kerbs. The approved body closes the gap with a plan layer: a raster of the mesh per level-18 node in the crate, a 32 MiB GPU pool, a 24 MiB packed store, a keep-off distance transform. In the one model the pages already hold the same function and the model's mask, so the plan layer may be unnecessary. No run has measured the difference, at the readers or at the hand-over (review finding H4).Decision:
R_eff, near steps and kerbs, and on open road; once with level 18 and once with level 17 as the finest level.FADE_M, and plants off water (the far stamp's water gates until GP14, then the water labels of the records).Rejected:
height_atper object: a record walk per plant on the GPU; not measured, and the pages already hold it.Systems: trailview
Contracts: none on path A. Path B as approved (
tread_bare_minroads.json).Size: M on path A (a measurement tool, the step rule, the fade, the stream gates; about 400 to 700 changed lines); L on path B (as approved).
Facts
Unchanged (approved Facts), plus:
drawn_heightandplain_heightreturn the drawn terrain triangle (mesh_height) of the pages, at the node's level: on a level-18 node a triangle of 1.63 m between grid vertices, each the bilinear of four texels (terrain/drawn-mesh.wgsl:99-107,terrain/drawn-height.wgsl:157-200).stand_heighttakes the morphed bilinear pastMESH_HEIGHT_M= 400 m.height_atat every texel centre, bounded by today's water and structure stamps (GP8 section 1). GPU = Rust within 2 mm (GP6).terrain/bins.ts:961).surface.plan_rangewith a hard edge; GP10 owns the fade.Design
1. The measurement (step 1)
nearover level-18 nodes,farover level-17 nodes), fromCellMesh.drawn_height,plain_heightandstand_height, read back from the GPU by a probe (model-probe.mjs, one GPU user at a time) at the same points, with the pages of the same view.R_eff:scripts/road-census.ts): the points where objects and plants stand today;R_eff− 40 m toR_eff);finest=17).surfaceview in magenta where |drawn_height(s) − h| passes the tolerance on interior triangles wherepiece_shareis 1 (the approved plan step 15), andflight.mjs --surface Ncounts magenta pixels.2. The tolerance (proposed; the owner sets it before the PR merges)
3. Path A: the readers on the pages
ground_height), with no plan-layer branch:terrain_height(s, u, how)as today.piece_fade(s) = 1 − smoothstep(R − FADE_M, R, length(vec3f(s, surface.above)))with R =surface.plan_range; GP9'spieces cutdiscards whereplan_dither(pixel) ≥ piece_fade(s); the far look paints exactly the discarded pixels (paint_share= 1 −piece_fadewith the same dither). Approved section 8, without the plan layer.takenwhere a texel centre lies within h + r of a stream segment (round joins and ends), at levels 16 to 18; tunnel parts stay out. After GP14 the water labels of the records decide.points.wgsl: noband_facelift on the new path (no band).drawn_heightas today.4. Path B: the plan layer
The approved body's sections 1 to 11 and 14 to 17, word for word, with one change: the far look of section 12 is GP8's B, and section 13 (corner radii) goes. Path B goes into a second PR under this issue.
5. The hand-over at R_eff
6. Mask reads
kept_offreads GP8's feature mask as today: the core distance less the walk, TAKEN and the way bit. Near the eye the mask holds the records' core (carriageway, shoulder, sidewalk once GP4 has them, verge), so plants keep off what the mesh draws.Invariants and how each is proven
--surfacecount 0Plan
CellMesh), the probe of the three reads, the classes, the table (section 1). Run it at GP9's head. Post the table on this issue and get the owner's tolerance.points.wgsl.cargo fmt --all.Files (path A)
host/obc-ground-plan/examples/debug/or a test helper: change: mesh height at points.builder/web/tests/browser/trailview/model-probe.mjs: change: the three reads at points.terrain/stamp.wgsl,terrain/bins.ts: change: the step bits, the stream records and the water gates on the new path.terrain/drawn-mesh.wgsl,terrain/features.wgsl,terrain/plan-layer.wgsl(onlypiece_fade,piece_share,plan_dither): change or create.plan/piece.wgsl,plan/pieces.ts: change: the fade, thesurfaceview.instances/points.wgsl: change: noband_faceon the new path.tests/browser/trailview/handover-views.json: create.flight.mjs:--surface N.census.mjs:--plan.Verification
obc test -p obc-ground-plan(the mesh height at points against hand cases), clippy, fmt; inbuilder/web:npx vitest run src/lib/trailview,npm run check,npm run check:wgsl; the old path pixel-equal toground-plan's head before this PR.flight.mjs --gpu --surface 10on both flights: 0 magenta pixels.node trailview/census.mjs --gpu --plan): plants in water 0 over the known samples; objects on ways reported against GP0's count on develop.flight.mjs --gpu --toggle ways, as GP9: the road share stays no larger than develop's (GP9's gate), and the reader passes (plants, forest, rows, dressing, instances, houses, structures, water) do not grow against GP9's head by more than the run-to-run spread.shoot.mjs --gpu, one slider page; the implementer looks at each):Done when
--surfacecount is 0; the census counts 0 plants in water; the hand-over shows no jump; the frame and reader gates hold. Path B: the approved Done when.Mode: change #3114andRequirements: none.Out of scope
Questions for the owner
What changed from the approved body, and why
Generated by Claude Code
timohueser commentedon Nov 6, 2026
Note from GP8 (PR #3161, merged): the feature mask on the new path has no two free bits for
STEP_E/STEP_S. Details: #3102 comment 6671786112.Generated by Claude Code
timohueser commentedon Nov 7, 2026
From the plan after the 2026-11-07 review of #3096: two changes to this item's hand-over.
R_effnear 600 m: the hand-over views sit at LOD distances of 540 to 640 m. As built, the mesh ends at the level-18 plateau, about 195 m of 3D distance (plan/pieces.ts:222, a 10 m fade,FADE_MARGIN_M), and no mesh draws when the finest level is 17. Until step 3 (TrailView ground plan, step 3: the mesh on level-17 terrain nodes (design first) #3196, the mesh on level-17 nodes) and step 6 (TrailView ground plan, step 6: the mesh range toward 600 m at two levels of detail #3199, the range toward 600 m at two levels of detail) land, the hand-over happens at about 195 m. Shoot the hand-over views at four LOD distances around the actual mesh end, not at fixed distances.The height half (section 1 of this body, the measurement in the fade band) does not change. The guard rule of the plan applies: no new reader of the records on the GPU except through
height_at/model_at.timohueser commentedon Nov 10, 2026
Cut (owner, 2026-11-10): path B, the plan layer (a second copy of heights for the readers, 32 MiB of GPU memory). The readers read the pages; the height half of this issue stays.
Generated by Claude Code