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
    • ADR 0001: Static where possible — no database, no accounts, nothing kept about a visitor
    • ADR 0002: Imperative three.js inside a React shell, not react-three-fiber
    • ADR 0005: Data stays in its provider's UTM zone, under one recenter offset and a rotated world group
    • ADR 0009: Light, shadows and post — soft PCF redrawn on demand, four concentric rings, a baked horizon for the far field, a fixed lamp pool
    • ADR 0010: The look — opaque clay on a painted ground, colours within one palette, detail drawn softly
    • ADR 0012: Sources — official data first, OSM and Wikidata for what it lacks, named stand-ins marked per city
    • ADR 0018: Headless tests run a lite profile and count frames; visuals are judged on a real GPU through snapshots
    • ADR 0021: docs/ is published as /wissen, and its diagrams are prerendered SVG
    • ADR 0024: The build bakes each city into a 3D Tiles tileset that streams around the camera
    • ADR 0027: WebGPURenderer and TSL node materials, one path, public API only
    • ADR 0030: The ground — a TIN of the native DGM, its static parts baked in, every part meeting it by one set of rules
    • ADR 0032: The camera is never below the ground or inside a building
    • ADR 0034: Picture styles are one post pass over the clay scene, reading the light and the world
    • ADR 0036: Buildings are LoD2; geometry beyond it only where a measurement and a name agree, and roofs that miss the scan are rebuilt in its form
    • ADR 0037: Cities, providers and the pipeline — fetch, bake, build; one deployment, a route per city
    • ADR 0040: Data layers are switches, off at start, drawn as glass; optional features start on first use
    • ADR 0041: Rails, trams and bridges — decks measured in the surface model, every line on a drivable profile solved by the build
    • ADR 0042: The twin answers on demand — facts and provenance ride in the tileset, text appears only when asked
    • ADR 0043: Crash and page reports go to an error tracker without an SDK, and the privacy page says what the code does
    • ADR 0044: Modell — the city in parallel projection, every pass reading the camera through a lens
    • ADR 0047: Every device gets a budget in true bytes, a phone's memory never grows, and a device that lost its GPU gets a lighter page
    • ADR 0048: A network failure is retried for a budget of the page's visible time, never decided at once
    • ADR 0054: A planner's design is loaded on the device, placed by its coordinates or by hand, and stands in for the buildings it covers
    • ADR 0055: What the twin knows is baked as files; walks are written ahead, their narration marked, every claim sourced
    • ADR 0056: Frag die Stadt runs on the visitor's own key, through one stateless function with a fixed prompt and fixed tools
    • ADR 0057: The Sprachführer speaks and listens with the browser's own voice, and the scene rests while it does
    • ADR 0059: One schema per file a bake hands over, checked by the build
    • ADR 0060: Glass fronts are read from street photos by an open image model, offline
    • ADR 0061: The scene runs in a worker; the page hosts it
  • 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
  • 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
    • ADR 0001: Static where possible — no database, no accounts, nothing kept about a visitor
    • ADR 0002: Imperative three.js inside a React shell, not react-three-fiber
    • ADR 0005: Data stays in its provider's UTM zone, under one recenter offset and a rotated world group
    • ADR 0009: Light, shadows and post — soft PCF redrawn on demand, four concentric rings, a baked horizon for the far field, a fixed lamp pool
    • ADR 0010: The look — opaque clay on a painted ground, colours within one palette, detail drawn softly
    • ADR 0012: Sources — official data first, OSM and Wikidata for what it lacks, named stand-ins marked per city
    • ADR 0018: Headless tests run a lite profile and count frames; visuals are judged on a real GPU through snapshots
    • ADR 0021: docs/ is published as /wissen, and its diagrams are prerendered SVG
    • ADR 0024: The build bakes each city into a 3D Tiles tileset that streams around the camera
    • ADR 0027: WebGPURenderer and TSL node materials, one path, public API only
    • ADR 0030: The ground — a TIN of the native DGM, its static parts baked in, every part meeting it by one set of rules
    • ADR 0032: The camera is never below the ground or inside a building
    • ADR 0034: Picture styles are one post pass over the clay scene, reading the light and the world
    • ADR 0036: Buildings are LoD2; geometry beyond it only where a measurement and a name agree, and roofs that miss the scan are rebuilt in its form
    • ADR 0037: Cities, providers and the pipeline — fetch, bake, build; one deployment, a route per city
    • ADR 0040: Data layers are switches, off at start, drawn as glass; optional features start on first use
    • ADR 0041: Rails, trams and bridges — decks measured in the surface model, every line on a drivable profile solved by the build
    • ADR 0042: The twin answers on demand — facts and provenance ride in the tileset, text appears only when asked
    • ADR 0043: Crash and page reports go to an error tracker without an SDK, and the privacy page says what the code does
    • ADR 0044: Modell — the city in parallel projection, every pass reading the camera through a lens
    • ADR 0047: Every device gets a budget in true bytes, a phone's memory never grows, and a device that lost its GPU gets a lighter page
    • ADR 0048: A network failure is retried for a budget of the page's visible time, never decided at once
    • ADR 0054: A planner's design is loaded on the device, placed by its coordinates or by hand, and stands in for the buildings it covers
    • ADR 0055: What the twin knows is baked as files; walks are written ahead, their narration marked, every claim sourced
    • ADR 0056: Frag die Stadt runs on the visitor's own key, through one stateless function with a fixed prompt and fixed tools
    • ADR 0057: The Sprachführer speaks and listens with the browser's own voice, and the scene rests while it does
    • ADR 0059: One schema per file a bake hands over, checked by the build
    • ADR 0060: Glass fronts are read from street photos by an open image model, offline
    • ADR 0061: The scene runs in a worker; the page hosts it
  • 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
  • What the data streams carry that the walker does not use yet
