Repository navigation
Description
Status: approved
Part of #3096. One pull request into ground-plan (a views file); the measurements go into a comment on the epic.
Depends on: none
TL;DR
Goal: Every later sub-issue compares its pictures and numbers with one fixed record of develop, and the owner's places can be shot from above with one command.
Problem: The epic gates the frame cost on "develop's corridors, band and stamp" and asks each pull request for pictures from above and at eye height. No record of develop's numbers exists for this epic, and road-views.json has eye views but few views from above (forecourt-top, the *-above views at pitch −42).
Decision: Add road-views-top.json with one view <place>-top from above (pitch −89) per listed place; shoot every view of road-views.json and road-views-top.json on develop at 1920 × 960 with the GPU; fly the walk and drive flights with the clock held; run the census and the torn-face gate; record the cost and size figures in one comment on the epic.
Rejected: Shots at the default 1280 × 800: the road views need 1920 × 960 (README.md of TrailView, "Shots and flights").
Systems: trailview
Contracts: none
Size: S (two views files, measurements only)
Facts
shoot.mjstakes--views FILE,--width,--height,--gpuand writes one PNG per view afterwaitForIdle()(builder/web/tests/browser/trailview/shoot.mjs:1-60).- A view is
{name, view}, whereviewis a query string withlat,lon,heading,pitch(−89 to 89), andeye(metres over the ground, walk) oralt(metres over sea level, fly) (builder/web/src/lib/trailview/view.ts:21-73). road-views.jsonhas 121 views, the owner's views v01 to v17 among them;forecourt-topuses pitch −80 andeye=28, theconn-*-aboveviews pitch −42 andeye=20.flight.mjs --gpuprints the GPU time per pass, the CPU selection time, and the nodes, triangles and pages of each flight offlights.json; only walk and drive count (README.md, "Shots and flights").- The census:
npx vite-node scripts/road-census.ts .artifacts/census(CPU counts) andflock /tmp/trailview-gpu.lock node trailview/census.mjs --gpu ../../.artifacts/census --ground DIR(GPU counts) (README.md). The torn-face gate counts folds, slivers and twists of the corridor meshes (TrailView G5: a check that fails on torn faces #3085).
Design
The views from above. road-views-top.json holds, for each place below, one view named <place>-top: lat and lon at the centre of the place (the point that the eye view looks at, not the eye), heading=0, pitch=-89, eye=60 (139 m wide and 69 m high at 1920 × 960 over flat ground: the vertical field of view is 60°), date, time and weather as in road-views.json. A place name is the name of its view in road-views.json without the suffix -eye or -above; the top view is the place name plus -top, and no other spelling is used (v06-road-path-broken-top, not v06-top). The places:
v01-stairs,v02-stream-path-shrubs,v03-good-path,v04-wall-road-junction,v05-slope-artifact,v06-road-path-broken,v07-good-junction,v08-rough-connection,v09-sidewalk-patches,v10-signpost-bench,v11-two-bad-junctions,v12-good-town-junctions,v13-culverts,v14-paths-not-joined,v15-stuff-on-road,v16-road-rail,v17-sharp-corners.i07-hairpin,d-hairpin,hp,t-tertiary,x-tertiary,junction0,j-tt-a,b45-bridge-junction,b315-bridge-junction,d-bridge,zebra-tagged,crossing-close,stream-culvert-main-road,stream-culvert-track,mouth-stream,stream-parallel-road,lake-shore,rail-close,steps-town.conn-own-a,conn-own-b,conn-own-c,conn-path-off-road,conn-track-off-road,conn-path-off-walk,conn-road-into-path,conn-walk-into-path,conn-road-into-track,conn-walk-into-track,conn-path-off-track,conn-footway-hump,conn-steep-ramp,conn-parallel-way.
road-views.json already has i07-hairpin-top (pitch −89, alt=1035); move it into road-views-top.json with the values above, so that each -top name is in one file only. A later sub-issue that adds a top view uses the same rule. To find a centre: cast the centre ray of the place's view onto the drawn terrain with the probe (trailView.check), round to 6 decimals, and check that the shot shows the feature of the view in its middle. A place with an -above view casts the ray of that view: it looks down at 42° to 70°, so its ray lands nearer the feature than the ray of an eye view at 6° to 12°. Where the first top shot shows the feature away from the middle, set the centre on the feature by hand on that shot (0.072 m per pixel, north up). i07-hairpin-top keeps the owner's earlier centre (46.821770, 8.404970). These centres are also the places of the crate's debug tool (GP1).
The baseline record (a comment on the epic, and the PNGs on the archive drive under /media/timo/OSM1/tmp/ground-plan/baseline/, linked from the comment):
- PNGs of every view of both files on develop,
--gpu --width 1920 --height 960. - The walk and drive flights,
flight.mjs --gpu, three runs each: per pass the median and p95 GPU time, the CPU selection time, nodes, triangles, pages. The viewer times no separate corridor, band or water pass: they draw inside theterrainrender pass. The viewer has no switch for ways off. Soflight-toggle.mjs(in thescripts/folder of the baseline, with the checkout as an argument) flies the same flights and replaces the corridors' draw and cast with no-ops on every odd frame, and tags each frame's timestamps with the toggle. The on and off frames share the flight and the clock; the difference of theirterrainmedians is the cost of the corridors with their band. The same toggle measures the water, and a run with no toggle is the control. The record names one reference figure per flight (corridors with band plus the amortized stamp) for the frame gate of GP9 and GP19. The new path needs its own ways-off switch or the same frame toggle of its own draw calls, because the toggle reaches intoterrain.roadsandterrain.water, which GP19 deletes. - The census counts (CPU and GPU) and the torn-face gate's counts. The gate of TrailView G5: a check that fails on torn faces #3085 is only on
claude/road-g5-torn-faces, which changes the census and tests, not the meshes. Run itsscripts/road-census.tsin a worktree of that branch with develop merged in, and name both commits in the record. If TrailView G5: a check that fails on torn faces #3085 has merged, run it on develop. TrailView G5: a check that fails on torn faces #3085 has merged, so all counts come from develop.plants-in-waterneeds--groundwith a ground bake of the fixture; none exists and this item bakes none, so the record marks that count as not valid. - The road worker's pool use at the end of each flight and its build times (median and p95 per owner), from
flight-toggle.mjs, which times each job of the road worker (one job builds one owner; time = reply minus the later of post and the previous reply). The worker's handler awaits decodes, so replies can pass each other and the times are approximate. - The feature tile sizes and the time of the fixture's feature bake (the commands of the TrailView README). The base of the tile budget is the archive that the bake of the archived inputs writes (
feature-bake/osm.pbfandterrain.mbtiles); GP18 bakes the same inputs. The bake runs 5 times with the time of each step; the gate uses the time after the OSM read, not the OSM read. - The machine, the GPU clock state, and the develop commit.
Plan
- Create
ground-planfrom develop if it does not exist yet (git push origin develop:refs/heads/ground-plan). - Branch from
ground-plan; addbuilder/web/tests/browser/trailview/road-views-top.jsonas in Design; shoot it once and check each place lies in the middle of its picture. - On develop's head (a worktree), build the page against the fixture (
npm run pretest:trailviewinbuilder/web/tests/browser), and run items 1 to 6 of the record, holdingflock /tmp/trailview-gpu.lockfor every GPU run. - Post the record as a comment on the epic: tables first, then the link to the PNG folder.
- Open the pull request with the views file into
ground-plan.
Files
builder/web/tests/browser/trailview/road-views-top.json: create: the views from above of the places of interest.builder/web/tests/browser/trailview/road-views.json: change: removei07-hairpin-top(it moves toroad-views-top.json).
Verification
- Checks:
node trailview/shoot.mjs --gpu --views trailview/road-views-top.json --width 1920 --height 960writes one PNG per view; each shows its place in the middle (the implementer looks at each one). - Measurements: the record of Design, with its commands in the comment.
- Pictures: every view of both files on develop, in the folder that the comment links.
Done when
road-views-top.jsonhas merged intoground-plan.- The epic has the comment with items 1 to 6, and the PNG folder exists.
Out of scope
- Any change to the viewer or the crate.
Questions for the owner
Owner decision (2026-11-03): every recommendation in this section is accepted.
none
Activity
timohueser commentedon Nov 3, 2026
Implementation plan
ground-planexists and is equal to develop (48c32cddb). TrailView G5: a check that fails on torn faces #3085 has merged into develop, so one worktree of this commit gives the views, the baseline and the torn-face gate.road-views.jsonand cast its centre ray onto the drawn ground in the viewer (trailViewprobe on the GPU page). Round the hit to 6 decimals. Write{name: "<place>-top", view: "?lat&lon&heading=0&pitch=-89&eye=60&date&time&weather"}, with date, time and weather of the eye view. A place that has-eyeand-aboveviews uses the eye view.i07-hairpin-topmoves fromroad-views.jsoninto the new file with these values.-topname is in one file only; each top shot shows the feature of its eye view in its middle (I look at each shot).flights.jsonwith--gputhree times (walk and drive count); look for a switch that turns the ways off; run the CPU census and the GPU census; read the pools and road worker times from the flight output and the HUD; measure the fixture's feature tile sizes per zoom and the time of its feature bake; record the machine, GPU clock state and commit.flock /tmp/trailview-gpu.lock. Pictures go to/media/timo/OSM1/tmp/ground-plan/baseline/withINDEX.md. The record goes into one comment on EPIC — TrailView ground plan: one engine for ways and water near the eye #3096.timohueser commentedon Nov 3, 2026
Landed in
ground-planwith #3118. The baseline record is the comment on #3096.