geo-flyover — 3D-Kartenflug-Generator
Rendert eine Cesium (CesiumJS) 3D-Globus-Szene frame-für-frame in einem headless Chrome und setzt daraus ein MP4 mit ffmpeg zusammen. Kein After Effects / Earth Studio nötig.
Voraussetzungen
- Node ≥ 18, Google Chrome installiert, ffmpeg im PATH (alles auf diesem Rechner geprüft).
CESIUM_ION_TOKENUmgebungsvariable (kostenloser Account unter https://ion.cesium.com → Access Tokens). Mit einem Token erhältst du Cesium World Imagery + World Terrain (3D-Berge). Ohne Token fällt der Renderer auf Esri World Imagery Satellitenkacheln auf einem FLACHEN Ellipsoid zurück – ansehbar, aber ohne 3D-Relief.- Erster Durchlauf:
cd render && npm install(installiert nur puppeteer-core, klein).
Arbeitsablauf
- JSON-Szene erstellen (siehe
scenes/putuoshan-demo.jsonund Schema unten). Koordinaten per Websuche oder eigenem Wissen ermitteln; POI-Längen-/Breitengrade grob auf dem Bildmaterial verifizieren. - Rendern:
cd <skill-verzeichnis>/render && node render.mjs ../scenes/<szene>.json /ausgabe/verzeichnis- Schreibt
frames/f_0001.png...und erstellt dann automatisch<ausgabe>/<name>.mp4. - ~1–3 fps Rendergeschwindigkeit; ein 10 s / 300-Frames Video dauert ein paar Minuten. Im Hintergrund laufen lassen und abfragen.
- Schreibt
- Überprüfen: 2–3 Beispiel-Frames als Bilder ansehen (Anfang/Mitte/Ende). Prüfen: Gelände geladen (nicht leer), Beschriftungen lesbar, Routenfortschritt sichtbar.
- Den MP4-Pfad an den Benutzer übergeben. Für finale Videos 1920x1080 empfehlen.
Empfohlen: Aufnahmebasierte Kamera (automatisch berechnet – diesen Modus statt manueller cameraPath verwenden)
"preset": "1080p", // 720p | 1080p | 4k — Schrift-/Punkt-/Linienbreiten skalieren automatisch mit der Auflösung
"shots": [
{ "type": "flyin", "duration": 5, "pitch": -33, "viewFrom": 178 }, // viewFrom: Kompassrichtung Ziel→Kamera (178 = Kamera fast genau südlich)
{ "type": "orbit", "duration": 6, "sweep": -14 }, // Kamera um sweep° schwenken, Ziel bleibt zentriert
{ "type": "flyin", "duration": 4, "cut": true, "transition": "white", // harter Schnitt maskiert durch Überblendung zu Weiß
"target": "玉皇顶·山顶", "radius": 1200, "targetHeight": 1530, // Nahaufnahme eines benannten POI; targetHeight = dessen Geländehöhe (m) – ERFORDERLICH für Berg-Nahaufnahmen sonst verlässt der Gipfel das Bild
"pitch": -30, "viewFrom": 165, "distanceFactor": 4.5 },
{ "type": "orbit", "duration": 5, "sweep": 20 } // Umkreist das Ziel des Schnitts
]
Reiseaufnahme – für lange lineare Merkmale (Korridore, Gebirgszüge, Roadtrips)
{ "type": "travel", // Dauer AUSGELASSEN → automatisch getaktet durch Pfadlänge (empfohlen)
"path": [[lng,lat],...], // oder weglassen um routes[0].path zu folgen
"offsetBearing": 32, // Kompassrichtung von jedem Pfadpunkt zur Kamera (32 = Kamera im NO)
"offsetDist": 52000, // Seitlicher Abstand vom Pfad, Meter
"alt": 16000, // Kameraflughöhe, Meter (NIEDRIG für Relief – siehe unten)
"targetHeight": 3400, // Höhe, auf die die Kamera blickt
"groundSpeed": 15000, // Meter Boden pro Sekunde; Dauer = Pfadlänge / groundSpeed
"lookAhead": 0.05 } // Blick nach vorne entlang des Pfades (0..0.15 = Reisegefühl)
// duration: <n> // optionaler harter Überschreiber; Samples ≈ Dauer/1.5 wenn weggelassen
Automatische Taktung (NIEMALS Dauer für Reise hartkodieren): duration weglassen und die Aufnahme zeit sich selbst aus Pfadlänge ÷ groundSpeed (Standard 15000 m/s, kalibriert damit ~1000 km in ~65 s abgespielt werden). Ein 300 km Abschnitt und eine 1500 km Schleife lesen sich dann beide mit angenehmem, gleichmäßigem Tempo. Verlangsamen durch niedrigere groundSpeed (z.B. 12000); beschleunigen mit höherem Wert. Die Keyframe-Anzahl skaliert automatisch mit.
Die Kamera hält einen konstanten seitlichen Versatz + Höhe und gleitet von einem Ende des Pfades zum anderen, immer auf den bewegten Pfadpunkt blickend (lineare Interpolation = gleichmäßiger Schwenk, kein Beschleunigungs-Pumpen). Dies ist das RICHTIGE Werkzeug für einen ~1000 km Korridor: eine statische Aufnahme müsste ins All gehen, um alles zu sehen, aber eine Reiseaufnahme bleibt niedrig und enthüllt es mit der Zeit.
Taktung und Relief für Reiseaufnahmen (gelernt beim Tunen des Hexi-Korridors):
- Geschwindigkeit = Pfadlänge ÷ Dauer. Ein 1000 km Korridor in 16 s ist ein Verwischen; gib ihm ~30 s+ damit Städte lesbar sind. BodenGeschwindigkeit über ~30 km/s liest sich als „zu schnell".
- Relief (das Gefühl des Höhenunterschieds Berg vs. Ebene) braucht drei Dinge zusammen: eine NIEDRIGE Kamera (
alt~12–18 km, nicht 40 km – große Höhe macht alles flach), einen FLACHEN Blickwinkel (großeroffsetDistrelativ zualt→ Pitch ~-12..-16°, sodass Gipfel gegen den Horizont aufragen statt von oben herab gesehen zu werden), und eine szenenweite"verticalExaggeration": 2.0–2.5(siehe unten). Vogelperspektive + weit = flach; niedrig + flach + überhöht = dramatisch.
verticalExaggeration (szenenweit) – Geländerelief hervorheben
"verticalExaggeration": 2.3 // multipliziert alle Geländehöhen; 1 = echt, 2–2.5 = der 三维地图看世界 Look
Der mit Abstand größte Hebel zur Darstellung von Höhenunterschieden. Gebirgszüge stehen als Wände auf; Schluchten-/Talkerben werden aus der Ferne lesbar. POI-/Label-/Routenanker werden entsprechend angepasst, sodass nichts schwebt oder versinkt. Verwende ihn für jede Geländegeschichte (Korridore, Gebirgszüge, Schluchten); bei Stadtaufnahmen (buildings3d) auf 1 belassen. Setze jeden POI appear etwa auf den Zeitpunkt, wenn die Kamera vorbeifliegt; POIs hinter der Kamera verlassen natürlich das Bild. Zeichne die Route mit tStart/tEnd über die gesamte Aufnahme, sodass sich die Linie beim Fliegen abspult.
Der Compiler zentriert Flyin/Orbit auf die umschließenden Boxen aller POIs/Routen/Regionen (oder auf das target der Aufnahme), berechnet die Schrägentfernung aus der Streuung (distanceFactor, Standard 3.8), leitet die Richtung automatisch aus der Kompassmathematik ab und warnt, wenn ein POI innerhalb eines Segments mehr als 28° von der Achse abweicht (Reiseaufnahmen überspringen diese Prüfung – sie fliegen absichtlich an POIs vorbei). Gesamtdauer = Summe der Einzelaufnahmen. cut: true springt die Kamera am Aufnahmeübergang unter einer Ein-/Ausblendung zu Weiß/Schwarz (transition, transitionDuration Standard 0,8s). Handgeschriebene cameraPath funktioniert weiterhin für volle Kontrolle.
Beschriftungsgröße
"labelScale": 3 // multipliziert POI (Stadt/Berg) Label + Punktgröße; Standard 1. Große Überblicks-/Reiseaufnahmen wollen 2–3.
Skaliert die Schriftgröße, den Rahmen, den Punkt und – entscheidend – die Anti-Kollisions-Abstände und Kantenausrichtung, sodass 3× Labels sich dennoch nie überlappen oder am Bildrand abgeschnitten werden. Der Titel hat seine eigene feste Größe (unbeeinflusst).
Integrierte Verhaltensweisen (keine Konfiguration nötig)
- Label-Anti-Kollision: jeder Frame werden Labels in den Bildschirmraum projiziert und entflochten – POI-Labels stapeln sich nach oben (Abstände skalieren mit Schriftgröße), der große Titel weicht aus (klebrige Offsets, kein Zittern). Labels nahe dem Bildrand richten sich automatisch nach innen aus (links/rechts Ursprung), sodass große Labels nie abgeschnitten werden. POI-/Titel-Anker werden auf Geländehöhe abgetastet, sodass die Projektion auf Bergen genau ist. Wenn ein Label nach oben geschoben wird, verbindet eine weiße Führungslinie es mit seinem Punkt.
- POI-Einblendung: Punkte skalieren mit einer Back-Ease-Bounce ein; Labels blenden nach ihrer
appear-Zeit über 0,6 s ein/aus. - Regionen-Zeichnung: Regionen animieren wie Routen (
tStart/tEndUmriss zeichnen;appearfunktioniert weiterhin als tStart). Optionales"fill": true, "fillOpacity": 0.10blende einen geländebedeckten Farbton nach Abschluss des Umrisses ein.
Übergänge: Dip vs. Crossfade
"transition": "white" | "black"– Überblendung zu Farbe, einzelner Render-Durchlauf (günstig, Standard)."transition": "fade"(+ optionalestransitionDuration, Standard 0,8 s) – ECHTER Crossfade: die Zeitleiste wird in separat gerenderte Segmente aufgeteilt (das ausgehende Segment hält einen eingefrorenen Schwanz), dann ffmpegxfadeverknüpft sie. Kostet zusätzliche Frames ≈ fps × transitionDuration pro Schnitt.
Google Photorealistic 3D Tiles (Städte)
"buildings3d": true, // ion asset 2275207; erfordert CESIUM_ION_TOKEN; Globus wird ausgeblendet
"buildings3dQuality": 16 // maximumScreenSpaceError; niedriger = schärfer = langsamer
Für heroische Stadtaufnahmen NIEDRIG und NAH: pitch -18..-25, minSlant 1200–2000 (überschreibt den 3000 m Mindestabstand), targetHeight ≈ mittlere Turmhöhe (150–250 m). Hinweis: Google Kacheln rendern pro Frame langsamer und verbrauchen ion-Kontingente; --workers standardmäßig 1, wenn buildings3d eingeschaltet ist.
Paralleles Rendern
node render.mjs szene.json ausgabe --workers=2 — N Chrome-Instanzen rendern zusammenhängende Frame-Blöcke parallel (wiederaufnehmbar + selbstheilend pro Worker). Standard 2 (1 mit buildings3d). 3–4 Worker nur auf leistungsstarken Rechnern.
Optionales Audio (TTS-Erzählung / BGM)
"audio": { // komplett weglassen für ein stummes Video
"tts": { "text": "泰山,五岳之首……", // Erzählung
"voice": "zh-CN-YunxiNeural", // edge-tts Stimme (falls edge-tts installiert)
"sayVoice": "Tingting" }, // macOS `say` Ersatzstimme
"bgm": { "file": "/pfad/zu/musik.mp3", "volume": 0.22 } // auf Videolänge geloopt + getrimmt
}
Engine wählt edge-tts falls installiert, sonst macOS say (Tingting), sonst überspringt mit Warnung. Ausgabe wird als <name>-audio.mp4 beiseite geschrieben; das stumme <name>.mp4 bleibt immer erhalten. Audio-Fehler brechen den Render nicht ab.
Immer vor dem vollständigen Render eine Vorschau machen
node render.mjs <szene>.json <ausgabe> --preview
~1 min: rendert 3 Frames (t=0,35/0,65/0,95) mit ALLEN POIs/Routen zwangsweise angezeigt. POI-Platzierung, Bildausschnitt, Label-Überlappungen prüfen – dann den vollständigen Render starten. Dies fängt Koordinatenfehler 6× schneller als ein Vollrender.
JSON-Schema der Szene
{
"name": "putuoshan", // Ausgabedatei-Stammname
"width": 1280, "height": 720, "fps": 30, "duration": 10, // Sekunden
"cameraPath": [ // Keyframes, t in [0,1] der Dauer, dazwischen kubisch geglättet
{ "t": 0.0, "lng": 122.387, "lat": 29.85, "alt": 60000, "heading": 0, "pitch": -90 },
{ "t": 0.4, "lng": 122.387, "lat": 29.95, "alt": 6000, "heading": 10, "pitch": -35 },
{ "t": 1.0, "lng": 122.40, "lat": 29.96, "alt": 4500, "heading": 80, "pitch": -30 }
],
"pois": [ // grüner Punkt + weißes Label, erscheint mit Einblendung bei t=appear
{ "name": "普济禅寺", "lng": 122.3875, "lat": 29.9887, "appear": 0.45 }
],
"title": { "text": "普陀山", "lng": 122.387, "lat": 30.001, "appear": 0.35 },
"routes": [ // leuchtende Polylinie, Zeichenanimation zwischen tStart..tEnd
{ "color": "#ffe94a", "width": 8, "tStart": 0.55, "tEnd": 0.95,
"path": [[122.3963,29.9770],[122.3960,29.9805],[122.3875,29.9887]] }
],
"regions": [ // optionaler leuchtender Polygonumriss (Region hervorheben)
{ "color": "#ffe94a", "width": 6, "appear": 0.5, "polygon": [[lng,lat],...] }
]
}
Dateien
render/flyover.html— Cesium-Szene; stelltwindow.__setup(cfg)/window.__frame(t)für deterministische Schrittweise zur Verfügung.render/render.mjs— puppeteer-core Treiber: durchläuft Frames, wartet auf Kachelladungen, macht Screenshots, führt ffmpeg aus.scenes/putuoshan-demo.json— funktionierendes Beispiel.TODO.md— Iteration-Backlog (Multi-Shot, Region-Draw-on, TTS, 1080p Presets…).
Tipps
- Kameraeinflüge lesen sich am besten: Vogelperspektive weit oben → neigen auf ~-30..-40° Pitch bei 3–8 km Höhe.
- Kompositionsprüfung (Rechnung aufmachen! ): an jedem Keyframe muss die Richtung von der Kameraposition zum Ziel zeigen – Richtung ≈ atan2(Δlng·cos(lat), Δlat) in Grad von Norden. Kamera auf einer Seite halten (z.B. südlich des Ziels, Richtung ≈ 0±25°) und sanft schwenken; eine Richtung, die abdriftet, lässt das Motiv (und deine Routenanimation) aus dem Bild laufen. Vor der Auslieferung immer Start-/Mittel-/End-Frames visuell prüfen.
- Richtungsänderung pro Aufnahme < 120° halten, sonst wirkt die Bewegung schwammig.
- POI
appearkurz nachdem die Kamera sich gesetzt hat; Titel nach dem Einflug. - Wenn Frames leere/schwarze Ozeankacheln zeigen,
TILE_TIMEOUT_MSUmgebungsvariable erhöhen oder Kamera verlangsamen. - Kein "Karte lädt nach"-Flackern: jeder Frame wartet, bis Kacheln geladen sind UND für
SETTLE_MS(Standard 500 ms) geladen geblieben sind, bevor aufgenommen wird – du bekommst nie einen noch ladenden Frame, der im nächsten schärfer wird. Bei schweren Szenen (niedrige Höhe, hoheverticalExaggeration, 4K) mitTILE_TIMEOUT_MS=60000 SETTLE_MS=500rendern, damit Kacheln genug Zeit zum vollständigen Setzen haben. Erhöhen vonSETTLE_MS(z.B. 800) tauscht Renderzeit gegen stabile Frames. - Tempo für Lesbarkeit: Bodengeschwindigkeit = Pfadlänge ÷ Dauer. Wenn Städte/Gelände verschwimmen, die
durationverdoppeln. Ein 1000 km Korridor will ~60 s, damit man die Orte tatsächlich lesen kann. - Namensnennung: Cesium ion Bildmaterial erfordert sichtbare Namensnennung – der Renderer behält den Cesium-Credit-Container sichtbar; nicht für veröffentlichte Videos wegschneiden.