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 0024: The build bakes each city into a 3D Tiles tileset that streams around the camera

  • Status: accepted
  • Date: 2026-09, rewritten 2026-10

Context

Decoding a GeoTIFF or parsing CityJSON in the browser cost seconds per tile, and the results are deterministic functions of committed files. A city is too large to load whole, and a fixed block of tiles ended at a visible edge. Data files change rarely but must reach every client when they do.

Decision

  • Everything heavy is baked at build time by scripts/prepare-data.ts: the browser decodes no GeoTIFF and parses no CityJSON. The build caches each artifact by content (inputs, the modules that bake it, the locked package versions).
  • The city is an OGC 3D Tiles 1.1 tileset of glTF 2.0 content (meshopt, quantised, pre-gzipped), streamed by 3DTilesRendererJS. Per site tile: the buildings (one mesh, a feature id per vertex, a property table per object — EXT_mesh_features, EXT_structural_metadata) over the terrain at two levels, coarse far off and fine near the camera. Distance, not a role, decides which tile is detailed.
  • Content-hashed names and one manifest. Every file is published as <stem>.<hash>.<ext> and served immutable; manifest.json (no-cache) names the hashed tileset, which names everything else: each glTF and, on its tile, the side files it is dressed with — a glTF's bytes do not change when a side file's name does.
  • Everything a tile brings is built and freed with it in the dressing plugin (processTileModel / disposeTile), compiled before it shows; what lands after the tile itself — its dressing, a city tile's murals, a data layer's bodies — goes through one lifecycle (late-parts.ts): built in its turn, compiled before it hangs, weighed from its build, freed once its compile has ended.
  • Two phases. The first frame waits on the spawn tile's buildings and any of its terrain levels; the dressing (trees, lamps, rails, furniture) then streams tile by tile, and the HUD flips to ready when the spawn tile is dressed and the stream is idle.
  • What streams is decided by a twin camera whose far plane ends where the fog does, plus the sun's shadow camera while the sun is up, at a low resolution of its own.

Consequences

  • The world is bounded by the data, not by boot cost; collision, picking and demolish work on every loaded tile.
  • Content opens in any glTF / 3D Tiles tool; the per-object table is inspectable metadata.
  • Anything that builds a /data URL goes through the manifest.
  • Anything added after the first frame redraws the shadow map and respects disposal, or it shows as a missing shadow or a leak; what a tile gains after it landed is a late part (late-parts.ts), which weighs, frees after the compile and reports for it.
  • A new streaming need registers against the twin camera, not the camera.

Alternatives

  • A hand-written tile manager with a loader worker and 1 km cells (never accepted): 1–1.5 k lines of what the library has.
  • CesiumJS, giro3d, iTowns: a second renderer or a framework that owns the scene, against the stylised look and ADR 0002.
  • Runtime decode with a resolution knob: the grid size is a bake-time property.
  • Terrain as a custom heightmap content type: smaller, but a private format again.
  • Query-string cache busting, or mtime copies with revalidation: inconsistent caches, or a round trip per file per visit.
Previous
ADR 0021: docs/ is published as /wissen, and its diagrams are prerendered SVG
Next
ADR 0027: WebGPURenderer and TSL node materials, one path, public API only
Source on GitHub: docs/adr/0024-site-streams-as-3d-tiles.md
On this page
  • Context
  • Decision
  • Consequences
  • Alternatives