Skip to content

EPIC — TrailView ground plan: one engine for ways and water near the eye #3096

Open
19 of 44 issues completed
Open

Description

@timohueser

Status: approved

Part of #2747. Replaces the open work of #3031 (paused). The analysis of the old system is #3095.

TL;DR

Goal: Within about 600 m of the eye, roads, tracks, paths, railways, bridges, culverts, streams, rivers and lakes sit in the terrain with no tear, fold, gap or step that a rule did not ask for, for any OSM input. Junctions of every kind look natural, and roadside objects stand where they stand in the real world. The look of today's roads, paths and railways stays, and the design runs on a phone.

Problem: #3095. Four parts of the viewer derive "the road" from its centre line: the terrain grid, the stamp, the mask and its paint, and the corridor sweep. They agree only when every change is copied into all four by hand. A sweep cannot describe a 2D region, so junctions, ends and tight bends need special pieces, and each new combination of pieces fails in a new way. A height field cannot hold a kerb, a wall or two levels in one cell.

Decision: Describe the ground near ways and water once, as a ground plan: a 2D map of faces that never overlap and leave no gap. Each face has an owner, a surface and a height rule. Heights come second and the triangle mesh third. One Rust crate builds the plan for each cell on the device, from today's feature tiles, and the bake keeps every decision that needs a wide view. The mesh draws the ground near the eye. The terrain grid holds its vertices under the mesh, and a strip of the mesh copies the terrain grid where the two meet. Every reader of the ground's height reads the plan near the eye. One simple stamp shapes and paints the ways far from the eye. A placement module puts objects where the plan allows them. The work collects on one integration branch and merges into develop only when the whole system works.

