Communitygithub.com

Vibetool/GeoReel

Erstellt kinematografische 3D-Kartenflugvideos aus einer JSON-Szene – ein Agentenskill für das Genre „三维地图看世界“ (echtes Gelände, automatische Kamera, selbstzeichnende Routen, Reiseaufnahmen, 3D-Kacheln, TTS).

Was ist GeoReel?

Dieser Skill rendert frame-für-frame eine CesiumJS-3D-Globus-Szene in einem headless Chrome und setzt daraus ein MP4-Video mit ffmpeg zusammen. Statt After Effects oder Earth Studio zu benötigen, definiert der Benutzer eine Szene in einer JSON-Datei mit Orten (POIs), Routen, Kamerafahrten (Einflüge, Orbits, Reiseaufnahmen) und optionalem vertikalen Overdrive für dramatische Geländedarstellung. Der Renderprozess läuft automatisiert ab: Kacheln werden geladen, Labels kollisionsfrei positioniert, Routen zeichnen sich selbst und optional wird TTS-Sprachausgabe oder Hintergrundmusik eingebunden. Der Skill eignet sich besonders für geografische Geschichten entlang von Korridoren (z.B. Bergketten, Straßen) und liefert ein einheitliches 3D-Karten-Erlebnis in Auflösungen bis 4K. Unterstützt werden node.js ≥ 18, Google Chrome, ffmpeg und ein Cesium-Ion-Token für globales Gelände und Bildmaterial. Ein Vorschaumodus (--preview) beschleunigt die Überprüfung von POI-Positionen und Label-Überlappungen, bevor der vollständige Render gestartet wird.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add Vibetool/GeoReel

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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_TOKEN Umgebungsvariable (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

  1. JSON-Szene erstellen (siehe scenes/putuoshan-demo.json und Schema unten). Koordinaten per Websuche oder eigenem Wissen ermitteln; POI-Längen-/Breitengrade grob auf dem Bildmaterial verifizieren.
  2. 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.
  3. Überprüfen: 2–3 Beispiel-Frames als Bilder ansehen (Anfang/Mitte/Ende). Prüfen: Gelände geladen (nicht leer), Beschriftungen lesbar, Routenfortschritt sichtbar.
  4. 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ßer offsetDist relativ zu alt → 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/tEnd Umriss zeichnen; appear funktioniert weiterhin als tStart). Optionales "fill": true, "fillOpacity": 0.10 blende 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" (+ optionales transitionDuration, Standard 0,8 s) – ECHTER Crossfade: die Zeitleiste wird in separat gerenderte Segmente aufgeteilt (das ausgehende Segment hält einen eingefrorenen Schwanz), dann ffmpeg xfade verknü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; stellt window.__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 appear kurz nachdem die Kamera sich gesetzt hat; Titel nach dem Einflug.
  • Wenn Frames leere/schwarze Ozeankacheln zeigen, TILE_TIMEOUT_MS Umgebungsvariable 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, hohe verticalExaggeration, 4K) mit TILE_TIMEOUT_MS=60000 SETTLE_MS=500 rendern, damit Kacheln genug Zeit zum vollständigen Setzen haben. Erhöhen von SETTLE_MS (z.B. 800) tauscht Renderzeit gegen stabile Frames.
  • Tempo für Lesbarkeit: Bodengeschwindigkeit = Pfadlänge ÷ Dauer. Wenn Städte/Gelände verschwimmen, die duration verdoppeln. 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.

Verwandte Skills