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
Inhalt
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
Leitfaden · 5 / 7

Der Weg der Daten

English: From download to browser

Diese Seite folgt den Daten vom Portal des Anbieters bis zu den Pixeln auf deinem Bildschirm. Sie beantwortet vier Fragen, die man bei so einem Projekt stellt: wo liegt die Wahrheit, was ist ein Derivat, was lädt der Browser tatsächlich herunter und was muss neu gemacht werden, wenn sich eine Quelle ändert. Abkürzungen stehen im Glossar.

Die sechs Stationen

Download (manuell oder per Skript)

Bake (manuell)

Commit

bun dev / bun run build

HTTP, dauerhaft gecacht

1 · Portale der Anbieter
geodaten.sachsen.de · OpenStreetMap
die Wahrheit über die Welt

2 · Rohdownloads — data/_raw/
Gigabytes · nur auf der Festplatte des Betreibers
nie im Repository

3 · Bakes — pipeline/ · bun run bake <ort>
von Hand je Kachel · ein Python-Paket
ausschneiden, klassifizieren, abtasten, vereinfachen

4 · Eingecheckte Derivate — data/
kleine Dateien je Kachel im Repository
die Wahrheit darüber, was die App zeigt

5 · Build-Schritt — scripts/prepare-data.ts
läuft vor jedem Dev-Server und Build
backt je Stadt ein 3D-Tiles-Tileset nach public/data/

6 · Browser
streamt die Kacheln, die die Kamera sieht
zeichnet alles auf der Grafikkarte

Zwei der Pfeile sind manuell und selten (ein neuer Download, ein geändertes Bake); die letzten beiden passieren automatisch bei jedem Build und jedem Besuch.

Station 1 — die Portale der Anbieter

Die sächsische Landesvermessung und OpenStreetMap besitzen die Daten. Wenn sich die Stadt ändert, ändert sie sich zuerst dort. Das Projekt hält einen Schnappschuss; wie alt jeder ist, steht in der Stände-Tabelle.

Station 2 — Rohdownloads (data/_raw/, nicht eingecheckt)

Die Rohdownloads sind groß: das landesweite Landschaftsmodell mehrere Gigabyte, eine Luftbildkachel hunderte Megabyte, der OpenStreetMap-Auszug für Sachsen etwa 250 MB. Sie liegen in einem Ordner, den die Versionsverwaltung ignoriert, mit einem Unterordner je Datenanbieter und Quelle (data/_raw/sn/dom1, …/dop, …/dlm, …/osm für Sachsen — alle sächsischen Orte teilen sie). Jeder kann sie neu herunterladen — bun run fetch dresden erledigt das in einem Rutsch —, und niemand braucht sie, um den Viewer zu betreiben.

Die eine Ausnahme ist das Geländemodell: Sein GeoTIFF ist eingecheckt (13,6 MB je Kachel), weil der Build-Schritt in Station 5 es direkt liest und zwei Bakes es ebenfalls brauchen. Das ist eine bewusste Entscheidung (ADR 0037, englisch).

Station 3 — die Bakes (manuell, je Kachel)

Ein Python-Paket, pipeline/bake/, verwandelt die Rohdownloads in kleine, kachelgroße Dateien. Es läuft auf dem Rechner des Betreibers mit einem einzigen Befehl, bun run bake dresden, der die Standort-Konfiguration liest (sites/dresden.ts: welche Kacheln, wo sie liegen, welches Koordinatensystem) und je Kachel sieben Schritte ausführt. Die Python-Umgebung ist festgeschrieben, und ihre Geodaten-Bibliotheken bringen GDAL gleich mit, sodass nichts weiter installiert werden muss. Davor holt bun run fetch dresden die Downloads selbst: jedes Produkt jeder Kachel von der Landesvermessung (das Gebäudemodell unterwegs nach CityJSON umgewandelt), das landesweite Landschaftsmodell und den OpenStreetMap-Auszug von Geofabrik. Welcher Ort — und damit welche Landesvermessung — sagt das erste Wort nach dem Befehl: dresden, leipzig, unna, …

Die Schritte laufen in fester Reihenfolge, weil manche die Ausgabe eines früheren lesen:

