Communitygithub.com

Vibetool/GeoReel

Cinematic 3D map flyover videos from a JSON scene — an agent skill for the 3D map world genre (real terrain, auto camera, self-drawing routes, travel shots, 3D tiles, TTS).

What is GeoReel?

This skill, named 'geo-flyover,' is a headless 3D map flyover video generator that renders CesiumJS globe scenes frame-by-frame using Puppeteer and Chrome, then assembles them into MP4 videos with ffmpeg—no After Effects or Earth Studio required. It is designed for developers and AI agents who want to produce cinematic, narrated map animations from simple JSON scene descriptions. The skill supports multiple shot types including fly-ins, orbits, and travel shots along linear paths, with auto-computed camera paths, anti-collision labels, terrain exaggeration, and optional TTS narration or background music. It requires Node.js 18+, Chrome, ffmpeg, and a free Cesium ion token for 3D terrain; it runs on any machine with these dependencies. The workflow involves authoring a scene JSON, running a render script that outputs frames and an MP4, and optionally previewing frames before full rendering. Key features include parallel rendering, Google Photorealistic 3D Tiles for cities, dip-to-white/black or crossfade transitions, and robust tile-load settling to prevent flicker. This is the right tool for creating dramatic 3D map flyovers for corridors, road trips, or scenic overviews without manual video editing.

Works with~Claude Code~Codex CLI~Cursor
npx skills add Vibetool/GeoReel

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

geo-flyover — 3D Map Flyover Generator

Renders a Cesium (CesiumJS) 3D globe scene frame-by-frame in headless Chrome, then assembles an MP4 with ffmpeg. No After Effects / Earth Studio needed.

Requirements

  • Node ≥ 18, Google Chrome installed, ffmpeg on PATH (all verified on this machine).
  • CESIUM_ION_TOKEN env var (free account at https://ion.cesium.com → Access Tokens). With a token you get Cesium World Imagery + World Terrain (3D mountains). Without it, the renderer falls back to Esri World Imagery satellite tiles on a FLAT ellipsoid — watchable, but no 3D relief.
  • First run: cd render && npm install (installs puppeteer-core only, tiny).

Workflow

  1. Author a scene JSON (see scenes/putuoshan-demo.json and schema below). Get coordinates via web search or your knowledge; verify POI lng/lat roughly on the imagery.
  2. Render: cd <skill-dir>/render && node render.mjs ../scenes/<scene>.json /path/to/outdir
    • Writes frames/f_0001.png... then assembles <outdir>/<name>.mp4 automatically.
    • ~1–3 fps render speed; a 10 s / 300-frame video takes a few minutes. Run in background and poll.
  3. Verify: Read 2–3 sample frames as images (start/mid/end). Check: terrain loaded (not blank), labels legible, route reveal progressing.
  4. Deliver the MP4 path to the user. For final videos suggest 1920x1080.

Recommended: shots-based camera (auto-computed, use this instead of hand-writing cameraPath)

"preset": "1080p",   // 720p | 1080p | 4k — fonts/points/line widths auto-scale with resolution
"shots": [
  { "type": "flyin", "duration": 5, "pitch": -33, "viewFrom": 178 },  // viewFrom: compass bearing target→camera (178 = camera almost due south)
  { "type": "orbit", "duration": 6, "sweep": -14 },                    // arc the camera by sweep°, target stays centered
  { "type": "flyin", "duration": 4, "cut": true, "transition": "white", // hard cut masked by dip-to-white
    "target": "Jade Emperor Peak·Summit", "radius": 1200, "targetHeight": 1530,        // closeup on a named POI; targetHeight = its terrain elevation (m) — REQUIRED for mountain closeups or the peak leaves frame
    "pitch": -30, "viewFrom": 165, "distanceFactor": 4.5 },
  { "type": "orbit", "duration": 5, "sweep": 20 }                      // orbits the cut target
]

travel shot — for long linear features (corridors, ranges, road trips)

{ "type": "travel",          // duration OMITTED → auto-paced by path length (recommended)
  "path": [[lng,lat],...],   // or omit to follow routes[0].path
  "offsetBearing": 32,       // compass bearing from each path point → camera (32 = camera to the NE)
  "offsetDist": 52000,       // lateral offset from the path, metres
  "alt": 16000,              // camera altitude, metres (LOW for relief — see below)
  "targetHeight": 3400,      // elevation the camera looks at
  "groundSpeed": 15000,      // metres of ground per second; duration = pathLength / groundSpeed
  "lookAhead": 0.05 }        // bias look-at forward along path (0..0.15 = travel feel)
  // duration: <n>           // optional hard override; samples auto ≈ duration/1.5 if omitted

Auto-pacing (do NOT hard-code duration for travel): omit duration and the shot times itself from the path length ÷ groundSpeed (default 15000 m/s, calibrated so ~1000 km plays in ~65 s). A 300 km leg and a 1500 km loop then both read at a comfortable, consistent speed. Slow it globally by lowering groundSpeed (e.g. 12000); speed up with a higher value. Keyframe count auto-scales too. The camera holds a constant lateral offset + altitude and glides from one end of the path to the other, always looking at the moving path point (linear interpolation = constant-speed pan, no easing pump). This is the RIGHT tool for a ~1000 km corridor: a static shot must go to space to see it all, but a travel shot stays low and reveals it over time.

Pacing & relief for travel shots (learned tuning the Hexi Corridor):

  • Speed = path length ÷ duration. A 1000 km corridor in 16 s is a blur; give it ~30 s+ so cities are readable. Ground speed over ~30 km/s reads as "too fast".
  • Relief (feeling the mountain-vs-plain height drop) needs three things together: a LOW camera (alt ~12–18 km, not 40 km — high altitude flattens everything), a SHALLOW look angle (large offsetDist relative to alt → pitch ~-12..-16°, so peaks rise against the horizon instead of being looked down on), and scene-level "verticalExaggeration": 2.0–2.5 (see below). Top-down + far = flat; low + shallow + exaggerated = dramatic.

verticalExaggeration (scene-level) — make terrain relief pop

"verticalExaggeration": 2.3   // multiply all terrain heights; 1 = real, 2–2.5 = the 3D map world look

The single biggest lever for conveying elevation. Mountain ranges stand up as walls; canyon/gully relief becomes legible from a distance. POI/label/route anchors are height-adjusted to match, so nothing floats or sinks. Use it for any terrain-relief story (corridors, ranges, canyons); leave it at 1 for city (buildings3d) shots. Set each POI's appear to roughly when the camera passes it; POIs behind the camera naturally leave frame. Draw the route with tStart/tEnd spanning the shot so the line unspools as you fly.

The compiler centers flyin/orbit on the bounding box of all POIs/routes/regions (or the shot's target), computes slant range from spread (distanceFactor, default 3.8), derives heading from bearing math automatically, and warns if any in-segment POI drifts >28° off-axis (travel shots skip this check — they pan past POIs by design). Total duration = sum of shot durations. cut: true jumps the camera at the shot boundary under a dip-to-white/black transition (transition, transitionDuration default 0.8s). Hand-written cameraPath still works for full control.

Label sizing

"labelScale": 3   // multiply POI (city/mountain) label + dot size; default 1. Big travel/overview shots want 2–3.

Scales the label font, outline, dot, and — crucially — the anti-collision stacking gaps and edge-alignment, so 3× labels still never overlap or clip off-screen. The title has its own fixed size (unaffected).

Built-in behaviors (no config needed)

  • Label anti-collision: every frame, labels are projected to screen space and de-overlapped — POI labels stack upward (gaps scale with font size), the big title moves out of the way (sticky offsets, no jitter). Labels near a frame edge auto-align inward (left/right origin) so big labels never clip off-screen. POI/title anchors are terrain-height-sampled so projection is accurate on mountains. When a label is pushed up, a white leader line connects it to its dot.
  • POI pop-in: dots scale in with a back-ease bounce; labels fade/trail in over 0.6 s after their appear time.
  • Region draw-on: regions animate like routes (tStart/tEnd outline draw; appear still works as tStart). Optional "fill": true, "fillOpacity": 0.10 fades a terrain-draped tint after the outline completes.

Transitions: dip vs crossfade

  • "transition": "white" | "black" — dip-to-color overlay, single render pass (cheap, default).
  • "transition": "fade" (+ optional transitionDuration, default 0.8 s) — TRUE crossfade: the timeline splits into segments rendered separately (the outgoing segment holds a frozen tail), then ffmpeg xfade chains them. Costs extra frames ≈ fps × transitionDuration per cut.

Google Photorealistic 3D Tiles (cities)

"buildings3d": true,            // ion asset 2275207; requires CESIUM_ION_TOKEN; globe is hidden
"buildings3dQuality": 16        // maximumScreenSpaceError; lower = sharper = slower

For city hero shots go LOW and CLOSE: pitch -18..-25, minSlant 1200–2000 (overrides the 3000 m slant floor), targetHeight ≈ mid-tower (150–250 m). Note: Google tiles render slower per frame and consume ion quota; --workers defaults to 1 when buildings3d is on.

Parallel rendering

node render.mjs scene.json outdir --workers=2 — N Chrome instances render contiguous frame chunks concurrently (resume + self-heal per worker). Default 2 (1 with buildings3d). 3–4 workers only on beefy machines.

Optional audio (TTS narration / BGM)

"audio": {                                       // omit entirely for a silent video
  "tts": { "text": "Mount Tai, chief of the Five Great Mountains…",              // narration
           "voice": "zh-CN-YunxiNeural",          // edge-tts voice (if edge-tts installed)
           "sayVoice": "Tingting" },              // macOS `say` fallback voice
  "bgm": { "file": "/path/to/music.mp3", "volume": 0.22 }   // looped + trimmed to video length
}

Engine picks edge-tts if installed, else macOS say (Tingting), else skips with a warning. Output is written alongside as <name>-audio.mp4; the silent <name>.mp4 is always kept. Audio failures never fail the render.

Always preview before a full render

node render.mjs <scene>.json <outdir> --preview

~1 min: renders 3 frames (t=0.35/0.65/0.95) with ALL POIs/routes force-shown. Check POI placement, framing, label collisions — then run the full render. This catches coordinate mistakes 6× faster than a full render.

Scene JSON schema

{
  "name": "putuoshan",           // output file stem
  "width": 1280, "height": 720, "fps": 30, "duration": 10,  // seconds
  "cameraPath": [                 // keyframes, t in [0,1] of duration, eased cubic in between
    { "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": [                       // green dot + white label, appear with fade at t=appear
    { "name": "Puji Zen Temple", "lng": 122.3875, "lat": 29.9887, "appear": 0.45 }
  ],
  "title": { "text": "Mount Putuo", "lng": 122.387, "lat": 30.001, "appear": 0.35 },
  "routes": [                     // glowing polyline, draw-on animation between 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": [                    // optional glowing polygon outline (region highlight)
    { "color": "#ffe94a", "width": 6, "appear": 0.5, "polygon": [[lng,lat],...] }
  ]
}

Files

  • render/flyover.html — Cesium scene; exposes window.__setup(cfg) / window.__frame(t) for deterministic stepping.
  • render/render.mjs — puppeteer-core driver: steps frames, waits for tile loads, screenshots, runs ffmpeg.
  • scenes/putuoshan-demo.json — working example.
  • TODO.md — iteration backlog (multi-shot, region draw-on, TTS, 1080p presets…).

Tips

  • Camera fly-ins read best: top-down high shot → tilt to ~-30..-40° pitch at 3–8 km alt.
  • Composition check (do the math!): at every keyframe, heading must point from camera position toward the target — bearing ≈ atan2(Δlng·cos(lat), Δlat) in degrees from north. Keep the camera on one side (e.g. south of target, heading ≈ 0±25°) and arc gently; a heading that drifts away leaves the subject (and your route animation) off-frame. Always verify start/mid/end frames visually before delivering.
  • Keep per-shot heading change < 120° or motion looks swimmy.
  • POI appear slightly after the camera settles; title after the fly-in.
  • If frames show blank/black ocean tiles, increase TILE_TIMEOUT_MS env or slow the camera.
  • No "map refreshing" flicker: every frame waits until tiles are loaded AND have stayed loaded for SETTLE_MS (default 500 ms) before capture — so you never grab a still-streaming frame that resolves sharper on the next one. For heavy scenes (low-altitude travel, high verticalExaggeration, 4K) render with TILE_TIMEOUT_MS=60000 SETTLE_MS=500 so tiles have room to fully settle. Raising SETTLE_MS (e.g. 800) trades render time for rock-steady frames.
  • Pace for readability: ground speed = path length ÷ duration. If cities/terrain blur past, double the duration. A 1000 km corridor wants ~60 s to actually read the places.
  • Attribution: Cesium ion imagery requires visible attribution — the renderer keeps the Cesium credit container visible; do not crop it out for published videos.

Related Skills