Rejected:

  • Keep the sweeps and the special pieces (TrailView: ways and water that sit in the terrain near the eye #3031): the four limits of TrailView roads: why the road system tears, and a planar road map #3095, section 5, stay.
  • Bake the meshes: a corridor has 14,000 to 28,000 triangles per km, while the line data of a way is about 1 kB per km. Baked meshes would multiply the feature tiles many times, and the owner does not accept that growth of storage and transfer.
  • Build the geometry in TypeScript: the bake and the later iOS app could not use the same code.
  • Faces from sampled distance fields and contours: the edges depend on the grid, the contours need many vertices, and nested contours need extra rules. Exact integer polygons are exact and compact. (Slope faces are sampled anyway, see section 6.)
  • A terrain grid that bends to the ways (TrailView roads R23: ways sit in the terrain #3027's fit), breaklines in the grid, a finer grid near ways: the reasons of TrailView: ways and water that sit in the terrain near the eye #3031 hold.
  • Ownership by a pixel discard in the terrain: +1.07 ms on the GTX (TrailView A1: prototype, the cost of a near terrain that leaves the ways' ground to the corridors #3036).
  • Ownership by an index buffer per terrain node: exact, but one index buffer and one indirect draw per near node. The floor keeps one instanced draw.
  • A whole-cell mesh that replaces the terrain: it repeats the terrain's look and LOD work everywhere, not only near ways.
  • A mesh over level-17 nodes with today's overlap (depth bias): two rules for one job.
  • The plan's heights and paint written into the terrain pages: two height functions would meet at every page border between a built and an unbuilt cell, and a page would depend on the order in which cells were built.
  • A throwaway prototype before this epic: the owner chose to go straight to the epic. Each building block proves itself with pictures and measurements instead.

Systems: trailview; planner-map-baking (GP18 makes finishes.json an option of the feature step, host/obc-data-steps/src/planner.rs).
Contracts: specs/trailview-features.md: the bake's rules change (one cross-section table, cover over untagged culvert crossings, kinds and tags for placement); features_format stays 4 unless a sub-issue proves a need. docs/design/trailview.md: owns gains the new crate. No settings blob, no device format.
Size: L (a new crate, the road, terrain and water paths of the viewer, the bake, well over 1,500 changed lines)

Words used here

  • Way: a road, track, path, railway, stream or river that OSM maps as a line.
  • Ground plan: the 2D map of the ground near ways and water in one cell: faces that never overlap and leave no gap.
  • Face: one polygon of the ground plan, with one owner, one surface and one height rule.
  • Owner: what a face belongs to: a way, a junction, a water body, a bridge deck, or the terrain.
  • Surface: what a face is, for its look and for placement: carriageway, shoulder, sidewalk, verge, corner fill, crossing, rail bed, platform, slope, seat, bed, bank, deck, terrain.
  • Height rule: owner, blend, kerb offset, slope or terrain (section 6).
  • Step edge: an edge where the faces on its two sides have different heights: a kerb, a wall, a headwall or a portal. The mesh draws it as a vertical face.
  • World unit: the terrain's integer unit: 2^−30 of the Web Mercator square, about 2.5 cm at 47° N (terrain/lod.ts:34). A tile unit of format 4 is 8 world units.
  • Node, level: the terrain grid draws Web Mercator tiles ("nodes") of 64 × 64 cells. A level-18 cell is 1.63 m wide (node 104 m), a level-17 cell 3.25 m (node 208 m).
  • Cell: what the crate builds at once: one zoom-16 tile, about 417 m wide at 47° N. It is one terrain node of level 16.
  • Piece: the mesh of a cell inside one level-18 node. The viewer culls and draws pieces.
  • Owned region: the level-17 terrain cells whose ground the mesh draws.
  • Strip: the outer ring of the owned region, one level-17 cell wide. Its outer border is the terrain's level-18 grid; its inner border holds level-17 grid vertices only.
  • Floor: the height under which the terrain grid holds its vertices inside the owned region.
  • Plan layer: the plan's height and mask near the eye, in textures of their own, for every reader of the ground where pieces draw.
  • Far stamp: the one stamp of the ways in every terrain page: core plane, cut and fill slopes and paint per segment, with no junction, sidewalk or snap logic. It replaces today's stamp on the new path.
  • Slope band: the band beside the outer edge of a non-terrain face, as wide as the class's reach, where the slope rule shapes the ground.
  • Reach: how far a rule looks from a point. The reaches of a chain of rules (the stages that lead to one result) add up to at most 191 m, inside the input margin of 192 m.
  • Level (of a face): 0 for the ground; each bridge deck has a level of its own.
  • Host, guest, seam: at a junction, a host keeps its shape. A guest meets the host at the seam, an edge on the host's side.
  • Crossing type: what happens where a way meets water or a railway: deck (bridge), culvert, ford, pipe in stones, stepping stones, footbridge, level crossing.
  • Integration branch: ground-plan, the branch that collects the work of the sub-issues.
  • Switch: ground=plan in the address. Until GP19, the old path is the default and every new viewer path runs only behind the switch.
  • Reference views: the views of road-views.json (121 views, the owner's views v01 to v17 among them), shot with shoot.mjs.
  • Fixture: the Engelberg box in builder/web/tests/browser/trailview/fixture/ with its terrain and feature tiles.

Facts

From the code on develop (4f8b8b255). Paths under builder/web/src/lib/trailview/ unless they start with host/, data/ or specs/.

Terrain:

  • One 64 × 64-cell grid, instanced per node, levels 1 to 18 (terrain/terrain.ts:290). Level 18: cell 1.63 m, page texel 0.41 m, node 104 m. Level 17: 3.25 m, 0.81 m, 208 m. Level 16: 6.5 m, 1.63 m, 417 m.
  • CDLOD (terrain/lod.ts:62-90): level 18 draws to about 480 m and morphs from 390 m; level 17 draws to 960 m and morphs over its far 19 %; level 16 to 1.9 km. The distance includes the eye's height above the ground (terrain/lod.ts:69). The range factor shrinks with the HUD's quality, and past a point the quality lowers the finest level: FINEST - Math.max(0, this.quality - steps) (terrain/terrain.ts:792-797).
  • In the morph, vertex_place slides each odd grid coordinate to the even one before it, axis by axis, so a vertex on a level-17 line slides along that line; place_height mixes the node's page at the vertex with the coarser page at the even vertex (terrain/drawn-mesh.wgsl:66-89).
  • At levels 16 to 18 the terrain also snaps its vertices toward road edges, from snap words that the stamp writes (terrain/drawn-mesh.wgsl:39-53).
  • Heights: pages of 256² r16 texels. Levels up to 14 are stored (zoom-13 tiles of 512 px, 6.5 m, where a national model exists, else GLO-30); levels 15 to 18 are the Catmull-Rom bicubic of the deepest stored ancestor, with no added detail (terrain/pages.wgsl:30). So the CPU can compute the same heights.
  • Heights are read by position across pages (terrain/drawn-height.wgsl:109-124). drawn_height returns the exact drawn triangle with snap and morph (terrain/drawn-mesh.wgsl:99); plain_height and stand_height skip the snap. Their readers: terrain/water.wgsl, structures/structures.wgsl, structures/houses.wgsl, structures/light-pools.wgsl, terrain/probe.wgsl (the eye), terrain/audit.wgsl, dressing/dressing.wgsl, vegetation/plants.wgsl, vegetation/forest.wgsl:306, vegetation/rows.wgsl:191, route/route.wgsl:86, instances/points.wgsl, instances/emit.wgsl.
  • The ground look ground_colour reads the level, the page normal, a facet term from screen derivatives and the road mask (ground/look.wgsl:650-674).
  • At a factor of 4.6 (usual screens and every phone), steps is 0, so the first quality step already removes level 18 (terrain/terrain.ts:795).
  • The stamp writes per page when the page is made (terrain/pages.ts:13-15): the stamped height, the mask (rgba8, levels 16 to 18: edge distance, sidewalk, metres along, surface code and flags; terrain/stamp.wgsl:127) and the snap words.
  • The terrain cuts no holes, other than unknown heights and tunnel portals (terrain/unknown-clip.wgsl; the portal boxes of terrain/terrain.wgsl:32-49 discard in a pipeline of their own). A pixel discard in the terrain cost +1.07 ms (walk) on the GTX, because it turns off the early depth test (TrailView A1: prototype, the cost of a near terrain that leaves the ways' ground to the corridors #3036). The walk draws about 1.0 M terrain triangles.

Corridors and looks:

  • A corridor vertex has 16 bytes: x and y in 2 mm steps, z, a word (material 7 bits, surface code 4, flags 5, band priority 3, half-width 9), across (12 bits) and along (20 bits) (roads/piece.ts, roads/section.ts:17-26). There are no normals: roads/corridor.wgsl:226 shades facets from screen derivatives, so the triangulation is part of the look.
  • The looks (roads/looks.wgsl, roads/track-looks.wgsl) read per pixel: material, surface code, flags, across, half-width, along, world position and the normal. Markings come from the shader; zebras and give-way lines relabel faces (roads/sweep.ts:67-74).
  • Corridors draw to 600 m (RANGE_M, roads/roads.ts:18); rails, sleepers, step treads and other details to 190 m. Casters (walls, rails, posts) draw into the shadow maps (roads/roads.ts:193). A main road costs about 7,500 vertices and 14,000 triangles per km, with sidewalks 14,500 and 28,000. Pools: 27 MiB vertices, 20 MiB indices, a 55 MiB worker heap.
  • roads/tracks.ts builds rails, sleepers and treads from roads/stations.ts and roads/sweep.ts.
  • Bridges have two builders that agree through pure functions: a corridor deck for paved roads at least 4 m wide (roads/decks.ts) and the rest in structures/bridges.ts, which draws every bridge, also far away. Footbridges and track bridges are flat paint.
  • Level crossings have no geometry of their own and no gates or signals.

Water:

  • A stream is a ribbon on the terrain mesh, lifted about 6 cm and blended; it is never stamped (terrain/water-mesh.ts, terrain/water.wgsl). A river stamps a flat floor at its level and banks of 0.5 m/m (terrain/stamp-core.wgsl:601). A lake is an opaque mesh at its level over a stamped bed (terrain/water.ts:28). A river area is a draped polygon.
  • Dams, weirs and waterfalls are in the tiles but not drawn. Culvert mouths exist only for streams up to 1.1 m wide (terrain/culverts.ts:339). The bake does nothing for a way that crosses a stream with no tag.
  • Plants grow in streams: streams are not in the mask (terrain/bins.ts:961).

Placement:

  • Rails, walls and delineators are decided per station from the stored terrain (roads/standing.ts, roads/details.ts:146); mapped guard_rail and retaining_wall come from terrain/bins.ts:312; lamps from roads/lamps.ts; point kinds move out of carriageways along the normal (roads/cores.ts:209, kinds/kind.ts:70) and stay where they are when no spot is free.
  • The viewer ignores the bake's walk field and decides sidewalks itself (terrain/bins.ts:472, stream/features.ts:213).
  • Catenary masts have no test against roads, paths or water (host/obc-trailview-features/src/rails.rs).

Bake and platform:

  • The feature layer rebakes in full when any input changes; OSM refreshes weekly by default (data/sources.toml:35). The road solver works per zoom-10 area with a 500 m halo (host/obc-trailview-features/src/roads/area.rs). side marks only junctions where three or more road or track ways leave a point; a path is never a way out (specs/trailview-features.md, Alignment).
  • Zoom-13 feature tiles of the fixture weigh 4 to 86 kB after gzip.
  • One WASM bridge exists, builder/wasm (1.24 MB, 478 kB gzip, builder/wasm/wasm_size_guard.py); TrailView loads no WASM. The site host forbids WASM threads.
  • i_overlay is in Cargo.lock (through geo, version 4, with i32 integer points); spade is not. Rust runs in the iOS app as static libraries with a C ABI (tools/build-ios-host.sh).
  • CI runs on every pull request, whatever its base branch (.github/workflows/ci.yml:40).

Architecture

1. Data flow

feature bake (Rust) ──► feature tiles (format 4) ─┐
stored terrain tiles ─────────────────────────────┤
data/trailview rule tables ───────────────────────┴─► obc-ground-plan (Rust, one cell at a time)
                                                       way graph → faces → heights → mesh → placement
                                                                        │
     viewer: pieces (the ground mesh near the eye) · floors (the terrain held under it)
             plan layer (height and mask for every reader near the eye) · objects
     every terrain page: the far stamp (one function, also under the mesh)

The crate is a pure function: the same inputs give the same output bytes on every platform. The bake links it natively, to run the checks over whole regions. The viewer runs it as WASM in a worker. The iOS app can later link it as a static library.

2. The crate

  • Place: host/obc-ground-plan, a member of the root workspace, owned by the trailview system (docs/design/trailview.md). GP5 adds a thin wasm-bindgen bridge, built by builder/build-wasm-bridges.sh with a size guard like builder/wasm/wasm_size_guard.py. The crate itself has no browser code.
  • Dependencies: i_overlay for integer polygon booleans and offsets; spade for the constrained Delaunay triangulation and its refinement; libm for every transcendental function, so native and WASM builds give the same bytes; faer only if the blend solve needs it. No threads.
  • Frame: all 2D work is in integers. The global frame is Web Mercator in 1/16 of a world unit (about 1.6 mm at 47° N), as i64. Each cell works in i32 relative to its origin, which is exact, and inside i_overlay's range. Metric lengths come from the Mercator scale at each point, in f64 through libm.
  • Input margin: a cell reads every zoom-13 tile that its square plus 192 m touches, usually one and at most four, and keeps one copy of each element by the owner rule of GP1 (each tile gives what lies in its own square; the tiles hold no OSM id). Each chain of rules stays at or below 191 m, so a result inside the cell does not depend on data past the margin. GP1 holds one table of every rule's reach and every chain, and its reader asserts the bound; GP6 owns the heights window (86 m past the cell), which the readers of heights farther out (GP16) need. A face depends on data up to 100 m away (GP2's corner room decision reads 70 m, and GP3's corner reaches 30 m from it), so the longest chain is the window plus that: 186 m. Only the graph stage reads that far; the faces, heights and mesh work in their own windows, so the larger margin costs little. The format's tile buffer of 40 m does not limit the margin, and the bake does not change for it.
  • Same borders in two cells: integers alone do not make it so. The crate samples each curve at global parameters (a span and the metres along that span, not the stroke metres, which two tiles round differently by up to 10 cm), splits every input polyline at the cell lines before any boolean, keeps every blend local (section 6), and splits the cell's border segments by a rule that reads only the border, then locks them (section 7). A check compares the borders of every pair of neighbouring cells of the fixture.
  • Debug tool: one command writes top-down pictures (faces by surface, heights as hillshade and contour lines, step edges, the mesh as wireframe, objects) of a list of places, plus a glTF file of a place for a 3D look. The places are the positions of the reference views. Every sub-issue of the crate proves its work with these pictures.

The shape that all sub-issues use (GP1, GP3 and GP7 fix the names and the bytes, and keep the meaning):

Type Holds
CellKey the zoom-16 tile
Way a key from local data (the tiles hold no OSM id), class, kind, the level of each way piece, its curve (cubic Hermite spans of format 4), walk and side per vertex, the tags that the rules read
Junction its point, its arms (way, end, heading, host or guest)
Crossing the two features, the point, the crossing type
Face id, owner, surface, level, height rule, polygon with holes
Edge the two faces, its kind: continuous, kerb, wall, headwall, portal, deck edge, cell border
Piece the level-18 node, vertices, the index ranges: interior near, interior far, strip, casters
Floors per level-18 and level-17 node in the owned region: one height per grid vertex, or none
PlanLayer per level-18 node in the owned region: the plan's height and mask per page texel
Object, EdgeFeature a model with its position and heading; a guardrail, post row or railing along a line

3. Inputs

  • Feature tiles of format 4, decoded by a Rust decoder in the crate, tested against specs/vectors/trailview-features.json and .bin. A cell reads the zoom-13 tiles that its square plus the input margin touches; the owner rule keeps one copy of each element by position.
  • Terrain: the stored terrain samples under the cell plus the margin. The crate computes heights with the same Catmull-Rom and the same r16 steps as terrain/pages.wgsl. The viewer hands over the samples from its terrain decode worker; the bake reads the terrain tiles.
  • Rule tables in data/trailview, read by the bake and the crate alike. Values by place come when a region needs them; until then the readers reject them, because a value that changes at a border would step on a cell line:
    • roads.json gains one cross-section per class: the carriageway's half-width and how width and lanes tags change it, shoulder, kerb height and width, sidewalk width, verge, the cut and fill slopes and their reach, the steepest slope, the return grade of a guest, the corner radius per class pair, the mouth rule per class pair. Today these values live in terrain/bins.ts, roads/section.ts and two tables of the bake, with different numbers.
    • A new plan.json holds the rules per class pair and per face (corner radius, mouth rule, priority, minimum width) and the blocks that later items add (marks, walls, structures, placement); every top-level key of roads.json stays a class. A new finishes.json holds the values per surface finish (for example the cap of a footway's width).
    • waterways.json gains the cross-section of flowing water (bed depth by width, bank slope, bank width, freeboard) and the crossing rules; a new shores.json holds the same fields for standing water (lakes, ponds, basins, river areas, the sea).
    • No value of these tables lives in code.

4. The way graph (stage 1)

  • Curves: each way part becomes its cubic Hermite curve from the alignment of format 4 (position, tangent, height, grade, bank, widen), sampled at global arc-length parameters.
  • Junctions: a point where ways share a vertex. Its arms are the ways out. The hosts are the through pair that side leaves unmarked. Where side marks nothing (paths, junctions of two classes that side does not cover), the host pair is the pair of the first class in the table that runs most nearly straight on; a path is always a guest of a road or a track. A point of two ways is a joint, not a junction.
  • Close junctions: junctions whose areas overlap (a side road at a dual carriageway, two side roads a few metres apart) need no merge. Each keeps its own hosts; the overlay keeps every host's carriageway as an owner face, and joins the blend parts of both into one blend face (sections 5 and 6).
  • Snapped ends: a way's end that lies within 1 m of another way's carriageway and within 0.5 m of its height becomes a guest of that way (GP2 sets the values). Farther, or at another height, it stays an end with its own end shape.
  • Levels: bridge parts (with a deck tag) and tunnel parts leave the ground level. The ground under a bridge is terrain, water or a way below.
  • Crossings: a way over or under another way with no shared vertex, a way over water, a way over a railway. Each gets a crossing type: from tags first, then from the rule tables (section 12). Two ground ways that cross with no shared vertex at a height that neither a junction nor a deck explains (an OSM fault) get the type Stacked: no structure; the overlay and the rule for unrelated owners give their faces. A synthetic deck splits a way, so the level belongs to each way piece.
  • Cleaning: repeated vertices, zero-length segments and spikes go. The stats count each removal.

5. Faces in 2D (stage 2)

  • Bands: each way part gives its carriageway: two offset curves of its alignment, with widen. Then per side a shoulder, or a kerb and a sidewalk where walk says so, then a verge, as its class's cross-section says. A railway gives its bed (ballast) by gauge, a platform its own face at its height.
  • Tight bends: a way's carriageway is the union of its bands, so the loop of an inner offset disappears by construction. Then the inner edge gets a fillet along the curve: where the inner offset turns tighter than the class's inner radius, an arc of that radius replaces it. It is never a closing of the whole carriageway, which would join two hairpin legs that lie closer than twice the radius.
  • Junction area: the union of the arms' carriageways near the point (a blend part ends at its ramp end, every other part within the table's extent of the point), plus one corner fill between each two neighbouring arms. A corner fill is a closing with the corner radius of the class pair, of those two arms' bands only, cut to the sector between them, with the radius made smaller until the fill fits the room: the angle and the arms' length to the next junction. A corner fill takes the surface of the lesser arm. This works at any angle and for any mix of classes, and a junction has no special pieces.
  • Mouth rules per class pair, as data:
    • a road into a road: the guest's carriageway reaches the host's carriageway edge and cuts through the host's sidewalk; the kerb turns round the corner fill;
    • a driveway (GP4 defines it from tags) into a road with a sidewalk: the sidewalk runs on with a lowered kerb, and the driveway stops at the sidewalk's back edge;
    • a track or a path into a road: the guest stops at the road's edge, or at the back edge of the sidewalk on that side, with a small corner fill in its own surface; the host's edge line runs on;
    • a path into a path: union with small corner fills;
    • steps: the first step stands at the seam.
  • Sidewalk corners and ends (the owner's rules, TrailView roads: why the road system tears, and a planar road map #3095 section 8): where both arms of a corner have a sidewalk on that corner, the sidewalk follows the kerb round the corner fill. Where only one has one, it runs straight to the other arm's carriageway edge and ends there. Every other end angles toward the road: the kerb stays straight on the carriageway's edge, the back edge converges to the kerb over a taper, the kerb's height falls to zero over the taper, and the ground fills behind.
  • Buildings: a sidewalk, then a shoulder, gives way where a building stands in its band, and the cut gets the same end shape. A carriageway never gives way.
  • Overlay: the faces of all ways, junctions and water of a cell go into one planar map by a priority table (data): for example a carriageway before a blend part, a higher class before a lower one, a road where it crosses a rail bed (the crossing face: the road's surface, the rails flush in it), a culvert's embankment before the stream. Blend parts that touch stay separate faces, one surface each; their shared edge is a blend join, and the blend rule treats the joined parts as one region. The result is a planar partition: each point of the owned region lies in exactly one face.
  • Slope bands: each outer edge of a non-terrain face gets a slope band as wide as its class's reach, cut by the other faces. Slope bands have a fixed 2D extent, so stage 2 draws them before any height is known; stage 3 only shapes the ground inside them.
  • No slivers by input: a face part thinner than the minimum width (GP3 sets it) merges into its neighbour of higher priority, and a sharp tip is cut where its width reaches the minimum. A sidewalk's thin piece never merges into the carriageway (it would move the road's edge); it goes to the sidewalk or the ground behind. Two near-parallel ways cannot leave a sliver.
  • Edges: each edge between two faces gets a kind: continuous, kerb, wall (decided in stage 3), headwall, portal, deck edge or cell border.

6. Heights (stage 3)

Heights are a function of position for each face, never of the mesh. The mesh reads them at its vertices. The rules run in this order, and each reads only the results of the rules before it:

  1. Owner rule (carriageways, shoulders, verges, crossings, rail beds, platforms, decks, water surfaces): the face takes its owner's profile: at a point, the height of the curve at the nearest station plus the bank times the signed distance across. A face uses this rule only where the nearest station is unique and well-conditioned (the distance to the curve is less than the curve's radius minus a margin). Elsewhere it is a blend face.
  2. Blend rule (the part of a junction area outside the host's carriageway, corner fills, mouths, the inner tip of a tight bend, the ramp where a guest returns to its own heights): a smooth interpolation of the heights of the face's own owner edges. It is local: a point reads only owner edges within the blend radius (below the margin), with weights that fall to zero at that radius, so two cells give a point the same height without solving any face whole. It equals each owner edge's height on that edge, stays between the heights around it, and is continuous. Every blend face lies within the blend radius of its owner edges by construction: corner radii, ramp lengths and tips have caps in the table. A guest's return ramp is as long as its height difference divided by its class's return grade (0.15 for roads, 0.3 for paths, in the table), lengthened by the method's steepest point, so the grade holds; a ramp that hits its cap is counted in the stats. Blend parts joined by a blend join form one region, so no two blend regions share a free edge. GP6 chooses the method (for example distance weights, or mean value coordinates) from pictures.
  3. Kerb offset (sidewalks, kerb tops, tapers): the height of the carriageway edge beside it plus the kerb and the cross-fall. The kerb falls to zero at a lowered kerb and over an end's taper.
  4. Slope rule (inside slope bands: cut and fill slopes, banks, the spill-through slope of a bridge seat): every edge of a non-terrain face gives a fill slope that falls and a cut slope that rises from the edge's height, across its band; the slope of a way starts at its verge's outer edge. Some edges give no cut or no fill (a portal, a deck's transition edge, a gallery's hill side), and some features add bounds of their own to L and U (the trough under a deck, the cover over a bore, a gallery's backfill, a mapped barrier=retaining_wall). Let L(x) be the highest fill slope and U(x) the lowest cut slope at a point x, and T(x) the terrain. The ground is min(U, max(T, L)), so the cut wins where two slopes conflict. A slope is the class's value, made steeper up to the class's steepest slope where that lets it meet the terrain within the reach. Where even the steepest slope does not meet the terrain within the reach, the slope has no room: it shifts by the height still missing (a fill down, a cut up), so it meets the terrain exactly at the reach. Past the reach the ground is the terrain. So the ground is continuous everywhere, and the slope band is bounded by the reach.
  5. Walls: at every edge of a non-terrain face, where the ground beside the edge differs from the edge's height by more than 1 mm, a step edge stands, and where it differs by more than 1 cm that step is a wall with a wall's look, shadow and placement: a step edge of that height, whose top is the higher side. It stands downhill where a fill has no room or where two slopes conflict (always at the edge of the higher feature), and uphill where a cut has no room. Along the edge it is continuous and shrinks to nothing where the difference ends. This is the owner's rule "a derived wall stands only where the slope has no room" and "between two legs of a hairpin, the wall reaches up to the upper road". A slope face steeper than the look's limit gets the rock or wall look; that is a look, not a step.
  6. Unrelated owners: an edge between faces of two owners that no junction joins (a path beside a road, a road on a river's band) is a step edge whose height is the difference of the two rules, continuous along the edge.
  7. Terrain rule: terrain faces inside the owned region and the strip take the terrain.
  • Water gives two slopes (section 12): the waterline gives a cut slope that rises as the bank, and the bank top gives a fill slope that holds the ground at least the freeboard over the water.
  • Owned region: every level-17 cell that a non-terrain face or a slope band touches, grown by one cell of terrain (so no face edge touches the strip) and one cell for the strip. The far stamp changes the ground only within a way's core and reach from the same table, so the owned region covers it without a copy of the far stamp in the crate.

7. Mesh (stage 4)

  • Triangulation: one constrained Delaunay triangulation per cell and level (a deck has its own, with locked shared vertices on its transition lines). Each face edge is a constraint. Inside slope and terrain faces, the level-18 grid points (1.63 m) are added, except within 0.4 m of a constraint. Refinement holds a minimum angle of 20° and a maximum edge length per surface (GP7 sets it). At a plan corner under 60° no refinement can hold 20° (Ruppert's limit); GP7 counts those triangles apart, and GP3's tip rule keeps them few.
  • Cell borders: each border segment is split at its grid points and its crossings with face edges, then halved by a rule that reads only the border, and locked; refinement never splits it. So two cells meet vertex for vertex. A triangle on a locked border segment has a weaker angle bound, which GP7 measures and gates.
  • Heights from section 6 at each vertex. A step edge has two vertices at each point, joined by a vertical face; its top is the higher side.
  • Strip: one level-17 cell wide around the owned region. Its outer border holds the terrain's level-18 grid vertices: they are given as grid indices and go through the terrain's own vertex code (vertex_place, place_height), so they slide, morph and take their height exactly as the terrain's do. Its inner border holds level-17 grid vertices only, which never slide; the interior of the mesh meets the strip only there. The inner border is locked like a cell border: the triangulation adds no point on it, neither a Steiner point nor a level-18 grid point. Each strip triangle has at most one sliding vertex, which moves along the outer border toward the even vertex beside it, so no strip triangle can turn over; at the strip's corners a fixed pattern keeps that rule. Over a level-17 node the strip draws with the morph forced to 1, which makes it exactly the level-17 cell row. One strip serves both levels. GP7 adds a middle ring to the strip where the terrain's own triangles at the outer border slide away from it in the morph (the south and east sides of the owned region).
  • Pieces: the mesh is cut into one piece per level-18 node, with index ranges for the interior near the eye, the interior far from the eye (GP7 sets what it leaves out), the strip, and the casters (vertical faces and objects that throw shadows).
  • Floors: for each level-18 and level-17 terrain vertex inside the owned region, but not on its outer border: the lowest height of the drawn mesh (its triangles, the strip's chords included, at morph 0 and at morph 1) over the terrain cells next to the vertex and next to the vertex it slides to, minus 5 cm. The strip's chords lie under the terrain on convex ground (up to L²κ/8 for a chord L at curvature κ), so the floor is measured against the triangles, never against the height rules.
  • Vertex: the position in its piece in integer steps, the height, today's look word, across and along, a normal from the height function (not from the facets), and a flag for strip vertices. GP7 fixes the bytes.
  • Validity: every triangle turns counter-clockwise in plan; every edge has two triangles, or is a step edge with its vertical face, or is a border; the minimum angle holds except on locked borders; every face is at least the minimum width; the floor lies under the drawn mesh everywhere. These are hard checks with the target 0, not baselines.

8. Ownership in the viewer

  • A plan worker builds the cells near the eye in order of distance and ahead of the eye, posts pieces, floors, the plan layer and objects, and drops cells that fall out of range from fixed pools.
  • The terrain does not snap on the new path, at any level: the far stamp writes no snap words.
  • The terrain vertex shader: on a level-18 or level-17 node, a vertex inside the owned region takes min(its height, its floor). That is one texture read per vertex. There is no pixel discard, no clip distance and no cover pass, and the terrain stays one instanced draw. The tunnel portal boxes stay as they are.
  • A piece draws only where the terrain draws at level 18, or at level 17 without a morph (GP9 tests this per point through the range), with the strip. The range stops at the nearest node that cannot draw (a cell not built, a pool full), so the mesh always covers a full disk. Pieces draw before the terrain, so the early depth test rejects the terrain under them. GP9 reads the floor from a storage buffer by vertex index.
  • Range, in the LOD metric (which includes the eye's height): the mesh draws to the smaller of about 600 m and 40 m before the distance where level 17 starts to morph, at two levels of detail: the full mesh near the eye, and a lighter outer level past the level-18 plateau (road faces and step slots, fewer ground points). Over its last 40 m it fades out with today's dither; there the floor is off, and the terrain shows the far look. Changed by the plan after the 2026-11-07 review: today the mesh ends at the level-18 plateau, about 195 m; steps 3 (TrailView ground plan, step 3: the mesh on level-17 terrain nodes (design first) #3196) and 6 (TrailView ground plan, step 6: the mesh range toward 600 m at two levels of detail #3199) bring it toward 600 m.
  • Lower quality: when level 17 is the finest drawn level (the first quality step on most screens and on phones already does that), pieces draw over level-17 nodes with the strip at morph 1. Only when the finest level is below 17 does no piece draw; the far look then shows the ways. The switch between the two has a hysteresis, so it does not flicker. Changed by the plan after the 2026-11-07 review: this mode is not built. Pieces draw only when the finest level is 18 (plan/pieces.ts), so no mesh draws on a phone. Step 3 (TrailView ground plan, step 3: the mesh on level-17 terrain nodes (design first) #3196) designs and builds it.
  • Readers: exactly where pieces draw (the same node test and the same fade), every height read returns the plan layer: the plan's height per level-18 page texel, bilinear, and the plan's mask for the mask reads. The plan layer hooks into the one function under drawn_height, plain_height and stand_height, so every reader of the facts' list, vegetation/forest.wgsl and vegetation/rows.wgsl included, reads it and none reads the floored terrain; only the audit and the terrain's own surface test read the stamped terrain. Across a step edge, the bilinear read uses only the corners on the point's side, so an object at a wall's foot does not float. Where no piece draws, they read the terrain as today.

9. The far stamp

  • One stamp function shapes and paints the ways in every terrain page on the new path, near and far: per way segment, its core plane, its cut and fill slopes from the cross-section table, and its paint. It has no junction, corner, sidewalk or snap logic. No page depends on the order in which cells were built, and a shot of a view is the same each time. GP8 builds it before the first real views (GP9), so those views already run on it. On the new path, GP8 also turns today's corridors off (they read today's stamp); until GP9 the new path shows no road mesh near the eye. The lake and sea shore ramps end at 15 m.
  • The far stamp changes the ground only within a way's core and reach, and the owned region covers that by the same table (section 6), so at the strip the stamped terrain and the plan's terrain faces are both the plain terrain.
  • At the end of the mesh range, the far stamp draws the ways alone. GP10 shows the handover at the junctions of the reference views; if corners jump visibly, the far stamp gets the corner radii of the table, not the junction plan.
  • Plants keep off every water face, streams included (the plan layer's mask near the eye, the far stamp's mask far from it).
  • Changed by the plan after the 2026-11-07 review: the one road model replaced the far stamp; the far look evaluates the cell's records (GP8 as built). Past the mesh, the far look shows only what a height grid can show: a wall is a steep band one grid cell wide with the wall's look painted on it, a kerb is paint only, and the far look and the piece fragment call one paint function with the same inputs (step 5, TrailView ground plan, step 5: the far look past the mesh, one paint function #3198).

10. Looks

  • Way faces use roads/looks.wgsl and roads/track-looks.wgsl with today's inputs and a smooth normal. Markings stay in the shader. In a junction the host's coordinates run through, so its lines continue; a guest's seam gives the give-way line; a zebra comes from its OSM tag.
  • Ground faces (slopes, verges, banks, the strip, the terrain inside the owned region) use the terrain's ground look function ground_colour. Its normal and its facet term become inputs: the terrain passes its own as today. The strip and the plan's terrain faces pass the terrain's own values at the pixel (the page normal, and the facet of the terrain triangle under the pixel, from the page), so they cannot differ from the terrain although their triangles differ. Slope faces pass their own. On the mesh the road paint of the mask is off, because the mesh draws the ways.
  • Walls, kerbs, headwalls and portals get their looks (masonry, concrete, rock) from the tables.
  • Steep slope faces show no stretched texture (TrailView A8: steep faces without stretched texture #3092). Whether they show rock or earth, the owner decides from GP11's pictures.

11. Bridges, tunnels, galleries, railways, steps

  • Bridge: a deck plan at its own level: the same bands, junction areas and heights as on the ground, but no slope faces. Its free edges get parapets or railings by class and the region's rules. A slab of the deck depth and its underside run under the deck; piers stand on the ground plan at the bake's points. Footbridges, track bridges and narrow decks use the same code; today they are flat paint. Deck plans draw within the mesh range, with its fade; past it, every bridge draws as a simple structure, as structures/bridges.ts does today, with the opposite fade, so no bridge is missing in a built cell past the range.
  • Abutment: where a bridge leaves the ground, the ground plan holds a seat face at the height of the deck's underside. Its slopes (rule 4) make the spill-through slope, and where that slope conflicts with a way or water below, the wall rule gives the abutment wall. The deck's end edge and the ground way's face share one edge, at the transition line past a junction's paved faces.
  • Tunnel: the ground way's face ends at the portal line, the approach cut meets the terrain by rule 4, and the portal is a step edge whose vertical face leaves the bore open, with today's portal facade. The terrain keeps its portal boxes. Galleries keep their structure.
  • Railways: rails, sleepers, rack and cables are built along the track's curve, not from stations, within the detail range of 190 m. A platform is a face at its height with a wall edge to the track bed.
  • Level crossing: where a road crosses a rail bed, the crossing face takes the road's surface on the track's plane at the rail tops, with a blend ramp back to the road's own heights (the road banks and has its own grade), and the rails run flush through it. Barriers, crosses and lights stand at the crossing's edges from the OSM tags of the railway=level_crossing node (crossing:barrier, crossing:light, crossing:saltire).
  • Steps: a flight of steps is an owner face with its ramp; the treads (stone in towns, logs on trails) are built along its curve within the detail range.

12. Water

  • A water body gives two things: its bed and banks are faces of the ground plan; its surface is a mesh of its own over the same polygon at the water's level, with the water look of terrain/water.wgsl.
  • Streams, rivers and canals: the water face is the line's band (width from the tag, else the class). The bed is a trapezoid under it: depth by width from waterways.json, sides at the bank slope. The bank rises from the waterline at the bank slope to the bank top, which stays at least the freeboard over the water, so water never lies flush on flat ground. Where the level lies far under the terrain, the banks are the steep cut slopes of rule 4.
  • Lakes, ponds, river areas and the sea shore: the polygon is the water face, the bed falls inside the shore by the profile of shores.json, and the bank is a slope outside it. The far look paints water from the same records (owner decision 2026-11-06; design in TrailView ground plan GP14: water near the eye, beds, banks and surfaces of streams, rivers, canals, lakes, ponds, river areas and the sea shore #3107).
  • Crossing types, from tags first, then from the rules of waterways.json by the way's class and the water's width:
    • a bridge tag: a deck (section 11);
    • a culvert (tunnel=culvert, a short bridge that the bake makes a ground road, or a road, track or railway over a stream with no tag up to a width): the way's faces and its fill slopes cut the stream; the bed ends at a headwall flush with the fill slope, and a pipe model stands in it. The bake lifts the way by the cover over untagged crossings too (GP18);
    • a ford (a ford tag or a shared vertex): the way's surface is the bed there, and the water surface runs over it; on a path, ford=stepping_stones gives stepping stones, and the bake does not sink the path there;
    • a path over a stream with no tag: up to 0.6 m wide a pipe in stones, up to 2 m stepping stones, wider a timber footbridge (a deck). These are the owner's defaults in the table.
  • Not built now: dams, weirs, locks and waterfalls. A water face holds a level per point, so a later change can add a dam as a step edge across it.

13. Placement

One module of the crate places objects from the plan, for each cell, deterministically. An object belongs to the cell that holds its point. Spacing runs along the stroke metres of format 4 (along), so every cell counts from the same start.

  • Edge features along way edges:
    • a guardrail where the ground beside the edge falls by more than the rule's height within the rule's distance, or a wall falls from the edge, or water lies below, on the classes and outside the towns that the rules name; at a mouth it ends with a terminal; mapped barrier=guard_rail wins;
    • delineator posts on the rules' classes outside towns where no guardrail stands, at the region's spacing and closer in bends, never across a mouth;
    • a cap or a railing on a wall higher than the rule's height; mapped barrier=retaining_wall makes a wall where the plan has none.
  • Point objects:
    • street lamps along the sidewalk's back edge (else the verge), in towns or on ways with lit=yes, at the rules' spacing, never in a mouth, a driveway or a corner fill; mapped highway=street_lamp nodes snap to the nearest allowed spot;
    • OSM point kinds (benches, guideposts, picnic tables, shrines, …) snap from their node to the nearest face that their kind allows (verge, sidewalk back, terrain); a guidepost goes to the widest corner of its junction;
    • catenary masts, aerialway pylons and stations slide in the bake (GP17), because they draw at every distance and a pylon anchors far cable spans: a move in the crate would make them jump when a cell builds;
    • level crossing equipment (section 11), culvert pipes and headwalls (section 12).
  • A point object never stands in a carriageway, junction area, rail bed or water face; pipes and stepping stones stand in water on purpose and are exempt from the water test only. Objects keep clear of each other within one cell; two near a cell line can overlap, and the stats count it.

14. Checks

Each stage proves its output with hard checks over every cell of the fixture, target 0. The bake can run the same checks over a whole region when the owner asks.

  1. The faces form a planar partition of the owned region: no overlap, no gap, valid polygons, no face thinner than the minimum width.
  2. Two neighbouring cells hold the same vertices, heights and attributes on their shared border.
  3. Every continuous edge has the same height on both sides (less than 1 mm apart), and every step edge's top is its higher side.
  4. Every triangle turns counter-clockwise in plan; every edge has two triangles or is a step edge or a border; the minimum angle holds, with the weaker bound on locked borders.
  5. The floor lies at least 5 cm under the drawn mesh (the strip's chords included, at morph 0 and 1) over each owned terrain cell.
  6. No point object stands in a carriageway, junction area, rail bed or water face (pipes and stepping stones exempt from the water test).
  7. A native build and the WASM build give the same bytes for every fixture cell (GP5 adds this check with the WASM build).
  8. In the viewer, no terrain pixel draws in front of the mesh inside the owned region and no crack opens at the strip: a GPU count in a debug mode over the walk and drive flights, which allows equal depth (a terrain triangle that lies on the strip's border is the strip's own triangle).

The census (scripts/road-census.ts, tests/browser/trailview/census.mjs) and the torn-face gate of #3085 measure the old corridors. GP0 records them as the baseline, and they go with the old code in GP19.

15. Budgets

Measured on the GTX 1660 SUPER with flight.mjs --gpu (clock held); the owner flies the M1 Pro at each checkpoint.

  • Frame: ways, water and ownership together cost no more than develop's corridors, band and stamp in the walk and drive flights (GP0 measures them), and at most 0.8 ms more than the same flight with no ways drawn (the budget of TrailView: ways and water that sit in the terrain near the eye #3031).
  • Cell build: GP7 measures the native time and the WASM time in Chrome on the GTX box, and gives the owner a timing page for the iPhone in Safari. The owner then sets the gates. The view near the eye must be complete within 2 s of a jump on the GTX box.
  • Memory: pieces, floors, the plan layer and objects fit today's corridor pools (27 MiB vertices, 20 MiB indices, 55 MiB worker heap) plus the plan layer's pool, which GP10 sizes.
  • WASM: GP5 sets the size budget of the bridge and adds a guard.
  • Tiles: the feature archive grows by less than 2 % (kinds and tags only).
  • Bake: the feature step takes less than 10 % longer.

16. What goes at the end

GP19 deletes, once the plan is the default: the sweep and the special pieces in roads/ (stations.ts, section.ts, sweep.ts, joints.ts, junctions.ts, arms.ts, corner.ts, planes.ts, path-ends.ts, junction-faces.ts, mouths.ts, shore.ts, standing.ts, ground.ts, cores.ts, ways.ts, decks.ts, band.wgsl, the rules of lamps.ts, the parts of tracks.ts that GP13 replaced); today's stamp and its snap (terrain/stamp-core.wgsl, terrain/corners.ts, terrain/approaches.ts, the snap words); terrain/culverts.ts and roads/cores.ts once GP19 gives their far readers (far ribbons, building signs, arête rocks) a replacement; roads/details.ts (GP16 moves its geometry into the crate; details.wgsl stays); the corridor pipeline itself (GP19 moves the piece's fragment and the part pipeline into plan/); the stream ribbons near the eye; the hand-over of structures/bridges.ts to the corridors (its simple deck past the range stays); the census and the torn-face gate of the old meshes. The looks stay.

How we work

Branches:

  • The integration branch ground-plan starts from develop. GP0 or GP1, whichever starts first, creates it (the owner approved this flow).
  • Each sub-issue has its own branch from ground-plan and one pull request into ground-plan. CI runs on it. An adversarial reviewer (Opus, high) reads the pull request, the implementer fixes the findings, and the pull request merges when CI is green and the findings are resolved.
  • At the start of each wave, ground-plan takes in develop (a merge, conflicts fixed in the merge).
  • Until GP19 the old path stays the default and unchanged; every new viewer path runs only behind the switch, so one build shows old and new.
  • GP19 merges ground-plan into develop after the owner accepts the views and the budgets. Then the owner starts the production rebake.

Proof in each pull request:

  • The checks of section 14 that the sub-issue touches, with their commands.
  • Measurements: time per cell, triangles, memory, and frame times where the GPU draws, with the clock held.
  • Pictures:
    • crate stages: the debug tool's top-down pictures of the sub-issue's places, before and after;
    • viewer stages: shoot.mjs --gpu --views trailview/road-views-top.json (from above, pitch −89) and --views trailview/road-views.json (at eye height), with --width 1920 --height 960, for the sub-issue's views, with and without the switch, on one slider page.
    • The implementer looks at every picture before it claims a fix.
  • One GPU user at a time: flock /tmp/trailview-gpu.lock.

Rules for every agent:

  • A torn, folded or sliver face is the worst fault. A builder never emits a face to cover a case that it cannot fit: the rules decide, and the output of every rule is a valid plan.
  • No code for one region: regional differences are rule values in data/trailview.
  • No tuning for one view: a fix changes a rule for the whole class of cases and is proven over the whole fixture.
  • Judge a view at 2×, from above and at eye height, against a real street, not against develop.
  • Write the algorithm and its invariants into the sub-issue before coding, and change the sub-issue when the code teaches otherwise.
  • Implementers: Opus at xhigh for GP3, GP6, GP7 and GP9; Opus at high for the others; reviews at high. One agent per sub-issue, at most three at a time. After two failed rounds on one sub-issue, stop and report to the owner.
  • Run commands through obc; test the crates you change (obc test -p obc-ground-plan, obc exec cargo clippy -p obc-ground-plan --all-targets -- -D warnings); cargo fmt --all; in builder/web for viewer changes: npx vitest run src/lib/trailview, npm run check, npm run check:wgsl.
  • Each pull request carries Mode: change #<sub-issue> and Requirements: none unless a TrailView requirement exists (this machine has no verification agent token; ask the owner).
  • Public docs change in GP19 only, as a docs: commit.

Owner decisions

The owner approved this epic and its sub-issues on 2026-11-03, with every recommended answer of the sub-issues' questions. The ones that change the look: streams and rivers on flat meadows lie in a channel under the meadow (the bake lowers their levels, GP18), not on a dyke; steep slope faces are bare earth, rock where barren (GP11 shows pictures); tracks take the spec's datum, the top of the rails (GP13); an untagged road, track or railway over water up to 3 m wide gets a culvert, over wider water a bridge (GP2); barrier arms are raised, and untagged level crossings get lights and a cross on roads, a cross on tracks (GP13).

Plan

Each item is one sub-issue and one pull request into ground-plan. The owner looks at the results at each checkpoint (✓).

Wave Sub-issues Checkpoint
1 GP0, GP1
2 GP2, GP18
3 GP3
4 GP4, GP5 ✓ junction and sidewalk shapes from above, in the debug tool and the viewer
5 GP6, GP8 ✓ heights, slopes and walls (pictures and glTF)
6 GP7 ✓ cell build times, native, Chrome and the iPhone
7 GP9 ✓ the first real views: no tear, no crack
8 GP10, GP11 ✓ looks, readers and the far view
9 GP12, GP14
10 GP13, GP15 ✓ bridges, tunnels, railways, steps and water
11 GP16, GP17 ✓ placement
12 GP19 ✓ acceptance, budgets on the GTX and the M1 Pro, merge into develop

Plan after the 2026-11-07 review

Two independent big-picture reviews of the merged state 78ddd5913 (ground-plan, walls #3185, junction records #3186) found where a view loses its time and why the far view jars.

Verdict: the architecture is sound. Do not rewrite it. The face plan, the integer overlay, the CDT mesh with step slots, the sunk terrain points with the strip, and the crate as a pure function stay. The faults are where the work runs, the mesh's tie to one terrain level, and one module (heights) that blends too much.

Owner decisions (2026-11-07):

  • No bake of records, faces or bins into the release. The feature tiles of the Central Switzerland box are 46.5 MB; its records would be 1.7–3.3 GB and its faces 1.1 GB (today's encoding).
  • The mesh reaches about 600 m at two levels of detail. Past it, a far look shows only what a height grid can show.

Steps, in this order:

  1. Stamp worker and small bake:
  2. TrailView ground plan, step 2: no far records, one tile parse, one near-first order, the margin cache #3195: the no-regret record fixes: no far records in build_cell, one z13 parse per worker, one near-first order with the eye field, the margin-work cache. (M)
  3. TrailView ground plan, step 3: the mesh on level-17 terrain nodes (design first) #3196: the mesh on level-17 terrain nodes; design first, with a test on the owner's iPhone. (L)
  4. Ground plan heights: slopes start from the face plan's paved outline #3187 (D1), then TrailView ground plan, step 4b: the paved heights read the face plan (after D1) #3197: the paved heights read the plan. (M)
  5. TrailView ground plan, step 5: the far look past the mesh, one paint function #3198: the far look past the mesh, one paint function. (M) Needs step 6.
  6. TrailView ground plan, step 6: the mesh range toward 600 m at two levels of detail #3199: the range toward 600 m with a lighter outer level and a frame gate. (L)
  7. TrailView ground plan, step 7: the device cache of built cells and the route prebuild #3200: the device cache and the route prebuild. This is the phone's path to the load target, not an option. (M)

Before the far-cell work (steps 5 and 6): #3201 measures the coarse-records word count, the stamp GPU time per level-18 page, plan-timing.html on the owner's iPhone, and the dense-city caps. Small special cases: PATH_HALF_M from the class and the stops() table value on #3186; one rail rule on #3188. Not now: more stamp workers (measured worse). Later: measure a compact baked format that refers to the tiles' centre lines before anyone proposes it.

Guard rule: nothing new reads the records on the GPU except through height_at / model_at, and heights.wgsl gets no term that the Rust heights lack. This keeps a later replacement of the GPU height function possible.

Measurements (78ddd5913, Ryzen 5 3600 and GTX 1660, cold loads, the PC under load; v17 = Engelberg town, eye 1.7 m; m1 = Trübsee 46.7905, 8.3933, heading 200, eye 1.7 m):

  • Time to a clean frame: v17 18.7 s (develop 15.3 s), m1 11.1 s (develop 11.0 s). A warm load is not faster: the worker CPU is the cost, not the network.
  • The stamp worker is the critical path in both systems: busy 17.0 s at v17 (develop 13.0 s). Level 18: 292 jobs, 4.8 of 6.6 s is whole-tile work redone per node; a per-tile memo measured 6.6 → 1.9 s. Level 9: 3.8 of 4.3 s is the z8 features(), redone per node. Pieces waited 6.5–15 s for level-18 stamps.
  • Records: 7.0 s of worker CPU per v17 view (63 cells). No far records and one tile parse per worker measured −25 % native (3,170 → 2,380 ms for 62 v17 cells). The 192 m input margin is 3.7× the cell's area of input.
  • The mesh ends at about 195 m; develop's corridors reach 600 m. 600 m at today's density is about 9× the area, and v17 already draws 329 k triangles in view.

A cold jump into a town: after steps 1 and 2, on the client path, it lands at about 1.5–3 s on desktop, more on a phone (an estimate). While riding, cells build ahead, so this does not matter.

Proof for each step: time to a clean frame, cold and warm, at v17 and m1 against develop (a shot every 0.5 s, diffed to the final idle frame with the HUD masked; clean = under 1 % of pixels off by more than 40 levels); the frame time with GP0's method (flight.mjs --gpu, the clock held, walk and drive); renders of the owner's views, develop | new. No phone numbers before plan-timing.html has run on the owner's iPhone.

Order of the remaining work

The ordered list, one line per issue with what blocks what: #3096 (comment) (a comment, because this body is at GitHub's length limit).

Done when

  • Every sub-issue has merged into ground-plan, and the checks of section 14 pass in CI over the fixture.
  • The owner accepts the reference views from above and at eye height at 2×.
  • The budgets of section 15 hold on the GTX, and the owner's flight on the M1 Pro passes.
  • ground-plan has merged into develop, the old code is gone, and the guide docs/content/software/trailview-roads.md describes the ground plan.
  • The owner's production rebake is published.

Risks and open questions

  • Cell build time in WASM on a phone. GP7 measures it on the iPhone. If it is too slow: smaller cells, fewer grid points in slope faces, or cells built farther ahead.
  • Triangles. Slope and terrain faces inside the owned region use the level-18 grid; in a town the owned region can cover a third of a cell. GP7 counts; GP9 measures the frame.
  • The handover at the end of the mesh range. GP10 shows it at the reference junctions; the far stamp gets the table's corner radii only if corners jump. After the 2026-11-07 review: the far look past the mesh is step 5 (TrailView ground plan, step 5: the far look past the mesh, one paint function #3198), and it is sound only once the mesh reaches past the level-18 plateau (step 6, TrailView ground plan, step 6: the mesh range toward 600 m at two levels of detail #3199).
  • Rare class pairs at junctions. The rule tables cover them; GP3's pictures show every junction of the fixture.
  • Steep faces: rock or earth. The owner decides from GP11's pictures.
  • The integration branch drifts from develop. It takes in develop at each wave.
  • The production rebake. GP18 and GP17 (the slide of masts, pylons and stations) change the bake's output; the owner rebakes once after GP19. Until then the old path keeps its look, except the slid masts and pylons after the next fixture or production bake.
  • The shore band's look. TrailView C4: a band of shore along lakes and ponds #3048 (beach, gravel or rock along lakes and ponds) is not in a GP item: GP14 builds the bank faces and slopes, and their material look needs a material input to ground_colour (GP11). A small follow-up after GP14, if the owner wants it.
  • Left-hand traffic (gb, ie, mt, cy) is not handled today (TrailView roads: what remains after epic #2960 #3005). It is a rule value by place in the region rules, never code: the crate and the looks read it for the side of markings, give-way lines, sidewalk corners, lamps and posts (GP3, GP11, GP16, GP17).

Activity

  1. added sub-issues on Nov 3, 2026
  2. 54 remaining items

  3. timohueser commented on Nov 13, 2026

    @timohueser
    OwnerAuthor

    State on 2026-11-13

    Merged into ground-plan (head 4ef6ed4) since the last state: #3322, #3323, #3320 (load: Lucerne about 40 s → 12–15 s), #3321 (stream levels), #3336, #3340 (rim cuts on the global grid), #3367 (GP12.1, closes #3342), #3382 (tunnel tag on shallow tunnels), #3379 (GP12.2a smooth slopes and wall tops, closes #3343), #3385 (house windows to twice the distance), #3384 (short floating tunnels), #3354 (tile-line vertices), #3395 (bridges no longer vanish on a small camera turn).

    Open

    Road heights. The owner's notes on three places led to a diagnosis. The solver changes each limit it overshoots into a heavy equality and does not release it; after round 20 it releases nothing. This gives trenches 5 m below flat ground and frozen crests (A4 at Mosi, the Lucerne link). A third place (primary road at the lake shore) has a different cause: the terrain below the centre line is not the road bed. Branch claude/gp-solver-converge (WIP, no pull request) has a solver without held rows. Its best run on test box B: places at the 5 m limit 462 → 255, tents 47 → 31, jumps 38 → 10, bake step 88.9 s → 106.0 s. The corridor band for the third place, the list of places that get worse, tests and pictures are not done.

    Left, in order: #3396; water; the solver (finish or drop); decks #3344 and #3353; tunnels #3345; #3346, #3347, #3348, the rest of #3349; a next checkpoint build; #3273, #3280, #3355; then #3110.

    Known faults. 28 places are still bad on checkpoint 4 (7 are worse than checkpoint 3, six of them from road heights). The list with pictures is with the owner.

    ground-plan's own clippy job fails on stable Rust 1.100 until one of the open pull requests lands; each carries develop's lint fix.


    Generated by Claude Code

  4. timohueser commented on Nov 13, 2026

    @timohueser
    OwnerAuthor

    State on 2026-11-13, evening

    Merged into ground-plan (head ff484a4) since the morning state:

    Owner decisions of today

    • The census gate measures across the road's width.
    • Bake cost is not critical while it stays far from several times the base; growth over a few percent is reported.
    • Implementation agents are Opus; Fable only for the hardest tasks.

    Open

    Left, in order: #3344, #3353, #3345, #3346, #3347, #3348, the rest of #3349; a next checkpoint build; #3273, #3280, #3355; then #3110.

    Known faults added today (each with its cause in the body of #3215, #3457 or #3449): the outlet and inlet of the long buried culvert; the notch at the box B confluence; a steep bank face at a path's edge by a river (46.82015, 8.3866); the Brunnen shore road on a tall face; a 9 m hairpin cut at Beckenried; sunk portals at Susten, the Axen gallery and the lower Bristenstrasse; an A2 link deck 4.4 m short over the Reuss cycleway in Lucerne; deep footway tunnels in Lucerne.

    Checks left out today: debug heights --gpu-check and model-probe.mjs after the water merge (the permission check refused the run); a box B rebake for the water pair.


    Generated by Claude Code

  5. timohueser commented on Nov 15, 2026

    @timohueser
    OwnerAuthor

    2026-11-15: ground-plan is merged into develop (#3491, with the owner's go).

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions