City Walk/WissenZum StadtspaziergangViewer
ImpressumDatenschutz
Leitfaden
  • So funktioniert der Stadtspaziergang
  • Woher die Daten kommen
  • Quellen nach Stadt
  • Wie der Viewer zu einer Angabe kommt
  • Der Weg der Daten
  • Bedienung
  • Glossar
Guide (English)
  • How the city walker works
  • Where the data comes from
  • Sources by city
  • How the viewer comes by what it shows
  • From download to browser
  • Using the viewer
  • Glossary
Entwicklung (English)
  • docs/ — the project knowledge base
  • Rendering — how the data becomes pixels
  • Data pipeline — the bakes, the build step and the artifact contracts
  • Architecture decision records
  • Data → feature provenance
  • Transformation catalog
  • Portability — rendering any location, with whatever data it has
  • Writing a walk
  • Routines: the twin's scheduled agents
  • Implementation plans, backlog and audit history
    • Completed plans — condensed records
    • Plan 086 [rewrite]: The rewrite series — faster on the device, fewer bytes on the wire, less to hold in the head
    • Plan 017: Any German city — the open half: a second Land, NAS input, OSM land cover, a site check
    • Plan 019: The GPU checklist — look at everything built headless, on real GPUs and phones
    • Plan 021: /wissen on Astro Starlight instead of a hand-built Next route
    • Plan 047 (spike): "Problem melden" — the crash report with somewhere to go
    • Plan 048 (spike): Share a view as a link, and commit the reference views the GPU checks need
    • Plan 050: Landmarks and what LoD2 leaves out — measured in DOM1, named by OSM and Wikidata
    • Plan 051: Stand-ins where a Land publishes less, and looks derived from each city's data
    • Plan 052: A queryable twin — identity, semantics and provenance, asked on demand
    • Plan 053: Time and live sources — the twin's fourth dimension
    • Plan 054: Scenarios — what-if studies drawn in the scene's own hand
    • Plan 069: Find what holds the load at 52 %, then take it off the tile path
    • Plan 070: Each tile holds a fraction of the raster memory it holds today
    • Plan 071: A phone renders a lean scene, a desktop a lighter one
    • Plan 074: Bake the static dressing, load the optional features on demand, one store for the HUD
    • 076 — Streaming without holes: the ground first, a plate under everything, coarse buildings and trees from the start
    • Plan 077: One rasters module — a tile's rasters loaded, shared and weighed behind one interface, their files named by the artifact table
    • 078 — One scene environment the dressings bind at birth
    • Plan 079: A page that lost its GPU comes back where it stood, through one recovery session
    • 080 — One row per inquiry kind: the twin's per-kind dispatch in one place
    • 082 — One answer turn, and a code for every way it ends
    • 084 — One session for an answer's lifetime: reading aloud, dictation and the scene's waits in one module
    • 085 — Window niches and shop windows: performance and follow-ups
    • Plan 087 [rewrite]: Plates compared on a real GPU, and one ledger every plan of the series writes its figures into
    • Plan 088 [rewrite]: The tileset is a published product, named by a lock file; the web build bakes nothing and data/ leaves git
    • Plan 089 [rewrite]: The bakes are type-checked in CI against a baseline that only shrinks
    • Plan 090 [rewrite]: A tile's dressing arrives in the layout the GPU draws from
    • Plan 091 [rewrite]: A tile's rasters arrive as the GPU reads them — plain arrays for ids, blocks for soft fields, a few files and bindings
    • Plan 092 [rewrite]: The bakes work on site-wide typed tables, cut tiles last, and no step rewrites another's file
    • Plan 093 [rewrite]: The stream's tile is smaller than the bake's — a quadtree whose levels replace the raster twins, built only if a phone still asks for it
    • Plan 094 [rewrite]: The clay's limits are counted by a test, and every pipeline the scene draws with is known at boot
    • Plan 095 [rewrite]: The viewer is a package with one entrance, a coordinate's frame is its type, and bootApp is owners
    • Plan 096 [rewrite]: Every bake heuristic that guesses has a reference set and a score a bake PR must hold
  • What the data streams carry that the walker does not use yet
Contents
Leitfaden
  • So funktioniert der Stadtspaziergang
  • Woher die Daten kommen
  • Quellen nach Stadt
  • Wie der Viewer zu einer Angabe kommt
  • Der Weg der Daten
  • Bedienung
  • Glossar
Guide (English)
  • How the city walker works
  • Where the data comes from
  • Sources by city
  • How the viewer comes by what it shows
  • From download to browser
  • Using the viewer
  • Glossary
Entwicklung (English)
  • docs/ — the project knowledge base
  • Rendering — how the data becomes pixels
  • Data pipeline — the bakes, the build step and the artifact contracts
  • Architecture decision records
  • Data → feature provenance
  • Transformation catalog
  • Portability — rendering any location, with whatever data it has
  • Writing a walk
  • Routines: the twin's scheduled agents
  • Implementation plans, backlog and audit history
    • Completed plans — condensed records
    • Plan 086 [rewrite]: The rewrite series — faster on the device, fewer bytes on the wire, less to hold in the head
    • Plan 017: Any German city — the open half: a second Land, NAS input, OSM land cover, a site check
    • Plan 019: The GPU checklist — look at everything built headless, on real GPUs and phones
    • Plan 021: /wissen on Astro Starlight instead of a hand-built Next route
    • Plan 047 (spike): "Problem melden" — the crash report with somewhere to go
    • Plan 048 (spike): Share a view as a link, and commit the reference views the GPU checks need
    • Plan 050: Landmarks and what LoD2 leaves out — measured in DOM1, named by OSM and Wikidata
    • Plan 051: Stand-ins where a Land publishes less, and looks derived from each city's data
    • Plan 052: A queryable twin — identity, semantics and provenance, asked on demand
    • Plan 053: Time and live sources — the twin's fourth dimension
    • Plan 054: Scenarios — what-if studies drawn in the scene's own hand
    • Plan 069: Find what holds the load at 52 %, then take it off the tile path
    • Plan 070: Each tile holds a fraction of the raster memory it holds today
    • Plan 071: A phone renders a lean scene, a desktop a lighter one
    • Plan 074: Bake the static dressing, load the optional features on demand, one store for the HUD
    • 076 — Streaming without holes: the ground first, a plate under everything, coarse buildings and trees from the start
    • Plan 077: One rasters module — a tile's rasters loaded, shared and weighed behind one interface, their files named by the artifact table
    • 078 — One scene environment the dressings bind at birth
    • Plan 079: A page that lost its GPU comes back where it stood, through one recovery session
    • 080 — One row per inquiry kind: the twin's per-kind dispatch in one place
    • 082 — One answer turn, and a code for every way it ends
    • 084 — One session for an answer's lifetime: reading aloud, dictation and the scene's waits in one module
    • 085 — Window niches and shop windows: performance and follow-ups
    • Plan 087 [rewrite]: Plates compared on a real GPU, and one ledger every plan of the series writes its figures into
    • Plan 088 [rewrite]: The tileset is a published product, named by a lock file; the web build bakes nothing and data/ leaves git
    • Plan 089 [rewrite]: The bakes are type-checked in CI against a baseline that only shrinks
    • Plan 090 [rewrite]: A tile's dressing arrives in the layout the GPU draws from
    • Plan 091 [rewrite]: A tile's rasters arrive as the GPU reads them — plain arrays for ids, blocks for soft fields, a few files and bindings
    • Plan 092 [rewrite]: The bakes work on site-wide typed tables, cut tiles last, and no step rewrites another's file
    • Plan 093 [rewrite]: The stream's tile is smaller than the bake's — a quadtree whose levels replace the raster twins, built only if a phone still asks for it
    • Plan 094 [rewrite]: The clay's limits are counted by a test, and every pipeline the scene draws with is known at boot
    • Plan 095 [rewrite]: The viewer is a package with one entrance, a coordinate's frame is its type, and bootApp is owners
    • Plan 096 [rewrite]: Every bake heuristic that guesses has a reference set and a score a bake PR must hold
  • What the data streams carry that the walker does not use yet
Entwicklung (English)

085 — Window niches and shop windows: performance and follow-ups

Status: TODO. Written 2026-11-10 from the review rounds on PR #273 (window niches, shop windows cut into the wall, painted signs). Every point below came up there, more than once, and was left out of #273 on purpose: none is a visible fault on a typical walk. They are ordered by what they cost a phone.

Read first: docs/rendering.md (rows Window niches, Shopfronts, Plinths), app/_components/window-niche-layer.ts, window-niche-client.ts, lib/city/window-niches.ts, lib/city/shop-windows.ts, scripts/bake-city-mesh.ts (planShopfronts, appendShopfronts), ADR 0047 (phone memory).

STOP if a step makes a phone's memory grow (ADR 0047) or a WebGPU-only check is needed that the headless WebGL2 e2e cannot make: then measure on a real GPU (bun run shots, ?trail=1 on the iPhone) first.

