Repository navigation
Description
Status: approved
Part of #3651.
TL;DR
Goal: With ground=plan, the viewer draws the parts of P3 in place of today's tunnels, chain by chain for the kinds that the parts crate builds: their meshes, the road up to an opening that lies inside its tunnel way, the terrain's box rule with their boxes, a hole in the ground plan's mesh only where the bake found ground inside the part, no plant and no object in a part, the walking camera on their floors, and the daylight of each vertex. Without the switch, nothing changes.
Problem: On the new roads a tunnel opening comes from general ground rules, and 266 of 1,014 test entrances fail (epic).
Decision: Which kinds are built is decided in one place, BUILT of obc-trailview-parts. The part fills its boxes: one box per straight piece of the tube, at the middle of its wall, with a round roof for a round tube; the outer shell runs to the end of the last box. The ground plan opens the stretch to each built opening with graph::open (P1). No ground of the ground plan draws in a box: its triangles and step slots near a box draw last, with the pipelines that already discard, and a pixel of them whose drawn point lies in a box drops, as a pixel of the terrain does; the ground over the collar stays. This narrows the rejection "no discard in the piece shader" to that tail near the boxes, and it waits for the owner's word. A change of BUILT needs a features bake. One structure mesh holds both apps: today's tunnels of built chains in the range that only today's app draws (offPlan), the parts in a new first range that only the ground plan draws (planOnly); so the stamp layer serves both apps and no draw is added. A chain of a kind that is not built yet keeps today's tunnel, boxes and floors on the new roads, with its opening at the end of the OSM way. Plants keep off a footprint through the stamp's taken ground, with no new buffer or binding. Two pull requests: (a) the part and the bake, (b) the drawing.
Rejected: The stamp layer with the parts only: today's app reads the owner nodes' meshes from the same layer. A layer per app: two bakes and two sets of bytes. A face with no mesh over the whole footprint (the first design of step 5): it also removes the ground over the part, so a slot opens at the collar's end (by the bake's cover rule the hill lies at least cover_m over the shell there), at the collar's sides and behind the head wall. A face over the whole box: behind the collar the hill over the tube must draw. A discard on every pixel of the pieces (the prototype's way): it turns off the hidden-surface removal of the phone's GPU on the foreground. A cut that the bake predicts and the mesh leaves open (rounds 1 to 4 of (b)): the stamps, the drawn pages and the device's own faces and triangles change the drawn ground, so the prediction cannot be exact (box B: 235 triangles past the band at 46 of 143 built ends). One box per end to the outside of the shell (P3's box): a round shell cannot fill a rectangle, and a straight box leaves a bend. A skirt of walls from the shell up to the ground: a walled pit round each collar. A box test in each instance producer: a new storage binding passes the default limit of 8 in the forest's compute stage, and it costs a loop per candidate.
Systems: trailview
Contracts: specs/trailview-features.md (Tunnel parts: no tag cut, the approach of a built end; a features revision), specs/trailview-tiles.md (Stamps: the keys planOnly and pointsOff)
Size: L (the parts crate, the feature bake, the viewer, the ground plan crate and its bridge, two contract changes, the phone)
Facts
- Both apps read an owner node's structure meshes from the stamp layer; the whole nodes of zooms 9 to 12 only with the plan (
terrain/stamps.tsfeatures). The bake asks the worker withplan: true(stamp-bake.ts). - A
StructureMeshkeeps its indices in ranges: the faces of both apps,decks, thenoffPlan;structures.tsdraws each range with onedrawIndexed.MeshBuilder.mesh()writes words 0 and 1 asi32, 3 and 4 asu32, the others asf32. terrain.tspacks at mostMAX_HOLES(32) boxes into the storage bufferholes, one per middle, from the nodes with portals, and draws those nodes withterrain with holes;hole_distanceruns per vertex, and per fragment only where the vertex found a box near.structures.wgslreads the same buffer; itsdaylightloops over all boxes. A box has three free lanes in its thirdvec4f.- Where the ground plan's mesh draws, the terrain sinks under it (
plan_sunk). The mesh draws the sharp faces, one ring of ground about them and a strip of fixed fans at the edge of its region (mesh/region.rs,mesh/strip.rs). - P3's box (
arch.rsportal_box): one per end, a rectangle to the outside of the shell, from the front of the head wall to max(the level-17 depth,collar+ 2 m); the shell runs tocollar. On test box B (bake of TrailView parts P3: a crate builds the arch and the tube, and the stamp code runs it as WASM #3754) the box runs past the collar by 5.2 m median, and the axis leaves the box's line by more than 0.5 m at 26 of 150 built arch ends. - P1's measure opens the stretches of all openings, built or not.
kept_offofterrain/features.wgsl, which the forest, plants, rows and dressing read, keeps them off ground that the stamp marksTAKEN; an area of kindAREAinstamp-core.wgslmarks it. The stored points (instances/points.wgsl) do not read it. The forest's compute stage already uses 8 storage buffers, andrequestDeviceasks for no higher limit.
Plan
Pull request (a): the part and the bake
It changes no pixel of either app: nothing draws the parts or reads cut before (b).
- The part fills its boxes (
obc-trailview-parts). Over the box's depth, the axis with its floor is simplified atshell_m/ 2; each straight piece of one height gets a box, which reaches past its joint so that two boxes cover the room through a bend. A box lies at the middle of the wall: half-widthhalf+shell_m/ 2, roofheight+shell_m/ 2 over the floor, and for a round section a round roof from the spring up. The box words get a 10th word, the spring height (today's boxes: the roof). The opening, from the front of the head wall to the frame line, has a box of its own: its outline grown to the middle of the wall round it. The depth past the opening follows today's rule past the start of the cover: max(portal_cellscells,collar+ 1 m) + a level-17 cell's diagonal + 1 m. The collar's shell runs to the end of the last box and ends with an end face. A test holds the invariant: each box holds the room, and lies inside the outer shell. - The bake opens the ends that the device opens. The numbers of the openings (the second measure of P1) read the ground with the stretches open only to the openings of chains whose ends are all in
BUILT. - The cut (
obc-trailview-features, after the floor pass and the ladder). For each end of a built chain, the cut is where the ground of the ground plan, with the ends ofBUILTopen, lies inside a box of the part: sampled each 0.5 m over the boxes' footprints, with the signed depth inside the boxes, and contoured between the samples. The tagcutof thetunnel-endholds its rings in the frame of the opening (metres in alongheading, metres to the left). A change ofBUILTor of a part's sizes needs a features bake. Features revision 30; the fixture tiles are baked again. - Contract.
specs/trailview-features.md, Tunnel parts: the tagcutand its rule.
Pull request (b): the drawing
- Mesh ranges.
mesh.ts:MeshBuilder.planOnly(make)builds into a first list;MeshBuilder.append(words: Uint32Array, indices: Uint32Array)adds a mesh of the bridge: words 0 and 1 asi32, 3 and 4 asu32, 2, 5 and 6 as thef32of their bits, each index plus the count of vertices before;StructureMesh.planOnly?: number.structures.ts: without the plan, the first draw starts atfirst + planOnlyand drawslength − planOnly; with the plan nothing changes. - Node.
bins.tskeeps the tagpartsof a tunnel way asLine.parts; a line is built when the bridge'sbuilt(line.parts)says so (P3), an exact mark that P1 writes.structures/node.ts:tunnels(mesh, lines, owns, keep)computestwinsover all lines as now and builds the lines thatkeeptakes; with the plan,structureMeshescalls it for the lines that are not built and, infar.mesh.offPlan, for the built ones, so today's app gets the faces it gets now; then, withinput = partInput(list, tile, node)(P3),far.mesh.planOnly(() => far.mesh.append(..partMeshes(input, node))). Without the plan the worker does not start the bridge and builds today's meshes. Kind points that lie in a footprint (footprintsof the bridge) go last inpoints, andNodeMeshes.pointsOffcounts them.portalBoxes(list, tile, node, plan)andfloorsOf(.., plan): without the plan as today; with it, today's boxes and floors of the lines that are not built, the bridges' floors, andpartVolumes.stamp-worker.tspassesplan. - Terrain.
portal-box.wgslreads the spring word: above it a box's roof is round. Today's boxes write the spring at the roof and keep their pixels. With the plan only:MAX_HOLES64, which holds the pieces of a part's boxes, nearest the anchor first, each box once. Cost: per vertex of a node with boxes, at most 64box_pointtests (about 12 operations each, a few more for a round roof); per fragment the same, only within reach of a box. It stays bounded by the count and by the nodes that have boxes; the gates and the phone run measure it. - Daylight.
structures.wgsl, aBOREface:if (in.daylight < 0.0)it runsdaylight(in.u, in.altitude), else it readsin.daylight. Today's tunnels write −1 (P3) and keep the loop; a part's fragment reads one value and runs no loop. In a tight bend the outer wall can be darker than the floor beside it (P3); the pictures decide whether that needs a change. - Ground plan.
obc-ground-plandepends onobc-trailview-parts.cell::cell_graphbuilds withgraph::build_openand theOpenEnds of thetunnel-endfeatures of itsCellInputwhose chains are built (End::from_tags,built): the road reaches each built opening as a ground way, with its cut and fill, and joins the junction; at an end that is not built the tunnel way stays as ondevelop. The mesh does not change. In the viewer, when a cell's stamps arrive, its triangles and step slots whose plan meets a box of its level-18 nodes, grown by a level-18 grid step, move to the end of their groups (splitTails); they draw with the fade's pipelines, which discard, as instance 1; the corridors' fragment drops a pixel of them whose drawn point lies in a box that the cell meets (corridor_dropped; the cell keeps those boxes in a small buffer). All other pieces draw with no discard. NoSurface::Part, no rank, no change of the far block.wasm_size_guard.pyrecords the plan bridge's new size.
Why: the boxes hold the room and lie at the middle of the part's wall. Ground that stays is outside the part, in the outer half of its wall, or over it; ground that goes lies under it. The boxes' margin to the faces of the part as it draws them, 0.11 m (the spec), is the tolerance between the bake's ground and the drawn ground; P7 (TrailView parts P7: the bake checks each placed part #3684) checks it. - Plants and objects. With the plan,
bins.tsgetsShapes.taken: the footprint rings of the built parts (the bridge'sfootprints), packed after the buildings with the kindAREA, so the stamp marks that groundTAKENandkept_offkeeps trees, plants and dressing off it. With the plan only, the code that joins the nodes' points forwriteofinstances/points.tsleaves out the lastpointsOffpoints of each node; without it every point stays. Two edges stay, as for buildings today: a node whose stamp passesSTAMP_WORDSdrops all its areas, and nodes coarser than levelNEAR(16) mark noTAKEN. There a plant can stand in an opening; it shows only in a dense village node or from far off, where the opening is a few pixels, so it is acceptable. - Stamps of the tunnel lines. With the plan, a built line stamps no cover from each opening of its chain to the start of the cover of its part (
collar+ 1 m, the start that step 1's box depth follows), so coarse terrain does not bury the head wall and the collar. The stretch follows the chain into the next way. Word 12 of a line's record (free on a line) holds it per end. - Contract.
specs/trailview-tiles.md, Stamps: the keysplanOnlyandpointsOff; the parts draw only with the ground plan. - Tests. (a): the box invariant of step 1; the cut of a made end (ground through the collar: the cut lies inside the boxes' footprint and holds the opening; a hill over the crown: no cut there). (b):
structures.test.ts: without the plan the draw leaves out exactlyplanOnly; the faces of today's app are equal with and without the split oftunnels.obc-ground-plan: in a cell with a built arch end at a moved opening, the road reaches the opening as a ground way; the cell's other corners are as ondevelop; with an end of a kind that is not built, the cell is as ondevelop.pieces.test.ts: the triangles and slots whose plan meets a grown box move to the tail, in their order.
Files
- (a):
host/obc-trailview-parts/src/{lib,arch,tube,footprint,tests}.rs,host/obc-trailview-features/src/parts/{mod,measure,tests}.rsand a module for the cut,host/obc-data-steps/src/planner.rs(the revision),specs/trailview-features.md,builder/web/tests/browser/trailview/fixture/features/: change. - (b):
builder/web/src/lib/trailview/structures/{mesh,node,parts,structures}.ts,structures.wgsl,terrain/{stamp-worker,terrain,bins}.ts,terrain/{portal-box,stamp-core}.wgsl,instances/points.tsor its caller: change.host/obc-ground-plan/{Cargo.toml,src/cell.rs,src/mesh/}: change.builder/wasm/wasm_size_guard.py,tools/testing/suites.toml(obc-ground-plantriggered byparts.json),specs/trailview-tiles.md: change.
Deviation from the epic
- The epic lists
terrain/portal-box.wgslas changed: it gets the round roof of a box. - The epic's P4 reads the portal lines of
levels; here the ground plan reads the placement (graph::openwith the record'swayandshift), and only for the chains whose kinds are inBUILT. - The ground plan has no face for a part: its pixels in a part's boxes drop (deviation 2 of (b)); the epic's "face that the part owns, where it makes no ground" covers only the ground that would lie inside the part.
- P5 and P6 each need a features bake: the open ends depend on
BUILT. - P3's boxes and shell change here (step 1), not in TrailView parts P3: a crate builds the arch and the tube, and the stamp code runs it as WASM #3754.
- Found in the code: today's app reads the structure meshes of the owner nodes from the stamp layer, which the bake makes with the plan. The index ranges of step 5 keep both apps on one layer.
Deviation in the build
Pull request (a) is #3761 (steps 1 to 4), after fix round 2. It deviates from the plan in these points:
- A box has 12 words, not 10. After the spring come the slopes of its start and its end, in the last two free lanes of the third
vec4f. Its ends lie in the planes of the tube's rings, so two boxes meet with no gap and no overlap in a bend; no box reaches past its joint. Today's boxes have slopes 0. Step 7 reads them too. - A box's heights rise between its two end planes, as the shell's do between its rings: a point rises by its share of the way from the start plane to the end plane times
rise · depth. So each end is level across in its ring's plane, at any bend and grade. The viewer's box test (step 7) must use the same rising box. The pieces are simplified at a quarter of the wall (0.125 m), where a vertex between lies off the piece's line across or off the box's rising line in height, on the axis or at a side of the room, and split where the section changes. The boxes lie at least 0.11 m inside the faces of the part as it draws them (bends up to 60° on grades up to 25 % in the crate's test; test box B); step 9's tolerance is that figure, not half the wall. - Where the parts of a tube's two ends would meet, both shells end at the vertex nearest the middle: the taller closes the step, and the walls have a corner at the other's foot. On box B this is 21 of 143 built ends.
- The head wall and the shell go down to the end's
foot, orfoot_munder the lowest floor of the chords that the part runs over, the lower. - The cover stop (step 11) is in pull request (b): alone it takes the hill off today's bores of built chains.
- The rings of
cutare simple and apart by construction: a point is inside only deeper than 1 µm; each crossing lies at whole centimetres at least 1 cm from the grid points; the thinning keeps them simple; a ring of ground only in the wall (no deeper than 0.11 m in the sides and the roof) goes. The metriccut_invalid_ringsis 0, and a non-zero count fails the bake. A hole goes only with the ring nearest round it. A point lies in the cut where an odd number of rings hold it. Ground of no known height is outside. The bake builds the ends and the chords with the tile encoder's rounding. - The numbers read the stretches of the chains that are built by their final kinds: the measure and the refit repeat while that set changes (at most one more round than the count of kinds).
- TrailView parts: the room folds in a tight bend, and a head wall under a low deck is lower than its opening #3762 holds two faults of P3's geometry that P4 does not repair: the room folds where a chord turns tighter than its half-width, and under a low deck the head wall is lower than the opening's box.
Pull request (b) is #3763 (steps 5 to 13). It deviates from the plan in these points:
obc-trailview-partsgetsbuilt_ends: the ground plan reads which ends are built with the crate's own rule. The ground plan opens a built opening where the end vertex of its way lies in the cell grown by its margin, as the bake's measure does; a pair's second opening opens too.- Round 6 (design R,
DESIGN-CUT.md; waits for the owner's word): the cut goes. Four rounds tried to make the bake's cut match the drawn ground and failed: the drawn ground in a part's room has three causes that only the device knows (a triangle sags between its corners, the GPU stamps lower the ground, the device's faces differ from the bake's). So the bake writes no tagscutandwalls, and the mesh gets no hole, no ring constraints, no snap rounding and no walls (features revision 34). The ground's own pixels test themselves against the boxes, as the terrain's do (step 9). This narrows the earlier rule "no discard in the piece shader" to the tail near the boxes. The tail uses the boxes of built parts and of today's portals alike, per cell, and, as the terrain's holes, drops nothing in a frame where the structure of one of its boxes does not draw. A cell splits once its stamps come (one cell a frame), and again when they come again. The fixture census of the mesh builds the cells as the device does. - Step 11: a built tunnel line stamps nothing, not only no cover, from the way end of each opening to the start of its part's cover (
shift+collar+ 1 m), along the chain. Its road into its portal dug the hill in the part, where the bake reads no stamp. Word 12 holds, per segment, the decimetres of that stretch from its start and from its end. - Step 10: the parts' rings take the ground as the decks' rings do (an
AREAitem each with the plan), not packed after the buildings. - The plan bridge grows by about 36 kB gzipped (+4.5 %).
- Round 4 (decision: the approach as wide as the opening). A way that ends at a built opening widens its shoulder, at the road's height, and the layers out of it to the opening's jamb lines, and back to its own width over
approach_m(parts.jsondesign, 10 m: in box B the opening is wider than its road's core at 84 of 143 built ends, by 0.25 m at the median and 3.1 m at most), or over the way where it is shorter. One op on the way line's offsets inobc-ground-plan(faces/approach.rs), after the tapers at joints; the graph carries the openings (WayGraph::mouths). Features revision 33. - Pictures of round 6 (box B, features revision 34, in TrailView parts P4 (b): with the new roads, the viewer draws the tunnel parts #3763): the openings of road-mouth, bend (mouth and from the road), lowered and the others are clear; round 4's dark triangles of steep hill are gone, and so is the dark tip at road-mouth (TrailView parts P7: the bake checks each placed part #3684). The openings of the unbuilt pair now show today's bores (develop's new roads fill them with ground), because the tail takes today's portals' boxes too. No view is worse. In 24 views no pixel of the plain draw lies in a box (a measuring build).
Done when
- (a):
obc test -p obc-trailview-parts,-p obc-trailview-features,-p obc-data-steps; clippy of each and of the parts bridge forwasm32-unknown-unknown;cargo fmt --all;bash builder/build-wasm-bridges.sh, the size guard of the parts module; the fixture policy check; a box B bake with the counts of the cut (ends, rings, points) and its time against TrailView parts P3: a crate builds the arch and the tube, and the stamp code runs it as WASM #3754's bake. - (b):
obc test -p obc-ground-plan; clippy of it and of the plan bridge forwasm32-unknown-unknown;bash builder/ground-plan-wasm/check-bytes.sh; the size guard of both modules; inbuilder/webthe test files of the changed modules,npm run check,npm run check:wgsl. - (b): the epic's gates against
develop, both withnode builder/web/tests/browser/trailview/flight.mjs --gpu --query ground=planoverwalkandvalley-drive: no new pass and no new draw per node; the frame time not up by more than the noise of the measure; the time to the first proper render of the start view not up by more than that noise (the stamp workers now load a WASM); the bytes of the stamp layer of the fixture (over 20 % more needs the owner's word); the structure pool's use. The same flights without--queryshow that today's app does not change. - (b): labelled pictures, today's app | new roads on
develop| new roads with the parts, at the arch entrances of the prototype's sheets: from the road, at the mouth, from inside, from above, and one from far off, where the terrain draws coarser than level 17. The owner approves them before the merge. - (b): one run of today's app on the owner's iPhone 13 before the merge:
structures.wgslandportal-box.wgslchange for today's app too (TrailView on the iPhone: the terrain draws broken, the new roads do not start, and the first picture takes long #3656, step 2). The new roads do not start there yet (TrailView on the iPhone: the terrain draws broken, the new roads do not start, and the first picture takes long #3656).
Depends on #3680. Requirements: none
Generated by Claude Code
Activity
timohueser commentedon Nov 19, 2026
P1 (#3678): what changed for the readers of its records
The build of P1 deviates from its design in these points. The full list is under "Deviation in the build" in #3678.
tunnel. A chain goes on through each vertex where the ends of two such ways meet. An end opens only where no other such way has a vertex there. At a fork or a cross passage, the end has no part, and thetunnel-tuberecords run to that end vertex.tunnelin the map that the bake lays on the ground) belong to no chain. They have no records and draw on the ground, as on develop.endsandparts. The end behind the record's first vertex comes first, in the rising metres of its way.nonenames an end with no part of its own: same tube, under a building only, a vertex of unknown height, or a fork.leftandrightare at leastcoping_m. Thecollarof aboxis at most half the chain. Thecollarof apairis the larger of its two tubes. In a pair, the nearer opening moves onto the frame line of the other, so itsshift(ormate_shift) includes that move.pairrecords have tubes that overlap. Their axes are nearer than both outer half-widths, for example motorway carriageways 9 m to 13 m apart with ahalfof 6.6 m, or double tracks 3.6 m to 4 m apart. Rung 2 as designed (halfof the wider +same_tube_gap_m) does not take them into one tube. The builder of a pair must cut the two tubes where they meet, or rung 2 must change. The report to the owner gives the options.graph::openmatches the end vertex on the first or last vertex of a part. A cell whose grown square ends withinshiftof the vertex does not see it (the trim ofgraph::parts), so the stretch stays a tunnel there. This is more than 170 m from the square of that cell.Generated by Claude Code
timohueser commentedon Nov 20, 2026
P3 (#3680, #3754): what P4 gets from the build
partInput(list, tile, node)gives the JSON input: the node's square and the tile's part records in world units of the viewer (2^30 per side), each chord with thecodeandmarkedofclassPaint(bins.ts).partMeshes(input)takes no node: the input holds its square. It gives aStructureMeshwith 7-word vertices or null.partVolumes(input)gives{ boxes, floors }. The bridge also hasbuilt(parts)andfootprints(input);parts.tsdoes not wrap them yet, so P4 adds the wrappers (each starts the bridge first, aspartMeshesdoes).BUILT. An endnoneis not built.meshesandvolumesgive nothing for a chain that is not built.lift_munder the floor.parts.tsreaches the stamp bundle,stampBundlereplaces the inlined WASM by the hash of its sources and stops whenstructures/pkg/sources.sha256is another hash: build the bridges again after each change of the crate.stamp-sources.test.tsalready acceptsstructures/pkg/, and the CI jobswebandweb-browseralready download its package.initSyncper worker. The gate on the first render must hold that.Generated by Claude Code
timohueser commentedon Nov 20, 2026
P3 fix round 1 (#3754): what changed for P4
recess_mout of the frame line), as its footprint does. Its depth counts from there.lift_munder the floor, from the front of the head wall to the frame line, across the hole. The road of the ground plan can lie over it without z-fighting. At an opening, the front of the tube's floor goes down to that sill.daylight_min. A point behind it, above it or under it is dark.vertex_gap_m(1 m) apart, so a chord's direction holds in tile units. The features revision is 29.End::from_tagsandChord::from_tagstake the rules. They fail on alookthat the rules do not have and on aclassin no group.alongis required.parts.tsis in the stamp bundle, the stamp step ofobc datamust build the bridges first. OtherwisestampBundlestops with "is missing". That is the right failure, but plan the build order.Generated by Claude Code
timohueser commentedon Nov 20, 2026
P3 fix round 4 (#3754): a note on daylight for P4
The daylight band of an opening is measured from its heading line. In a tight bend, the outer wall lies off that line. One example: 7 m off the line, 12 m in, the wall gets no light, while the floor near it gets about 0.35. P4 must handle this when the shader reads the word: for example, take the light along the walk, or accept a darker outer wall in tight bends.
Generated by Claude Code
timohueser commentedon Nov 21, 2026
Done in #3761 and #3763.