landcover
Landnutzungsklassen + Heckenreihen

canopy
Baumpunkte

lamps
Lampenpunkte

furniture
Bänke · Papierkörbe · Bügel · Wartehäuschen

ndvi
Grün-Raster

roof-colour
Dachfarben-Tabelle

walls
Mauerlinien

monuments
Brunnen · Denkmäler · Steine

stairs
Treppenläufe

rail
Gleise · Oberleitungsmasten · Schotter · Brücken · Bahnsteige

Jeder Schritt beschreibt, was er in den Rohdaten „sieht“ und wie er vereinfacht. Fehlen für eine Kachel Oberflächenmodell oder Luftbild, werden die Schritte, die sie brauchen (Bäume, Grün, Dachfarben), mit einem Hinweis übersprungen, statt abzubrechen. Die Entwicklerseite data-pipeline.md (englisch) dokumentiert Eingaben, Ausgaben und Stellschrauben jedes Schritts.

Station 4 — die eingecheckten Derivate (data/)

Dieser Ordner ist das, was das Repository tatsächlich garantiert. Alles, was der Viewer zeigt, liegt entweder hier oder wird daraus berechnet. Er enthält je Kachel:

OrdnerDateienWas sie sindGröße je Kachel
data/dresden/dgm/dgm1_<Kachel>.tif + .tfw + _akt.csvdas Geländemodell wie heruntergeladen (die Ausnahme von oben)13,6 MB
data/dresden/cityjson/lod2_<Kachel>.city.jsondas Gebäudemodell, nach CityJSON umgewandelt8–11 MB
data/dresden/dlm/landcover_<Kachel>.png + .jsonLandnutzungsklasse je Halbmeter-Pixel (4096²), mit Legende; die Datei enthält nur Klassennummern, die Farben kommen erst im Browser dazu0,2 MB
ndvi_<Kachel>.pngGrünindex aus dem Luftbild, 1024²0,3–0,5 MB
vegrows_<Kachel>.geojsonHecken- und Baumreihenlinienwenige kB
canopy_<Kachel>.geojsonein Punkt je Baum mit Höhe (5 000–16 000 je Kachel)0,6–1,8 MB
lamps_<Kachel>.geojsonLampenpositionenbis 60 kB
furniture_<Kachel>.geojsonBänke, Papierkörbe, Fahrradbügel, Poller, Briefkästen und Wartehäuschen, jeweils mit ihrer Blickrichtung50–180 kB
monuments_<Kachel>.geojsonBrunnenbecken und Denkmalpunkte mit Art und amtlichem Namen2–55 kB
walls_<Kachel>.geojsonMauerlinien mit Art und Höhe, dazu die Zäune und Geländer (mit Bauart) und die Tore darauf130–290 kB
stairs_<Kachel>.geojsonTreppenläufe: Achse, Breite, Stufenzahl, Höhe an Fuß und Kopfwenige kB
terraces_<Kachel>.geojsonerhöhte Flächen, die dem Geländemodell fehlen (die Brühlsche Terrasse), mit ihrer Höhewenige kB
rail_<Kachel>.geojson, railarea_<Kachel>.geojsonGleislinien, eine je Gleis, mit Spurweite, Elektrifizierung und den Oberleitungsmasten daneben; verschmolzene Schotterflächenwenige kB
bridge_<Kachel>.geojsonBrückendeck-Umrisse mit Höhe je Ecke, Art und Tragwerkwenige kB
platform_<Kachel>.geojsonBahnsteige mit ihrer Höhewenige kB
osmbuild_<Kachel>.jsonje Gebäude: Laden oder Café im Erdgeschoss, Baudenkmal15–40 kB
data/dresden/dop/roofcolor_<Kachel>.jsoneine Farbe je Gebäude, aus dem Luftbild abgetastet0,2 MB

Insgesamt trägt das Repository etwa 400 MB Daten für die fünfzehn Kacheln.

Eine Wahrheit gegenüber Derivat, auf einen Blick:

