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
  • 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
  • What the data streams carry that the walker does not use yet
Guide (English) · 5 / 7

From download to browser

Deutsch: Der Weg der Daten

This page follows the data from the provider's portal to the pixels on your screen. It answers four questions people ask about a project like this: where is the truth kept, what is a derivative, what does the browser actually download, and what has to be redone when a source changes. Abbreviations are in the glossary.

The six stations

download (manual or scripted)

bake (manual)

commit

bun dev / bun run build

HTTP, cached forever

1 · Provider portals
geodaten.sachsen.de · OpenStreetMap
the source of truth for the world

2 · Raw downloads — data/_raw/
gigabytes · on the maintainer's disk only
never in the repository

3 · Bakes — pipeline/ · bun run bake <site>
run by hand per tile · one Python package
clip, classify, sample, simplify

4 · Committed derivatives — data/
small per-tile files in the repository
the source of truth for what the app shows

5 · Build step — scripts/prepare-data.ts
runs before every dev server and build
bakes a 3D Tiles tileset per city into public/data/

6 · Browser
streams the tiles the camera sees
draws everything on the graphics card

Two of the arrows are manual and happen rarely (a new download, a changed bake); the last two happen automatically on every build and every visit.

Station 1 — the provider portals

The Saxon survey office and OpenStreetMap own the data. If the city changes, it changes there first. The project keeps a snapshot; see the edition table for how old each snapshot is.

Station 2 — raw downloads (data/_raw/, not committed)

The bulk downloads are large: the statewide landscape model is several gigabytes, an aerial-photo tile is hundreds of megabytes, the OpenStreetMap extract for Saxony is about 250 MB. They live in a folder the version control system ignores, one subfolder per data provider and source (data/_raw/sn/dom1, …/dop, …/dlm, …/osm for Saxony — every Saxon place shares them). Anyone can re-download them — bun run fetch dresden does it in one go — and nobody needs them to run the viewer.

The one exception is the terrain model: its GeoTIFF is committed (13.6 MB per tile) because the build step in station 5 reads it directly and two bakes need it as well. This is a deliberate decision (ADR 0037).

Station 3 — the bakes (manual, per tile)

One Python package, pipeline/bake/, turns the raw downloads into small, tile-sized files. It runs on the maintainer's machine with one command, bun run bake dresden, which reads the site config (sites/dresden.ts: which tiles, where they lie, which coordinate system) and runs seven steps per tile. The Python environment is pinned, and its geodata libraries bring GDAL with them, so nothing else has to be installed. Before it, bun run fetch dresden fetches the downloads themselves: every product of each tile from the survey office (the building model converted to CityJSON on the way), the statewide landscape model, and the OpenStreetMap extract from Geofabrik. Which place — and so which survey office — is the first word after the command: dresden, leipzig, unna, …

The steps run in a fixed order, because some read the output of an earlier one:

landcover
land-use classes + hedge rows

canopy
tree points

lamps
lamp points

furniture
benches · bins · stands · shelters

ndvi
greenness raster

roof-colour
roof colour table

walls
wall lines

monuments
fountains · statues · stones

stairs
flights of steps

rail
tracks · overhead-line masts · ballast · bridges · platforms

Each step says what it "sees" in the raw data and how it simplifies it. When the surface model or the aerial photo of a tile is missing, the steps that need it (trees, greenness, roof colours) are skipped with a note instead of failing. The developer page data-pipeline.md documents every step's inputs, outputs and tuning knobs.

Station 4 — the committed derivatives (data/)

This folder is what the repository actually guarantees. Everything the viewer shows is either in it or is computed from it. It holds, per tile:

FolderFilesWhat they areSize per tile
data/dresden/dgm/dgm1_<tile>.tif + .tfw + _akt.csvthe terrain model as downloaded (the exception above)13.6 MB
data/dresden/cityjson/lod2_<tile>.city.jsonthe building model, converted to CityJSON8–11 MB
data/dresden/dlm/landcover_<tile>.png + .jsonland-use class per half-metre pixel (4096²), with a legend; the file holds class numbers only, the colours are added in the browser0.2 MB
ndvi_<tile>.pnggreenness index from the aerial photo, 1024²0.3–0.5 MB
vegrows_<tile>.geojsonhedge and tree-row linesa few kB
canopy_<tile>.geojsonone point per tree with its height (5,000–16,000 per tile)0.6–1.8 MB
lamps_<tile>.geojsonlamp positionsup to 60 kB
furniture_<tile>.geojsonbenches, bins, bicycle stands, bollards, post boxes and shelters, each with the way it faces50–180 kB
monuments_<tile>.geojsonfountain basins and monument points with kind and official name2–55 kB
walls_<tile>.geojsonwall lines with kind and height, then the fences and railings (with their kind) and the gates on them130–290 kB
stairs_<tile>.geojsonflights of steps: axis, width, step count, the heights at foot and heada few kB
terraces_<tile>.geojsonraised areas the terrain model lacks (the Brühlsche Terrasse) with their levela few kB
rail_<tile>.geojson, railarea_<tile>.geojsontrack lines, one per track, with gauge, electrification and the overhead-line masts beside them; dissolved ballast areasa few kB
bridge_<tile>.geojsonbridge deck outlines with a height per corner, kind and structurea few kB
platform_<tile>.geojsonstation platforms with their heighta few kB
osmbuild_<tile>.jsonper building: a shop or café on the ground floor, listed15–40 kB
data/dresden/dop/roofcolor_<tile>.jsonone colour per building, sampled from the aerial photo0.2 MB

