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 086 [rewrite]: The rewrite series — faster on the device, fewer bytes on the wire, less to hold in the head

What this file is. The map of the rewrite series, plans 086–096. It is not executed itself: it says what the series is for, in which order its plans go, what each one may assume of the others, and what was considered and left out. Every plan of the series carries [rewrite] in its title and in its row in README.md, and names this file under Series. An executor reads this file once, then its own plan.

Planned at: commit 5dfa300d, 2026-11-16.

Where it comes from

On 2026-11-16 the maintainer asked what one would do differently if the project, as it stands, were built from scratch — after the moves it has made one at a time (WebGL to WebGPU and TSL, a fixed block of tiles to a streamed 3D Tiles tileset, LoD2 and the DGM alone to OSM, the DLM, the orthophoto, the laser scan and street photos, the page's thread to a worker). The answer, read from the ADRs, the plans and the code: the big decisions stand. What a fresh start would place differently are the seams between the stages, because each move left its predecessor's seam where it was:

  • the bake hands over about fifty loose files a tile (GeoJSON, JSON, PNG), and the browser still builds seventeen kinds of dressing from them, tile by tile, on the thread that draws;
  • the 2 km tile is at once the Land's download cell, the bake's unit, the stream's unit and the memory's unit;
  • the baked data lives in git and is baked again inside the web build;
  • looks are judged by hand on a GPU nobody has in CI.

The maintainer chose all of it, with three aims and two rulings.

The three aims, and how each is counted

Every plan says which of these it serves and proves it in the ledger plan 087 sets up. A plan that buys one aim with another says so in its row and waits for the maintainer's word, as ADR 0047's exceptions do.

AimCounted asWhere it stands (source)
Faster on the devicetime to the first frame and to ready; CPU a landing tile costs the scene's thread; frames kept while tiles streama fine level's dressing 1.65–2.90 s on SwiftShader (PR #156, 2026-10-10); before they were sliced, on the phone profile: rails 1.3 s, trees 0.8–1.3 s, tram 0.7 s a tile (docs/rendering.md, "The frame budget")
Fewer bytes on the wiregzip bytes of the first load's JavaScript; bytes and requests of the spawn tile, of a fine level, of a far tile, of the site1.0 MB of JavaScript for /dresden (audit 2026-11-11); a tile 4.0–9.7 MB, Dresden ≈ 98.9 MB (docs/data-pipeline.md, measured 2026-09-25: stale, 087 measures again)
Less complexitykinds of side file and formats a tile has; lines of mesh building in the viewer; modules that handle a tile's seam; rules AGENTS.md has to state because nothing checks them17 dressing kinds, 4 hand-made binary formats beside GeoJSON; 27 *-layer.ts with 18 769 lines; 52 of 77 bake modules mention neighbours, seams or margins; bootApp 3 088 lines

Beside them, counted but not an aim of its own: a phone's memory (ADR 0047 stays — it must not grow), the repository's size (data/ 937 MB, the pack 1.2 GiB after eighteen days) and the build's time (prepare-sites cold 360 s).

The maintainer's rulings (2026-11-16)

  1. Official data first stays (ADR 0012): LoD2 and the surface model before OpenStreetMap. A base level from global data (OSM buildings, GLO-30) for any place on earth was offered and declined for now.
  2. The newest versions of the dependencies stay, unless something grave speaks against one. A "novelty budget" (new only where the product needs it) was offered and declined. Consequence for the series: every bump of three is a risk to the look, which plan 087's plates exist to catch; and plan 094 waits for what upstream does with compileAsync before it builds machinery around it.

The plans, in the order they go

PlanWhat is true afterwardsEffortNeeds
087Reference views rendered on a real GPU and compared with main rendered on the same machine (no reference image is stored); one ledger of bytes, requests, counters, first-load JavaScript and a phone's tile bytes that gates CI and that every later plan writes its before and after into (timings are recorded, never gated); published tilesets compared by contentM, plus a machine with a GPU that keeps running—
088The tileset is published to a store under its content hashes; a lock file in git names what a commit runs on; the web build bakes nothing; data/ leaves git but for a fixture; one transport encoding in place of the pre-gzipped files, if its spike measures a gainM, plus storage and traffic every month; three decisions of the maintainer first087
089The bakes are type-checked in CI against a baseline that only shrinksM (the checker and its baseline: S)—
090A tile's dressing arrives in the layout the GPU draws from: instance tables, line tables, baked parts; the viewer places nothing, slices nothing and parses no GeoJSONL, a layer at a time087; 088 for the byte gates
091Exact rasters (class ids, tables, packed channels) travel as plain arrays in their texture's layout, so the viewer carries no PNG decoder; a trial of block compression on one soft raster decides the others; fewer files and bindings a levelS for the table and the trial, M–L for what the numbers carry087, 088; 090 for the NDVI
092The bakes read and write through one store — by extent, by owner — over site-wide typed tables of the vector features (rasters stay cut by window with a halo) and cut tiles at publishing; a step never rewrites another's file; one schema says what both languages read; the format decided by a spikeL–XL, with a full re-bake of every site087, 088, 089; leans on 090
093The stream's tile is smaller than the bake's: an explicit quadtree under each bake tile whose levels replace the raster twins — built only if a phone's numbers after 090 and 091 still ask for it, and only if a spike on one tile passes its kill criteriaXL, the series' largest risk087, 088, 090, 091, 092, 094
094The clay's vertex buffers and inter-stage variables are counted by a test; every material variant is known at boot, and a flight builds no pipeline after itS now, M before 093 (cheaper after 090 and 091)087
095The viewer is a package with one entrance; data-frame and scene-frame coordinates are different types; bootApp is owners, not one functionM–L, last090, 093
096Each bake heuristic that guesses (roofs, dormers, windows, crowns) has a reference set and a score a bake PR must holdM a family, open-ended087

Order: 087 first, then 088 and 089's checker side by side, then 090 a layer at a time with 091's trial beside it, then 092, then the decision on 093. 089's edits to the bake modules wait until just before 092's re-bake: a step's key hashes its module's bytes (step_cache.code_hash), so an annotation re-runs that step on every tile of every site. 094's counting test goes at any time; 095's frame types too, the rest of 095 last; 096 runs beside everything.

What each plan may assume of the others

The series is built whole. A plan is therefore written for the state the others leave, not for today's alone. These are the joints.

  1. Measure first. Nothing that changes the picture merges before 087's plates exist, and every plan writes its numbers into 087's ledger. A plate is compared with main rendered on the same machine, so no reference image is kept anywhere; a PR with a Snapshots section claims a change and the plates report it, a PR without one claims none and a differing view fails it. The reason is the series' own history: PR #156 (plan 074 part A's spike) has waited since 2026-10-11 for a look on a real GPU, and plan 019 since September.
  2. Data leaves git before a binary hand-over format enters it (088 before 092). GeoJSON's one merit is the diff a re-bake shows in git; a binary table in git has neither a diff nor a delta. Which format it is, 092's spike decides: the pinned GDAL wheel writes FlatGeobuf and GeoPackage but no Parquet, and GeoJSON under the one schema is the fallback.
  3. Bake where a thing stands, never how it looks (090). Colour, season, picture style and the palette stay at runtime (ADRs 0010, 0012: "a colour change is not a re-bake"). A baked record is semantic — place, size, turn, kind, genus — and the shader makes the look of it.
  4. A file's layout is the GPU's layout (090, 091). What a tile brings is uploaded, not rebuilt: an instance is the compact record the vertex shader expands, not sixteen floats written on the CPU.
  5. Bake what is compact, not what is large. PR #156 measured it: rails, trams and riverside baked as triangles made Dresden's fine levels 10.1 % larger (+3 MB) while halving the dressing's build. The series aims at both, so 090 prefers a table the GPU expands (an instance, a line's segment) over baked triangles, and leaves what is large and derived — a BVH, a height index — to the workers that build it today. Areas and irregular solids (ballast, platforms, piers, basins) have no table smaller than their triangles: they are baked nodes, each kind behind a stop on the level's bytes.
  6. No worker pool. Earlier advice named one ("the render thread builds nothing"). With 090 the scene's thread has nothing left to build; the slices (lib/city/build-steps.ts) go with the last runtime builder, and the three workers there are (BVH, ground, window niches) stay. A pool would be built for work 090 deletes.
  7. One reader a kind (090 for 092). 090 puts every read of a bake's file in the build behind one reader a kind, so that 092 changes the format in one place and not in every baker a second time.
  8. Format, site-wide tables and steps that overwrite nothing are one plan (092): all three rewrite the same input and output layer of every bake step. Together they cost less than apart. The proof this repository leans on — "a cold bake publishes 0 new files" — holds through 092's schema, its own-output rule, its store and even its change of format; only the last step, windows in place of tiles, changes published bytes by design, and there a comparison by content takes over: 087 compares two published tilesets, 092 its own tables with today's files, and 087's plates watch the seams.
  9. The quadtree is decided by numbers, not by this file (093). It needs 092 (or every cut is sixteen times the seams), 090's one container a tile (or sixteen times the requests), 091 (levels in place of raster twins) and 094's register (more tiles arriving a second). Plan 076 rejected implicit tiling "for now (15 tiles)", and 093 does not bring it back: the installed library's implicit tiling keeps one content a tile and addresses by template, against our hashed names, so the tree is explicit. What 093 reopens, under a gate, is the smaller tile: what a phone still pays after 090 and 091.
  10. Raw rasters pay only with 088 (091): without a transport encoding a pre-gzipped array is a PNG by another name. 088 measures first what an encoding saves over files that are gzipped at level 9 already, and builds it only on a gain. Measured on one tile for 091: a plain array is smaller than its PNG for the exact rasters and a third larger for the fields unless a row predictor comes first — PNG's filters are one.
  11. Packages follow the seams the other plans leave (095). Regrouping 699 files first would cross every open PR; after 090 the viewer's edge is where the builders left. A move re-keys every bake (the cache key hashes a module's path), so its proof is a build that publishes 0 new files.
  12. Block compression is the small lever (091). The first advice called GPU-compressed textures the largest unused one; 091's table says otherwise: the rasters that tolerate it (NDVI, sky view, horizon) are 4.7 MiB of the 40–60 MiB a phone holds for a fine level, and three's KTX2 path saves nothing on a one-channel raster. The weight is in the id rasters, which stay exact, and in the colour splat painted from them. So 091 leads with plain arrays and fewer bindings and keeps compression to a trial.