Schicht im ViewerWahrheit (Anbieter)Im Repository eingechecktBeim Build erzeugtAn den Browser gesendet
GeländeDGM1-GeoTIFFdas GeoTIFF selbstzwei Geländenetze je Kachel (ein detailliertes und ein grobes), mit eingearbeiteten Mauerkanten, als glTFdas Netz, das die Kamera gerade braucht
GebäudeLoD2-CityGMLdie CityJSON-Umwandlungein glTF-Gebäudenetz je Kachel mit einer Tabelle von Stilwerten je Gebäude (Dachfarbe eingearbeitet), dazu die Grundrisse für die MinikarteNetz + Grundrisse
BodenfarbenBasis-DLM-Shapefilesdas Landnutzungsklassen-PNG mit Legendeeine halb so große Kopie (2048²) für Handys und ferne Geländeteile und eine kleine (512²) für die Minikartedie Klassen-PNGs; die Farben malt der Browser
BäumeBasis-DLM + DOM1 + DGM1Baumpunkte, Heckenreihen—wie eingecheckt
GrünDOPdas NDVI-PNG—wie eingecheckt
DachfarbenDOP + LoD2die Dachfarben-Tabellein die Tabelle des Gebäudenetzes eingearbeitetim Gebäudenetz
Ladenfronten, BaudenkmaleOpenStreetMap + LoD2die Tabelle je Gebäudein die Tabelle des Gebäudenetzes eingearbeitetim Gebäudenetz
Denkmäler und BrunnenBasis-DLM (Namen, Lage) + OpenStreetMap (Becken)die GeoJSON-Dateien—wie eingecheckt
Lampen, Bahnsteige, BrückentragwerkOpenStreetMapdie GeoJSON-Dateien—wie eingecheckt
Mauern, Zäune, Treppen, TerrassenOpenStreetMap + DGM1die GeoJSON-Dateienins detaillierte Geländenetz eingebaut: der Boden an und unter ihnen geformt, Mauern, Zäune und Stufen Teil des Netzesim Geländenetz
Gleise, Schotter, BrückenOpenStreetMap + Basis-DLM (+ DOM1/DGM1 für Höhen und Breiten)die GeoJSON-Dateien—wie eingecheckt

Station 5 — der Build-Schritt (scripts/prepare-data.ts)

Jedes bun dev und bun run build beginnt damit, dieses Skript auszuführen — einmal für jede Stadt, deren Daten auf der Platte liegen (scripts/prepare-sites.ts entscheidet, welche), und jede Stadt bekommt ihren eigenen Ordner, public/data/dresden/, public/data/leipzig/, … Für jede Stadt tut es drei Dinge:

  1. Backt die schweren Eingaben zu einem Tileset. Für jede Kachel wird das Gelände-GeoTIFF zu zwei fertigen Geländenetzen: einem detaillierten als unregelmäßiges Dreiecksnetz (TIN), das dem 1-m-Höhenmodell auf ±15 cm folgt – mehr Dreiecke, wo sich der Boden krümmt –, und einem groben auf einem Raster von 512 × 512 Punkten – mit den hohen Mauern aus OpenStreetMap als scharfen Kanten, mit den Treppen samt passend geformtem Boden darunter und mit einer kurzen Schürze am Rand, damit an den Nahtstellen zwischen Kacheln keine Lücke sichtbar wird. Das CityJSON wird zu einem Gebäudenetz je Kachel mit einer Tabelle von Stilwerten je Gebäude, dazu einer Liste der Gebäudegrundrisse für die Minikarte. Jedes Netz wird als glTF geschrieben, das Standardformat für 3D-Modelle, komprimiert und gezippt: etwa 1,1–1,5 MB Gebäude, 1,5–2,0 MB detailliertes und 0,4–0,55 MB grobes Gelände je Kachel, statt des 13,6-MB-GeoTIFFs und des 8–11-MB-CityJSONs. Eine kleine Indexdatei, tileset.json, im offenen 3D-Tiles-Format, listet für jede Kachel die Gebäude und die zwei Geländestufen und legt fest, ab welcher Nähe die detaillierte Stufe die grobe ersetzt. Das Landnutzungsklassen-PNG bekommt eine 2048²- und eine 512²-Kopie. Ergebnisse werden in .cache/ zwischengespeichert und nur neu erzeugt, wenn sich eine Eingabe oder der Bake-Code geändert hat.
  2. Veröffentlicht jede Datei in den Ordner der Stadt unter einem Namen, der einen Fingerabdruck ihres Inhalts trägt (zum Beispiel canopy_33412_5656_2_sn.55a26a2d.geojson), und schreibt eine manifest.json, die die einfachen Namen auf die Namen mit Fingerabdruck abbildet.
  3. Räumt auf, was das Manifest nicht mehr nennt, damit eine entfernte Quelle ihr Feature wirklich abschaltet, statt weiterzuleben.

