Repository navigation
Description
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=planin 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 withshoot.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_placeslides 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_heightmixes 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_heightreturns the exact drawn triangle with snap and morph (terrain/drawn-mesh.wgsl:99);plain_heightandstand_heightskip 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_colourreads 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),
stepsis 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 ofterrain/terrain.wgsl:32-49discard 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:226shades 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.tsbuilds rails, sleepers and treads fromroads/stations.tsandroads/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 instructures/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); mappedguard_railandretaining_wallcome fromterrain/bins.ts:312; lamps fromroads/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
walkfield 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).sidemarks 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_overlayis inCargo.lock(throughgeo, version 4, withi32integer points);spadeis 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 thinwasm-bindgenbridge, built bybuilder/build-wasm-bridges.shwith a size guard likebuilder/wasm/wasm_size_guard.py. The crate itself has no browser code. - Dependencies:
i_overlayfor integer polygon booleans and offsets;spadefor the constrained Delaunay triangulation and its refinement;libmfor every transcendental function, so native and WASM builds give the same bytes;faeronly 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 ini32relative to its origin, which is exact, and insidei_overlay's range. Metric lengths come from the Mercator scale at each point, inf64throughlibm. - 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.jsonand.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.jsongains one cross-section per class: the carriageway's half-width and howwidthandlanestags 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 interrain/bins.ts,roads/section.tsand two tables of the bake, with different numbers.- A new
plan.jsonholds 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 ofroads.jsonstays a class. A newfinishes.jsonholds the values per surface finish (for example the cap of a footway's width). waterways.jsongains the cross-section of flowing water (bed depth by width, bank slope, bank width, freeboard) and the crossing rules; a newshores.jsonholds 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
sideleaves unmarked. Wheresidemarks nothing (paths, junctions of two classes thatsidedoes 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
decktag) 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 wherewalksays 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:
- 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.
- 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.
- 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.
- 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 ismin(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. - 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.
- 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.
- 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_heightandstand_height, so every reader of the facts' list,vegetation/forest.wgslandvegetation/rows.wgslincluded, 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.wgslandroads/track-looks.wgslwith 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
deckdepth 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, asstructures/bridges.tsdoes 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_crossingnode (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.jsonby the way's class and the water's width:- a
bridgetag: 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
fordtag or a shared vertex): the way's surface is the bed there, and the water surface runs over it; on a path,ford=stepping_stonesgives 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.
- a
- 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_railwins; - 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_wallmakes a wall where the plan has none.
- 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
- 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; mappedhighway=street_lampnodes 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).
- street lamps along the sidewalk's back edge (else the verge), in towns or on ways with
- 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.
- The faces form a planar partition of the owned region: no overlap, no gap, valid polygons, no face thinner than the minimum width.
- Two neighbouring cells hold the same vertices, heights and attributes on their shared border.
- 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.
- 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.
- 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.
- No point object stands in a carriageway, junction area, rail bed or water face (pipes and stepping stones exempt from the water test).
- A native build and the WASM build give the same bytes for every fixture cell (GP5 adds this check with the WASM build).
- 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-planstarts from develop. GP0 or GP1, whichever starts first, creates it (the owner approved this flow). - Each sub-issue has its own branch from
ground-planand one pull request intoground-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-plantakes 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-planinto 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; inbuilder/webfor viewer changes:npx vitest run src/lib/trailview,npm run check,npm run check:wgsl. - Each pull request carries
Mode: change #<sub-issue>andRequirements: noneunless 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 |
- TrailView ground plan GP0: the baseline of develop, and the top-down views #3097 GP0: Baseline: pictures and costs of develop, and the views from above (
road-views-top.json) whose centres are the places of the debug tool. (S) - TrailView ground plan GP1: the crate's base: frame, tile decoder, terrain heights, cross-section table, debug tool #3111 GP1: The crate's base: the crate, the integer frame and
libm, the Rust tile decoder with the join of features across tiles, the terrain heights, the cross-section table and its reader, the debug tool. Createsground-planif GP0 has not. (M) - TrailView ground plan GP2: the way graph: curves, junctions, hosts, snapped ends, levels and crossings #3098 GP2: The way graph: curves at global parameters, the split at cell lines, junctions with their hosts, overlapping junctions, snapped ends, levels, crossings and their types, cleaning. (M) Depends on GP1.
- TrailView ground plan GP3: faces of ways and junctions: carriageways, tight bends, junction areas, mouths, rail beds #3112 GP3: Faces of ways and junctions: carriageways, tight bends, junction areas, corner fills, mouths, rail beds, platforms and crossing faces, slope bands; the planar map, its overlay, the minimum width, cell borders. (L) Depends on GP2.
- TrailView ground plan GP4: faces of sidewalks: kerbs, driveways, zebras, corners, ends and buildings #3099 GP4: Faces of sidewalks: kerbs, driveways, zebras, corners, ends, buildings. (L) Depends on GP3; uses GP18's fixture when it lands.
- TrailView ground plan GP5: the WASM bridge, the plan worker, the timing page and the debug draw of the faces #3100 GP5: The WASM bridge, the plan worker, the timing page and a debug draw of the faces in the viewer, behind the switch. (M) Depends on GP3.
- TrailView ground plan GP6: heights: the owner, blend, kerb offset, slope, wall and terrain rules #3113 GP6: Heights: the owner, blend, kerb offset, slope, wall and terrain rules, unrelated owners, the owned region. (L) Depends on GP4.
- TrailView ground plan GP7: the mesh, its strip, pieces and floors, and the cell build times #3101 GP7: Mesh: the triangulation, locked borders, vertical faces, the strip, pieces with their index ranges, floors against the drawn mesh, the vertex and its normal; build times native, in Chrome and on the iPhone; triangle counts. (L) Depends on GP5, GP6.
- TrailView ground plan GP8: the far stamp, one stamp function in every page on the new path, no snap #3102 GP8: The far stamp: one stamp function in every page on the new path (core plane, slopes from the table, paint), no snap. (M) Depends on GP5. Changed: the far look of the one road model replaced the far stamp; its look past the mesh is step 5 (TrailView ground plan, step 5: the far look past the mesh, one paint function #3198).
- TrailView ground plan GP9: ownership in the viewer: floors, the strip, pieces, draw order, range, crack count #3103 GP9: Ownership in the viewer: floors in the terrain, pieces with the strip and its morph, draw order, casters, pools, the range in the LOD metric, level 17 as the finest level, the fallback below it; the GPU crack count. (L) Depends on GP7, GP8. Changed: the level-17 mode and the range to 600 m were not built; step 3 (TrailView ground plan, step 3: the mesh on level-17 terrain nodes (design first) #3196) and step 6 (TrailView ground plan, step 6: the mesh range toward 600 m at two levels of detail #3199) take them.
- TrailView ground plan GP10: readers on the plan layer, plants off water, the fade and the handover #3114 GP10: Readers: the plan layer under
drawn_height,plain_heightandstand_heightand the mask reads, exactly where pieces draw; plants off water; the fade at the end of the range and the handover to the far stamp. (L) Depends on GP9. Changed: the handover is to the far look, at about 195 m until step 6 (TrailView ground plan, step 6: the mesh range toward 600 m at two levels of detail #3199); its look is step 5's one paint function (TrailView ground plan, step 5: the far look past the mesh, one paint function #3198). - TrailView ground plan GP11: looks on the mesh: way faces, ground faces, markings, kerbs, walls and steep faces #3104 GP11: Looks on the mesh: way faces with normals, ground faces through
ground_colourwith the normal and facet as inputs, markings in junctions, kerbs, walls, steep faces. (L) Depends on GP9. - TrailView ground plan GP12: bridges, tunnels, underpasses and galleries: decks, bores and roofs with the ladder (the contract of the crossing block) #3105 GP12: Bridges, tunnels and galleries: deck plans, parapets, slab, piers, abutments, the handover to far bridges, portals. (L) Depends on GP10, GP11.
- TrailView ground plan GP13: railways and steps: rails, sleepers, rack and cable, platforms, level crossings with gates and lights, step treads #3106 GP13: Railways and steps: rails, sleepers, rack and cables along the curve, platforms, level crossings with gates and lights, step treads. (M) Depends on GP12.
- 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 GP14: Water: beds, banks and surfaces of streams, rivers, canals, lakes, ponds, river areas and the sea shore. (L) Depends on GP10, GP11.
- TrailView ground plan GP15: water crossings: culverts, fords, pipes in stones, stepping stones, footbridges #3108 GP15: Water crossings: culverts with headwalls and pipes, fords, pipes in stones, stepping stones, footbridges. (M) Depends on GP12, GP14, GP18.
- TrailView ground plan GP16: edge features: guardrails, delineator posts, wall caps, railings, mapped barriers #3115 GP16: Edge features: guardrails, delineator posts, wall caps and railings, mapped barriers. (M) Depends on GP12, GP14.
- TrailView ground plan GP17: point objects: street lamps, OSM point kinds, catenary masts, aerialway pylons and stations #3116 GP17: Point objects: lamps, OSM point kinds, catenary masts, aerialway pylons. (M) Depends on GP13, GP14.
- TrailView ground plan GP18: the bake on the cross-section table, cover over untagged culverts, kinds for placement, the fixture rebake #3109 GP18: Bake: the bake reads the cross-section table, lifts ways over untagged culvert crossings, keeps the kinds and tags that placement needs; the fixture rebake. (M) Depends on GP1.
- TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110 GP19: The switch becomes the default; the old code goes; docs; budgets on the GTX and the M1 Pro; merge into develop. (L) Depends on all.
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:
- Stamp worker and small bake:
- 1a TrailView ground plan, step 1a: the stamp memo per tile, the z8 cache, no unread tile work on the plan path #3192: the per-tile stamp memo, the z8
features()cache, no unread tile work on the plan path. (S) - 1b TrailView ground plan, step 1b: corners take the water and structure ground from the cell #3193: corners take the water and structure ground from the cell, so pieces stop waiting for level-18 stamps. (M)
- 1c TrailView ground plan, step 1c: bake the coarse stamps (L9–L12) and the structure meshes #3194: bake the coarse stamps (L9–L12) and the structure meshes, about 10 MB a region. (M)
- 1a TrailView ground plan, step 1a: the stamp memo per tile, the z8 cache, no unread tile work on the plan path #3192: the per-tile stamp memo, the z8
- 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) - 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)
- 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)
- 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.
- 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)
- 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-planhas merged into develop, the old code is gone, and the guidedocs/content/software/trailview-roads.mddescribes 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
54 remaining items
timohueser commentedon Nov 13, 2026
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
timohueser commentedon Nov 13, 2026
State on 2026-11-13, evening
Merged into
ground-plan(head ff484a4) since the morning state:Owner decisions of today
Open
claude/gp12-3a-deck-sheets.ground-plan.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-checkandmodel-probe.mjsafter the water merge (the permission check refused the run); a box B rebake for the water pair.Generated by Claude Code
timohueser commentedon Nov 15, 2026
2026-11-15:
ground-planis merged intodevelop(#3491, with the owner's go).develop. The review flow does not change.ground-plangets no more pull requests.Generated by Claude Code