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 0061: The scene runs in a worker; the page hosts it

  • Status: accepted
  • Date: 2026-11

Context

The scene's script shared the page's thread with the HUD. While it booted (compiles, tile parsing, uploads) the page stalled, and a phone's sidebar sheet scrolled against a busy scene: the frame pace kept a scroll guard and a 12 fps cap behind the sheet to keep the scroll alive. Browsers draw WebGPU into an OffscreenCanvas from a dedicated worker, and three's renderers run there since r180.

Decision

  • The scene (create-app.ts and everything it imports) touches no DOM. It reads the page through page-view.ts, gets its size, input, page events and the HUD's covers as calls, and asks the page for what only the page has: nameplate letters in the site's web fonts. An oxlint rule keeps document, window and location out of scene modules.
  • scene-server.ts serves the scene over messages (scene-protocol.ts). scene-client.ts is the page's end: a handle whose getters read the mirror the scene sends when it changed, whose value calls return promises, and whose sync() waits for the mirror after a write.
  • The server runs in a worker (scene-worker.ts, created as new Worker(…, { type: "module" }); the bundler emits a classic bootstrap that loads the scene's chunks with importScripts) on the canvas's OffscreenCanvas; the page keeps input capture, pointer lock, layout, fonts and image composing. A browser that cannot draw from a worker — its hello reports no WebGPU adapter, no requestAnimationFrame or no OffscreenCanvas — is told so, as one without WebGPU is (ADR 0027); there is no fallback onto the page for old browsers. The same server runs on the page behind a MessageChannel only for debugging: ?thread=main and three's Inspector (?inspect=1).
  • A lost GPU the page recovers from by a reload is listed in the init (reloadable); the scene releases its device, then reports onReload.
  • Behind a covering sheet the scene draws only what is asked of it: a call draws half a second at 12 fps and does not end the scene's standing still; a scene that moves in those frames (a glide a call started, a stream landing) keeps that rate; a still one draws nothing else.

Consequences

  • A scene module needs no DOM in tests or the worker; a new DOM need is a call from the page or a page-view field, never a global.
  • Every HUD read of the scene is either the mirror (one frame stale) or a promise; a spec that writes and then reads awaits handle.sync().
  • A worker frees the page's thread, not the GPU: a long compile still holds the GPU process and can still stall the compositor.
  • Errors and unhandled rejections in the worker reach the page's crash trail as page errors.
  • A dependency that reads window breaks in the worker: 3DTilesRendererJS resolves tileset paths against window.location, patched to globalThis.location (patches/3d-tiles-renderer@0.5.4.patch) until upstream changes it. three's TextureLoader makes an <img>: an OBJ's textures decode through createImageBitmap (design-bitmap-texture.ts), and a Rhino file's textures and text dots, which three's 3DMLoader draws through the DOM, are left out, the panel saying so (design-formats.ts).

Alternatives

  • Comlink or a generic RPC proxy: hides which calls cross and makes every getter a promise; the mirror keeps the HUD's per-frame reads synchronous. Rejected.
  • Only the boot in a worker (parse and compile there, draw on the page): three's renderers do not share a device across threads.
  • Keep the scroll guard and the 12 fps cap: they treat the symptom and cost frames on every page.
Previous
ADR 0060: Glass fronts are read from street photos by an open image model, offline
Next
Data → feature provenance
Source on GitHub: docs/adr/0061-the-scene-runs-in-a-worker.md
On this page
  • Context
  • Decision
  • Consequences
  • Alternatives