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)

Plan 017: Any German city — the open half: a second Land, NAS input, OSM land cover, a site check

Executor instructions: Follow this plan phase by phase. Each phase is its own PR and must leave Dresden rendering exactly as before. Run every verification command and confirm the expected result before moving on. If anything in the "STOP conditions" section occurs, stop and report — do not improvise. When a phase is done, update the status row for this plan in docs/plans/README.md (PARTIAL with the open phases, DONE at the end).

Multi-site layout (merged 2026-10-01, ADR 0037, plan 049): the data lives per site — data/<site>/{dgm,cityjson,dlm,dop} (Dresden's under data/dresden/), raw downloads in data/_raw/<provider>/ — and the bakes run as bun run fetch <site> / bun run bake <site> [tile…] [--step X] through scripts/pipeline.ts (scripts/bake.ts and --ingest are gone; Saxony's adapter is pipeline/bake/providers/sn.py). Read the paths and commands below in that layout; this is drift, not a STOP condition.

Drift check (run first): git log --oneline -10 -- lib/city/site.ts sites pipeline/bake/ingest_sn.py pipeline/bake/landcover.py pipeline/bake/__main__.py scripts/bake.ts docs/portability.md

Status

  • Priority: P2 (direction, not a defect)
  • Effort: M–L for what is open (phases A–D below, each S–M)
  • Risk: MED — Dresden must stay byte-identical; the data-availability facts per Land are unverified (see "Open questions")
  • Depends on: plan 045 (named class ids in the bakes) before phase C; plan 040 step 3 (ingest hardening: timeouts, https check, atomic extraction) is the pattern a second adapter copies
  • Category: portability / data pipeline
  • Planned at: commit cf8602a, 2026-09-23; rewritten for the Python pipeline on 2026-10-01 (audit) — the bash/JSON text is in git history
  • Status: PARTIAL — the site config, the Python bake package and the Saxony adapter are built (below), and plans 049 and 051 built most of phases A, C and D in their own shape (see "Progress, second round"); open: NAS input (phase B) and the canopy without DOM1 (phase D.1).

Progress, second round (plans 049 and 051)