Plans this series touches

  • 074 part A (bake the static dressing) and its spike PR #156: taken over by 090, which starts from the spike's numbers.
  • 019 (the GPU checklist): 087 turns its reference views into compared plates and rewrites ADR 0018, which rejects pixel comparison — on SwiftShader, where it stays rejected; whether a picture is good, the two phones and the deploy host stay 019's.
  • 070 (raster diet, partial) and 074's backlog item "one raster stack per tile": continued by 091. 076's and 077's rejection of KTX2 stands for every exact raster (block compression would change ids); 091 tries blocks on one soft raster and lets the numbers decide.
  • 069 (streaming without stalls, partial): its open steps are re-read once 090 has taken the dressing off the tile path.
  • 021 (/wissen as a workspace package): 095 names the workspace's shape, 021 stays its own plan.
  • 017 (Germany-wide sites): untouched; 092 keeps the provider adapters' five functions.

Considered and left out

Kept here and in the README's Rejected list so nobody audits them again.

  • Rust for the bakes. The bakes are heuristics on rasters and vectors, run rarely on the maintainer's machine and cached a step; rasterio, pyogrio and shapely bring GDAL in their wheels with no system set-up. Rust would cost that and solve nothing measured.
  • Rust for the TypeScript build. 58 of lib/city's 211 modules (20 236 of 56 803 lines; counted over the import graph on 2026-11-16) run in the build and in the viewer — windows.ts, terrain-tin.ts, city-mesh.ts, levels.ts. One language is why the facade's packing and the shader that reads it agree. The build's memory (1.3–1.9 GiB a tile) stops binding once 088 takes the bake out of the host's builder; a hot loop that still matters gets a native kernel, not a port.
  • Rust and wgpu for the viewer, or a renderer of our own. Loses TSL (and returns to shaders as strings, which ADR 0027 left), GLTFLoader, 3DTilesRendererJS, three-mesh-bvh and the design loaders.
  • WebAssembly as the platform. The costs a tile has on a phone are functions of its data: bake them (090) or let the GPU expand them. A WebAssembly heap never shrinks (tile-stream.ts says so of the meshopt workers), against ADR 0047. It stays where it is: decoders.
  • A base level from global data, a novelty budget: the maintainer's rulings above.
  • A worker pool: joint 6.

Closing the series

A plan that is done is condensed into completed.md as every plan is; its row keeps the [rewrite] mark. When the last one closes, this file's table goes to completed.md with each plan's ledger figures, and this file is deleted.

Previous
Completed plans — condensed records
Next
Plan 017: Any German city — the open half: a second Land, NAS input, OSM land cover, a site check
Source on GitHub: docs/plans/086-rewrite-programme.md
On this page
  • Where it comes from
  • The three aims, and how each is counted
  • The maintainer's rulings (2026-11-16)
  • The plans, in the order they go
  • What each plan may assume of the others
  • Plans this series touches
  • Considered and left out
  • Closing the series