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 0027: WebGPURenderer and TSL node materials, one path, public API only

  • Status: accepted
  • Date: 2026-09

Context

Every custom look used to be a string patch on three.js shader chunks (onBeforeCompile), fragile against renames and silent when a patch failed. three (r186 then, r187 now) ships WebGPURenderer, TSL node materials, scene.fogNode and node post-processing. A spike measured WebGPU 40–80 % faster at the same look, and found where a naive port stalls: node builds run on the main thread, every InstancedMesh built separately, and a scene pass nested in the post pipeline never matched what compileAsync prepared (r187 fixed both in three). The spike fixed those by patching renderer internals, which kept misbehaving.

Decision

  • One renderer, one backend: WebGPURenderer on WebGPU. A browser without a WebGPU adapter is told so; three's WebGL2 backend is not used. No WebGLRenderer, no GLSL, no second path.
  • Every look term is a TSL node on a node material; a fixed strength is a named constant node, anything that moves a shared uniform's .value. What the sun and the date move lives in scene-environment.ts: a layer reads it and adds no setter to setSun. Fog is the one scene.fogNode.
  • Public API only: no prototype patches, no private members. The stalls are designed out instead: the scene renders top-level into its own target that the post pipeline reads; instanced sets are Instances (a plain Mesh over an InstancedBufferGeometry), so sets share a build; materials without per-tile data are scene-wide; tiles and dressings are compiled before they show, one compile at a time, and Modell's parallel camera gets its own builds before it draws.

Consequences

  • A look term is a type-checked expression; there are no chunk names to pin.
  • The shadow pass's pipelines for new casters still build in the frame that first draws them — the price of public API. Measure before adding machinery.
  • Compiles run one at a time (compileInTurn), and a frame names the targets it draws into: three r187's compileAsync keeps its state on the renderer around every await inside it, so two in flight resume into each other's, and it restores the target it was called with. Both are upstream bugs, worked around until a release fixes them (rendering.md).
  • A material builds once per kind of camera (r187: a parallel view's light has one fixed direction): Modell's builds are made while its dolly zoom in runs.
  • WebGPU's limits bind every material: eight vertex buffers, sixteen inter-stage variables (the clay uses all but two). A mesh past either does not draw.
  • Headless CI renders WebGPU over SwiftShader's Vulkan (Chrome's own Vulkan on SwiftShader too, or the canvas cannot present), so it meets the same limits as a device.
  • iPhones before iOS 26, Firefox without WebGPU and blocklisted GPUs get the no-WebGPU message (decided 2026-11).

Alternatives

  • WebGL with GLSL patches: worked, but the patches were the most fragile code in the repo.
  • WebGPU plus a WebGLRenderer fallback: every look written twice.
  • Patching three's renderer (render guard, shared instancing, context override): depended on private members and misbehaved unpredictably.
  • InstancedMesh: up to r186 three put its uuid in the build key — one build per set. r187 shares those builds; Instances stays because every layer's nodes and shared buffers are written for it, and instanceColor multiplies any object's colour by an InstancedMesh-only varying.
Previous
ADR 0024: The build bakes each city into a 3D Tiles tileset that streams around the camera
Next
ADR 0030: The ground — a TIN of the native DGM, its static parts baked in, every part meeting it by one set of rules
Source on GitHub: docs/adr/0027-webgpu-renderer-and-tsl.md
On this page
  • Context
  • Decision
  • Consequences
  • Alternatives