A. Performance on the runtime path

  1. Refill without churn. Every 6 m (and every frame in a fast flight) fill rescans every packed niche within 270 m of every shown tile, allocates a candidate per niche, unpacks them twice and, when the set changed, rewrites the whole instance range. Group the niches by house at add (a house → [first, end) index, its box and its nearest point), rank houses by their boxes, unpack only the picked houses, and write only the instances that changed (addUpdateRange per run). Measure: refill time and GC in a flight over the Altstadt, desktop and phone.
  2. Only the changed flag texels. setNiched → markObjects walks every object and re-uploads the tile's whole object texture for a few OBJECT_FLAG_NICHED bits. Either an update range over the changed rows or a small separate niched mask (one byte per object) the clay reads.
  3. The wall copy off the main thread. nicheInput scans every triangle of a full-LoD2 tile in processTileModel (accessors, applyMatrix4 per corner) before the worker sees anything. Hand the raw quantised arrays and the tile's matrix over and filter and transform in the worker; weigh the copy as today (nicheCopyBytes). Watch the CPU-copy drop (cityCpuDroppable) and bvhBuilding: the arrays must be copied, not borrowed.
  4. The cut variant compiled before it shows. cutOn flips the clay's maskNode and only queues recompile, so the first tile that starts cutting builds the clay|niches pipeline in the frame (once per session and camera kind). Compile it before the flip: a stand-in mesh on the same geometry with a cut clone, or warm the variant once with the first city tile; keep the stand-in until the real mesh has drawn (three frees a node-builder state when its last user goes). Also: do not anchor the variant for Modell's camera (Modell never cuts), and key compile-lanes records by material.version so cutGround (terrain design cut) stops building in the frame too; PostStack.recompile then goes.
  5. No discard in the shadow pass. maskShadowNode = keepWalls (a constant true) still routes the clay's shadow depth through three's mask path with a discard and its own pipeline. Find a way to keep the walls whole in the shadow map without a mask node there.
  6. One wall view per fragment. clayWindows evaluates wallView twice (recess, parts) and fwidth(s) twice (grid's inside); compute once and pass down.

B. Bake

  1. Ask coverage, cut once. planShopfronts runs a full cutWall (difference, earcut, edge loops) per bay only to learn whether it is covered, and appendShopfronts cuts again. A coverage-only pass (intersection areas) for the plan; or keep the plan's cut and reuse it. The (s, z) box reject is in (#273).
  2. Plan and cut agree. Two shopfront records on one host and plane: one's sign is cut before the other's window, which may then fall under MIN_COVER although the plan broke the plinth for it. Plan signs as well, or take the plinth breaks from what was cut (lay the plinths after the cut, keeping the plan only for wall finding).

C. Correctness follow-ups (rare)

  1. The niche's colour as the wall's. wallColour mixes base and tint only; the clay also darkens the lowest 5 m (GROUND_SHADE) and applies OSM colours, facade readings and articulation. Share the clay's wall colour node with the niche material (an instance attribute or the object texture) so a house keeps its tone at the 250 m hand-over.
  2. Box front at a grazing view. The box's open front sits on the wall's mean plane; where a quantised triangle stands up to 3 cm in front of it, a ray past ≈ 55° through the cut's edge can miss the 4 cm overlap. A box reaching a little out of the wall only within the opening, or a deeper side overlap.
  3. Opening sizes past 5.1 m. packNiches caps width and height at 255 × SIZE_STEP_M; a taller stair-hall window would get a box shorter than its cut. Widen the field or refuse the niche (no cut: the object then keeps the drawn window).
  4. Column index past 255. j is packed in 8 bits; a wall with more than 256 axes would light its niches differently after dark.
  5. Hidden while the BVH holds the index. stands() reads the wanted hidden set, while the clay applies it once the BVH worker hands the index back (≈ 1 s on a phone): boxes may stand in the air for that long after a design moves. Refill when the deferred applyHidden settles, and read the applied set.
  6. A sign over drawn windows on a raised host is placed from the street's ground, not the host's base (shopfrontMesh knows no base).
  7. A stepped wall's niche whose opening straddles the wall's edge shows its box beside the wall (any probe on the wall places it). Clip the box to the wall's extent along the opening.
  8. CPU and shader grids tied by a test. wallColumns/wallRows re-implement clay-windows.ts columns/rows; a test that evaluates both (the TSL graph on a fixed input, or shared constants with a golden table) keeps them one.

D. Structure

  1. One worker job queue. window-niche-client.ts, bvh-client.ts and ground-prep-client.ts each hand-roll start, give-up, abort, copy-until-answered and stop. One helper, parameterised by transfer and run-here.
  2. Motion blur hold by time. BLUR_HOLD_FRAMES counts frames (83 ms at 144 Hz, 400 ms at 30 fps); hold by accumulated moveMs.
  3. The ground-join audit (scripts/ground-joins.ts) still reads the plinths from the unbroken features; read the baked stretches (after withoutSegments) so the plinths' budget measures what is drawn.
  4. drawScene in post-stack.ts is a single-use closure; inline it.
Previous
084 — One session for an answer's lifetime: reading aloud, dictation and the scene's waits in one module
Next
Plan 087 [rewrite]: Plates compared on a real GPU, and one ledger every plan of the series writes its figures into
Source on GitHub: docs/plans/085-window-niche-follow-ups.md
On this page
  • A. Performance on the runtime path
  • B. Bake
  • C. Correctness follow-ups (rare)
  • D. Structure