In total the repository carries about 400 MB of data for the fifteen tiles.

Single source of truth versus derivative, at a glance:

Layer in the viewerTruth (provider)Committed in the repoProduced at build timeSent to the browser
GroundDGM1 GeoTIFFthe GeoTIFF itselftwo terrain meshes per tile (a detailed and a coarse one), with the walls sharpened in, as glTFthe mesh the camera needs
BuildingsLoD2 CityGMLthe CityJSON conversionone glTF building mesh per tile with a table of per-building style values (roof colour folded in), plus the footprints for the minimapmesh + footprints
Ground coloursBasis-DLM shapefilesthe land-use class PNG and its legenda half-size (2048²) copy for phones and distant terrain, and a small 512² one for the minimapthe class PNGs; the colours are painted in the browser
TreesBasis-DLM + DOM1 + DGM1tree points, hedge rows—as committed
GreennessDOPthe NDVI PNG—as committed
Roof coloursDOP + LoD2the roof colour tablefolded into the building mesh's tableinside the building mesh
Shop fronts, listed buildingsOpenStreetMap + LoD2the per-building tablefolded into the building mesh's tableinside the building mesh
Monuments and fountainsBasis-DLM (names, positions) + OpenStreetMap (basins)the GeoJSON files—as committed
Lamps, platforms, bridge structureOpenStreetMapthe GeoJSON files—as committed
Walls, fences, stairs, terracesOpenStreetMap + DGM1the GeoJSON filesbuilt into the detailed terrain mesh: the ground shaped along and under them, the walls, fences and steps as part of the meshinside the terrain mesh
Rails, ballast, bridgesOpenStreetMap + Basis-DLM (+ DOM1/DGM1 for heights and widths)the GeoJSON files—as committed

Station 5 — the build step (scripts/prepare-data.ts)

Every bun dev and bun run build starts by running it — once for every city whose data is on disk (scripts/prepare-sites.ts decides which), and it writes each city into a folder of its own, public/data/dresden/, public/data/leipzig/, … For each city it does three things:

  1. Bakes the heavy inputs into a tileset. For every tile, the terrain GeoTIFF becomes two ready-made terrain meshes: a detailed one, a triangulated irregular network (TIN) that follows the 1 m elevation model within ±15 cm — more triangles where the ground bends — and a coarse one on a 512 × 512 grid, with the tall walls from OpenStreetMap sharpened in, the ground shaped under its stairs and the steps themselves built in, and a short skirt hanging from its edge so no gap shows at the seams between tiles. The CityJSON becomes one building mesh per tile with a table of per-building style values, and a list of building footprints for the minimap. Every mesh is written as glTF, the standard file format for 3D models, compressed and gzipped: about 1.1–1.5 MB of buildings, 1.5–2.0 MB of detailed and 0.4–0.55 MB of coarse terrain per tile, instead of the 13.6 MB GeoTIFF and the 8–11 MB CityJSON. A small index file, tileset.json, in the open 3D Tiles format, lists every tile's buildings and its two terrain levels, and says from how close the detailed level replaces the coarse one. The land-use class PNG gets a 2048² and a 512² copy. Results are cached in .cache/ and only redone when an input or the bake code changed.
  2. Publishes every file into the city's folder under a name that contains a fingerprint of its content (for example canopy_33412_5656_2_sn.55a26a2d.geojson), and writes a manifest.json that maps the plain names to the fingerprinted ones.
  3. Prunes files the manifest no longer mentions, so a removed source really switches its feature off instead of lingering.

The fingerprinted names allow the browser to cache every data file forever; only the tiny manifest is re-checked on each visit. A re-bake changes fingerprints, and the new manifest points at the new files.