Die Namen mit Fingerabdruck erlauben dem Browser, jede Datendatei dauerhaft zu cachen; nur das winzige Manifest wird bei jedem Besuch neu geprüft. Ein neues Bake ändert die Fingerabdrücke, und das neue Manifest zeigt auf die neuen Dateien.

Zuletzt schreibt der Build neben die Ordner eine kurze Liste der gebauten Städte, public/data/sites.json. Die Startseite zeigt je Eintrag eine Karte (mit der Landnutzungskarte der Stadt, gemalt in denselben Farben wie der Boden), und jeder Eintrag bekommt seine eigene Adresse: /dresden, /leipzig, … Eine Stadt, deren Daten nicht auf dem Rechner liegen, der baut, erscheint einfach nicht.

Station 6 — der Browser

Die Adresse sagt, welche Stadt: Unter /dresden holt der Browser das Manifest Dresdens (/data/dresden/manifest.json) und sein Tileset und streamt dann: Eine Bibliothek namens 3DTilesRendererJS entscheidet danach, wo die Kamera steht und wohin sie schaut, welche Dateien geladen werden. Das erste Bild wartet nur auf Gebäude und Gelände der Kachel, auf der du startest. Kacheln nahe der Kamera bekommen das detaillierte Gelände – Mauern und Treppen sind darin schon eingebaut – und werden dann mit Bäumen, Lampen und Gleisen ausgestattet; weiter entfernte Kacheln zeigen ihre Gebäude auf dem groben Gelände; Kacheln außer Sicht werden gar nicht geladen, und Kacheln, die du hinter dir gelassen hast, können wieder aus dem Speicher fallen. Gemessen an den aktuellen Daten (komprimierte Größe, wie über das Netz gesendet):

WasStartkachelAndere KachelnGeladen, wenn
Gebäude (mit Stiltabelle)1,34 MBbis 1,91 MBdie Kachel im Blick ist
Gebäudegrundrisse (Minikarte)48 kBbis 75 kBmit den Gebäuden
Grobes Gelände (512²)0,41 MB0,44–0,65 MBdie Kachel im Blick ist
Detailliertes Gelände (ein TIN, mit seinen Mauern, Treppen und Bordsteinen)1,61 MB1,31–3,56 MBdie Kamera nahe kommt
Landnutzungsklassen, 512²15 kB9–18 kBbeim Start, für die Minikarte
Landnutzungsklassen, 2048²0,08 MB0,06–0,11 MBmit dem groben Gelände (auf Handys mit jeder Stufe)
Landnutzungsklassen, 4096²0,22 MB0,15–0,29 MBmit dem detaillierten Gelände (nur Desktop)
Grün (NDVI)0,39 MB0,32–0,77 MBmit dem Gelände
Baumpunkte36 kB41–526 kBmit dem detaillierten Gelände
Stadtmöbel19 kB0,3–19 kBmit dem detaillierten Gelände
Lampen, Gleise, Schotter, Brücken, Bahnsteige, Heckenreihenje unter 5 kBje unter 5 kBmit dem detaillierten Gelände
Belag- und Straßenkanten-Raster2,18 MB0,28–2,76 MBmit dem detaillierten Gelände
Je Kachel, volle Detailstufe≈ 6,4 MB≈ 4,0–9,7 MB
Je Kachel, nur als ferne Kulisse≈ 2,3 MB≈ 1,3–3,3 MB