Plan 049 and ADR 0037 finished most of what is open below, in a different shape: a typed Provider per Land instead of Site.ingest; bun run fetch <site> with one adapter per provider — Saxony, NRW, Bavaria, Hamburg (tested), Berlin (untested) — that also fetches the DGM1 and the LoD2 (CityGML converted in-house, no citygml-tools/cjio); per-site data in data/<site>/, downloads per provider (data/_raw/<provider>/), provenance per site (data/<site>/provenance.json); OSM land cover where the Basis-DLM is not open as Shape (phase C); bun run site <site> (phase D's site:check); tests over every site; one deployment with a route per site. Plan 051 and ADR 0012 added phase C.2: OSM rails and bridge decks (rail_osm.py) for providers without a DLM. Still open: NAS input (phase B) and row-only trees without DOM1 (phase D.1).

Built (2026-09-24…26)

  • The site config, in TypeScript. lib/city/site.ts holds the Site type (id, label, title, EPSG 25832/25833, tileKm, tileSuffix, the tiles as {e, n} km cells, fallback lat/lng, attribution, viewpoints, the ingest adapter) plus tileIdOf / tileExtentOf / utmZoneOf; sites/dresden.ts is the one site and SITE picks it at build time (ADR 0037). There is no tile block any more: the site streams as a 3D Tiles tileset (ADR 0024).
  • One Python bake package (pipeline/bake/, uv; ADR 0037), run by bun run bake [tile] [--ingest] [--step X] with the site's extent and CRS. Canonical raw layout: data/_raw/<site>/{dom1,dop,dlm,osm,lsc,downloads}; the DGM1 and the CityJSON stay committed under data/. pipeline/bake/ingest_sn.py is Saxony's adapter (GeoSN's download-link service per tile, the statewide Basis-DLM, the Geofabrik extract, the city's tree WFS; checked downloads). Every OSM layer is baked on all fifteen tiles from a local Geofabrik extract.
  • The class table is data at the top of pipeline/bake/landcover.py (CLASSES, the burn order, ROAD_HALF_WIDTH); the colours are the client's alone (ADR 0010).
  • Optional inputs, partly: without DOM1 or DOP the canopy, NDVI and roof-colour steps skip with a note; rail decks fall back to the DGM ramp. docs/portability.md separates what is built from what is planned.

Why this matters

The viewer still renders Dresden only. The site config and the bake package made the code Land-neutral in shape, but there is one ingest adapter (Saxony), the bakes need the Basis-DLM as AdV Shape, and docs/portability.md lists fallbacks (OSM land cover, row-only trees without DOM1) that are not built.

The runtime is closer to portable than the pipeline:

  • terrain bounds come from the tileset (lib/city/tileset.ts), not from the tile name;
  • lib/city/crs.ts handles EPSG:25832 and 25833, which together cover every German Land (each Land picks one zone for its whole territory, so a city never straddles zones);
  • the LoD2 attributes the bake reads (function, roofType, measuredHeight) are AdV-standard CityGML, nationwide; the one Saxon extra, Dachneigung, already falls back (lib/city/building-tint.ts);
  • the Basis-DLM layer names the bakes use (veg01_f, ver01_l, gew01_f, ver03_f, ver06_f, attributes BRF/WDM) are the AdV Shape profile, not a Saxon invention.

So the work left is: one ingest adapter per Land, NAS as a second DLM format, and OSM as a same-shape substitute for the Basis-DLM where the Land does not publish it.

Phase A — A second Land: the NRW adapter and a second site (M)

  1. pipeline/bake/ingest_nw.py (NRW, EPSG:25832, 1 km downloads), modelled on ingest_sn.py and its tests (pipeline/tests/test_ingest.py): for rasters, mosaic the Land's tiles and cut our 2 km tile at 1 m (DOP at its native resolution) with rasterio (GDAL is in the wheels; no shell); LoD2 via citygml-tools to-cityjson and cjio … merge + subset --bbox per tile (bake-only tools; document them in docs/data-pipeline.md). Widen Site.ingest (lib/city/site.ts, today the literal "sn") to "sn" | "nw".
  2. sites/<id>.ts for an NRW city the maintainer picks (ask), one or a few tiles; commit its derived data only after the size check (STOP).
  3. Per-tile provenance (was README Direction option 6): the ingest adapter writes data/<site>/<tile>.provenance.json (dataset, edition, download date, licence — the values download() already checks); the HUD footer reads them where it shows the attribution.

Verify: bun run test:pipeline green; SITE=<id> bun dev boots the new site; a --headed shot from an oblique angle shows buildings on the ground (DGM and LoD2 heights agree); Dresden's git status data/ stays clean.

Phase B — NAS input for Länder without AdV Shape (S–M)

The bakes read the Basis-DLM as AdV Shape layers (veg01_f, ver01_l, gew01_f, ver03_f, ver06_f, attributes BRF/WDM). For a Land that ships only NAS/XML, the ingest adapter converts it with GDAL's NAS driver (pyogrio/ogr2ogr from the wheels) into a GeoPackage, and a mapping (AX_Landwirtschaft→1, AX_Wald→2, AX_Gehoelz→3, AX_Wohnbauflaeche|AX_IndustrieUndGewerbeflaeche|…→4, AX_Bahnverkehr→5, AX_Weg→6, AX_Strassenverkehr|AX_Strassenachse→7, AX_Fliessgewaesser|AX_StehendesGewaesser|AX_Gewaesserachse→8) feeds the same burn order. Confirm the width attributes' NAS names before relying on them.

Verify: Dresden's landcover_*.png unchanged after the refactor; a unit test over a tiny NAS sample (or a GeoPackage fixture) yields the expected class ids.

Phase C — OSM as a same-shape land-cover source (M; after plan 045)

Makes the Basis-DLM optional without touching the runtime: the bake writes the same class raster and legend from another source.

  1. pipeline/bake/landcover_osm.py: from the site's .osm.pbf (GDAL's OSM driver, as the other OSM bakes) write landcover_<tile>.png (class ids only — the colours are the client's) and the legend: landuse=farmland|meadow|grass→1, landuse=forest|natural=wood→2, natural=scrub→3, landuse=residential|commercial|industrial|retail→4, landuse=railway→5, highway=footway|path|cycleway→6 (buffer 1 m), other highway=* → 7 (buffer by class, a width= tag wins), natural=water|waterway=riverbank→8, waterway=stream|river buffered. Use plan 045's named class ids, never literals.
  2. rail.py without a DLM: tracks from railway=rail, bridge decks from man_made=bridge polygons (the deck logic is unchanged).
  3. Hedge and tree rows for the canopy gate from OSM natural=tree_row / barrier=hedge when there is no DLM.
  4. A Site field (e.g. landcover: "dlm" | "osm") makes bun run bake run the OSM step instead of landcover.

Verify: for the spawn tile, bake OSM land cover on a branch and compare with the DLM raster: class agreement ≥ 80 % on road/water/forest texels (write the number here); a --headed shot side by side reads as the same place.

Phase D — Without DOM1, a site check, every site in the tests (S–M)

  1. Canopy without DOM1: emit row-only trees at default heights (the portability matrix's "DOM1 absent" row, docs/portability.md) instead of skipping.
  2. bun run site:check [SITE]: per tile, which inputs exist, which artifacts will be baked, which fallback applies — run by bun run bake first and cheap enough for CI.
  3. lib/city/features.test.ts and lib/city/tile-data.test.ts iterate every site's tiles, not just DRESDEN.
  4. Docs: the per-Land table in docs/portability.md (portal, CRS, download tile size, formats, licence), an ADR for the second Land if it changes a decision, docs/data-pipeline.md, the guide's data-sources page in both languages.

STOP conditions

  • Phase 3 or 4 changes any Dresden artifact (git status data/ after a re-bake with the DLM path) — find out why before continuing.
  • A second site's committed derived data would add more than ~40 MB to the repo (the DGM GeoTIFF alone is 13–15 MB per 2 km tile): ask the maintainer (ship one tile, or keep the second site uncommitted) — never switch on Git-LFS (AGENTS.md "ask before").
  • A Land's licence requires terms the HUD footer can't carry (e.g. a non-derivative or non-commercial clause): stop for that Land.
  • citygml-tools / cjio cannot produce CityJSON the bake accepts (CRS other than 25832/25833, missing objectid/surfacetype) — report rather than patch the loader.
  • LoD2 roofs and DGM1 disagree by more than ~1 m at building footprints in the new site (different height references/editions): report.

Open questions (verify, don't assume)

  • Availability and licence per Land of DGM1, DOM1, LoD2, DOP (RGBI or RGB only) and Basis-DLM (Shape vs NAS only, open or not). LoD2 and DGM1 are believed open in most Länder; DOM1 and Basis-DLM are not everywhere. Fill a table in docs/portability.md from the portals themselves.
  • Berlin and Hamburg cut downloads by their own grids/districts — the ingest mosaicking handles that, but confirm the CRS (25833 / 25832).
  • Brick-built northern cities may want a site-level roof/facade tint preset (building-tint.ts defaults to Dresden old-town terracotta). Out of scope here; note it as a future Site field if it matters.
Previous
Plan 086 [rewrite]: The rewrite series — faster on the device, fewer bytes on the wire, less to hold in the head
Next
Plan 019: The GPU checklist — look at everything built headless, on real GPUs and phones
Source on GitHub: docs/plans/017-germany-wide-sites.md
On this page
  • Status
  • Progress, second round (plans 049 and 051)
  • Built (2026-09-24…26)
  • Why this matters
  • Phase A — A second Land: the NRW adapter and a second site (M)
  • Phase B — NAS input for Länder without AdV Shape (S–M)
  • Phase C — OSM as a same-shape land-cover source (M; after plan 045)
  • Phase D — Without DOM1, a site check, every site in the tests (S–M)
  • STOP conditions
  • Open questions (verify, don't assume)