Last, a short list of the cities that were built, public/data/sites.json, is written next to their folders. The start page shows one card per entry (with the city's land-cover map, painted from the same colours as the ground), and every entry gets its own address: /dresden, /leipzig, … A city whose data is not on the machine that builds is simply not listed.

Station 6 — the browser

The address says which city: at /dresden the browser fetches Dresden's manifest (/data/dresden/manifest.json) and its tileset, then streams: a library called 3DTilesRendererJS decides, from where the camera stands and where it looks, which files to fetch. The first picture waits only for the buildings and the terrain of the tile you start on. Tiles near the camera get the detailed terrain — with their walls and stairs already built in — and are then dressed with trees, lamps and rails; tiles further away show their buildings on the coarse terrain; tiles out of sight are not fetched, and tiles you have left behind can be dropped from memory again. Measured on the current data (compressed size, as sent over the network):

WhatStart tileOther tilesFetched when
Buildings (with the style table)1.34 MBup to 1.91 MBthe tile is in view
Building footprints (minimap)48 kBup to 75 kBwith the buildings
Coarse terrain (512²)0.41 MB0.44–0.65 MBthe tile is in view
Detailed terrain (a TIN, with its walls, stairs and kerb stones)1.61 MB1.31–3.56 MBthe camera comes close
Land-use classes, 512²15 kB9–18 kBat the start, for the minimap
Land-use classes, 2048²0.08 MB0.06–0.11 MBwith the coarse terrain (on phones with every level)
Land-use classes, 4096²0.22 MB0.15–0.29 MBwith the detailed terrain (desktop only)
Greenness (NDVI)0.39 MB0.32–0.77 MBwith the terrain
Tree points36 kB41–526 kBwith the detailed terrain
Street furniture19 kB0.3–19 kBwith the detailed terrain
Lamps, rails, ballast, bridges, platforms, hedge rowsunder 5 kB eachunder 5 kB eachwith the detailed terrain
Paving and road-edge rasters2.18 MB0.28–2.76 MBwith the detailed terrain
Per tile, in full detail≈ 6.4 MB≈ 4.0–9.7 MB
Per tile, as distant backdrop≈ 2.3 MB≈ 1.3–3.3 MB

How much a visit downloads therefore depends on where you go. With every tile in full detail, a desktop has fetched about 97 MB for the fifteen tiles; a phone about 95 MB (it takes the 2048² land-use raster for every tile); the test-only "lite" profile, which streams the start tile alone, about 6 MB. That is more than before the switch to streaming (a full visit used to be about 10.6 MB), because the terrain now arrives as a ready-made mesh instead of a compact grid of heights; in exchange every file is in a standard format that common 3D tools can open.

What is never sent: the 13.6 MB terrain GeoTIFF, the 10 MB CityJSON, and any of the raw downloads. The browser parses no CityJSON and builds no terrain; it receives meshes it can draw directly, plus small images and feature files.

What is computed in the browser rather than downloaded: the ground colours (painted once per tile on the graphics card, from the land-use classes and one pastel palette), the water surface, every tree from its point and height, lamp posts and benches from their points, bridges from their outlines, the sun position, all lighting and shadows, and the whole post-processing look.

What has to be redone when something changes

ChangeManual stepsAutomatic
New terrain editionreplace the GeoTIFF in data/<site>/dgm/ (or delete it and bun run fetch <site>); re-run the canopy and rail bakes (they read it)the terrain meshes, walls included, are re-baked on the next build
New building modeldelete the CityJSON in data/<site>/cityjson/ and bun run fetch <site> (it converts the new CityGML); re-run the roof-colour bakethe building mesh is re-baked on the next build
New land-use editionfetch the new package, re-run the landcover bake, then canopy, lamps, furniture, rail and tram (they read the class raster)the 2048² and 512² copies are re-baked
New aerial photosre-run the ndvi and roof-colour bakesthe roof colours are folded into the mesh on the next build
New OpenStreetMap datadownload a fresh Geofabrik extract and re-run the lamps, furniture, monuments, osm-buildings, walls, stairs, rail and tram bakes—
Different ground coloursedit the one palette in the codenothing to re-bake: the browser paints the colours
A new tileadd it to the site config (sites/dresden.ts); bun run fetch <site> downloads everything for it, the building model converted to CityJSON on the way; bun run bake <site> runs all seven bakesthe build adds it to the tileset and publishes it

Why it is built this way

Doing the heavy work once, offline, keeps the viewer a plain static website: no server, no database, no API keys, and a first picture within a few seconds even on a phone. Keeping the small derivatives in the repository means anyone can build and run the viewer without the gigabytes of raw data, and every change to what the viewer shows is visible in the version history. The trade-offs are written down in the architecture decision records.

Previous
How the viewer comes by what it shows
Next
Using the viewer
Source on GitHub: docs/guide/en/data-journey.mdDeutsche Fassung →
On this page
  • The six stations
  • Station 1 — the provider portals
  • Station 2 — raw downloads (data/_raw/, not committed)
  • Station 3 — the bakes (manual, per tile)
  • Station 4 — the committed derivatives (data/)
  • Station 5 — the build step (scripts/prepare-data.ts)
  • Station 6 — the browser
  • What has to be redone when something changes
  • Why it is built this way