Wie viel ein Besuch lädt, hängt also davon ab, wohin du gehst. Mit jeder Kachel in voller Detailstufe hat ein Desktop-Browser etwa 97 MB für die fünfzehn Kacheln geladen; ein Handy etwa 95 MB (es nimmt für jede Kachel das 2048²-Landnutzungsraster); das nur für Tests gedachte „lite“-Profil, das allein die Startkachel streamt, etwa 6 MB. Das ist mehr als vor der Umstellung aufs Streamen (ein vollständiger Besuch lag bei etwa 10,6 MB), weil das Gelände jetzt als fertiges Netz statt als kompaktes Höhenraster ankommt; dafür ist jede Datei ein Standardformat, das gängige 3D-Werkzeuge öffnen können.

Was nie gesendet wird: das 13,6-MB-Gelände-GeoTIFF, das 10-MB-CityJSON und keiner der Rohdownloads. Der Browser parst kein CityJSON und baut kein Gelände; er bekommt Netze, die er direkt zeichnen kann, dazu kleine Bilder und Feature-Dateien.

Was im Browser berechnet statt heruntergeladen wird: die Bodenfarben (einmal je Kachel auf der Grafikkarte gemalt, aus den Landnutzungsklassen und einer Pastellpalette), die Wasseroberfläche, jeder Baum aus seinem Punkt und seiner Höhe, Laternenmasten und Bänke aus ihren Punkten, Brücken aus ihren Umrissen, der Sonnenstand, alle Beleuchtung und Schatten und der gesamte Nachbearbeitungs-Look.

Was neu gemacht werden muss, wenn sich etwas ändert

ÄnderungManuelle SchritteAutomatisch
Neuer GeländestandGeoTIFF in data/<ort>/dgm/ ersetzen (oder löschen und bun run fetch <ort>); die Bakes canopy und rail neu ausführen (sie lesen es)die Geländenetze samt Mauerkanten werden beim nächsten Build neu gebacken
Neues GebäudemodellCityJSON in data/<ort>/cityjson/ löschen und bun run fetch <ort> (wandelt das neue CityGML um); das Bake roof-colour neu ausführendas Gebäudenetz wird beim nächsten Build neu gebacken
Neuer Landnutzungsstanddas neue Paket laden, das Bake landcover neu ausführen, dann canopy, lamps, furniture, rail und tram (sie lesen das Klassenraster)die 2048²- und 512²-Kopien werden neu gebacken
Neue Luftbilderdie Bakes ndvi und roof-colour neu ausführendie Dachfarben werden beim nächsten Build ins Netz eingearbeitet
Neue OpenStreetMap-Dateneinen frischen Geofabrik-Auszug laden und die Bakes lamps, furniture, monuments, osm-buildings, walls, stairs, rail und tram neu ausführen—
Andere Bodenfarbendie eine Palette im Code ändernnichts neu zu backen: Der Browser malt die Farben
Eine neue Kacheldie Kachel in die Standort-Konfiguration (sites/dresden.ts) eintragen; bun run fetch <ort> lädt alles für sie, das Gebäudemodell unterwegs nach CityJSON umgewandelt; bun run bake <ort> führt alle sieben Bakes ausder Build nimmt sie ins Tileset auf und veröffentlicht sie

Warum es so gebaut ist

Die schwere Arbeit einmal offline zu erledigen, hält den Viewer eine schlichte statische Website: kein Server, keine Datenbank, keine API-Schlüssel und ein erstes Bild in wenigen Sekunden selbst auf dem Handy. Die kleinen Derivate im Repository zu halten, heißt, dass jeder den Viewer ohne die Gigabytes an Rohdaten bauen und starten kann und jede Änderung dessen, was der Viewer zeigt, in der Versionsgeschichte sichtbar ist. Die Abwägungen stehen in den Architekturentscheidungen (englisch).

Zurück
Wie der Viewer zu einer Angabe kommt
Weiter
Bedienung
Quelle auf GitHub: docs/guide/de/data-journey.mdEnglish version →
Auf dieser Seite
  • Die sechs Stationen
  • Station 1 — die Portale der Anbieter
  • Station 2 — Rohdownloads (data/_raw/, nicht eingecheckt)
  • Station 3 — die Bakes (manuell, je Kachel)
  • Station 4 — die eingecheckten Derivate (data/)
  • Station 5 — der Build-Schritt (scripts/prepare-data.ts)
  • Station 6 — der Browser
  • Was neu gemacht werden muss, wenn sich etwas ändert
  • Warum es so gebaut ist