Entwicklung (English)

ADR 0009: Light, shadows and post — soft PCF redrawn on demand, four concentric rings, a baked horizon for the far field, a fixed lamp pool

  • Status: accepted
  • Date: 2026-06, rewritten 2026-11

Context

Sun shadows are the most expensive item after post-processing and the hardest to get right on a large, gently sloped ground at a grazing sun. A shadow frustum must stay tight for sharp texels, yet the view reaches kilometres, on foot and from the air. Fill rate, not draw calls, is the bottleneck. three builds the number of lights into every lit material, and a phone has no memory to spare (ADR 0047).

Decision

  1. The shadow recipe: PCFShadowMap with a shadow.radius that leaves no gaps between its samples; the terrain receives but never casts; normalBias = 0; a small bias per ring; no colour target.
  2. The map is four concentric rings: squares of one resolution, each three times as wide as the one inside it, the layers of one depth array drawn by one camera. A fragment reads the finest it lies on, cross-faded into the next at the edge. A phone's four of 900² hold fewer bytes than the one 2048² it had and pay for what the wide rings' casters hold beside them, so the rings are the one path on every device. Modell, of one scale across its picture, tiles its square with the same layers.
  3. A ring is redrawn only on demand, one a frame: when it has drifted a share of its size, the sun moves or a caster changes (invalidateShadows()). A small ring redraws often with few casters, a wide one rarely with many. Thin casters stop short of the coarse rings. The tile stream keeps its own square (lib/city/shadow-fit.ts), so what loads does not change with the rings.
  4. Past the map the ground's shadows come from a baked horizon map (pipeline/bake/skyview.py): the skyline's elevation per azimuth in a near and a far band, combined with the shadow map by min. The same bake writes the sky-view factor, which scales the ambient light only.
  5. Nothing animated reaches the shadow map. Sway casts rigidly through castShadowPositionNode; clouds, water and moving data layers cast nothing.
  6. A fixed pool of real lamp lights, sized per tier before the first frame and never changed (three on a desktop, one on a phone), retargeted to the nearest lamps: spot lights aimed down, as a street lamp's shade throws its light. The walls and a fountain's water take the lamps near the eye in one loop over a fixed uniform array (48, a phone 12), each less the share a real light gives it; every lamp's head, halo and pool is emissive and additive. All scaled by the night factor.
  7. Post: the scene renders into its own target; GTAO at half resolution, smoothed, never gated by motion; depth of field on a desktop only, as wide as a real lens's and drawn by its own gather (lens-blur.ts), dropped while the camera moves by switching between two prebuilt pipelines and grown back in after; SMAA on a desktop, FXAA on a phone; grading, grain and vignette in the output node. No tone mapping.

Consequences

  • A shadow looks the same from anywhere at the same distance: its sharpness depends on no height, no direction and no history of the flight, and no switch or refit changes the whole picture at once.
  • Walking redraws a ring a few times a minute instead of every frame. Every change to casters or the sun must call invalidateShadows(); a missed call is a stale shadow, never a crash.
  • Half of each ring lies behind the camera on foot, unseen, the price of not redrawing on every turn: far off, its texels are wider than a map fitted to the view would have at its best.
  • A desktop holds 64 MiB of shadow map (36 with the one 3072² before).
  • Depth passes are more frequent and each smaller. Whether that holds on a real phone, where the memory was measured only in emulation, is judged there, not on a desktop.
  • A new lit feature fits into the pool or is faked.
  • A pass's sample counts are construction-time settings; switching them by motion is a rebuild hitch.

Alternatives

  • One map warped over the view (LiSPSM, shipped until 2026-11): it held shapes out to the fog from one map, but a warp has nothing to work with along the light. At a low sun, looking within about 35° of its azimuth or away from it, its near texels were 0.5–1.2 m against 0.06 elsewhere: every winter day lamp shadows vanished and house edges blurred, and it needed a second, sharper-or-softer map on foot, switched at one height, with steps of its own as it refitted.
  • CSMShadowNode: slices the view and follows it every frame, one texture per cascade, one camera per cascade, and binds one camera for good; on-demand redraws, Modell and the phone's memory all fall out of that. TileShadowNode redraws all its layers at once.
  • Virtual shadow maps (Unreal's clipmap, Sundial on three): the same rings at page granularity, but on three's internals and without multi-draw on WebGPU, tile by tile. Worth another look when three has multiview.
  • VSM: corduroy rings on large ground at grazing angles, at any blur.
  • A large normalBias: a bright peter-panning strip at every contact.
  • A bigger frustum or a 4096 map at eye level: coarser texels, or cost without visible gain once the radius softens.
  • Re-centring per texel: a depth pass on almost every moving frame.
  • Gating AO by motion: the contact shadows blinked on every step.
  • Swapping one pipeline's output node for DoF: re-translates the whole post graph.
  • A real light per lamp, or per-frame shadow updates for sway: a rebuild storm, or the end of the on-demand map.
  • Occluders from DOM1 for the horizon: includes trees, which cast their own shadows.
Previous
ADR 0005: Data stays in its provider's UTM zone, under one recenter offset and a rotated world group
Next
ADR 0010: The look — opaque clay on a painted ground, colours within one palette, detail drawn softly
Source on GitHub: docs/adr/0009-shadow-recipe.md
On this page
  • Context
  • Decision
  • Consequences
  • Alternatives