Terrain Route Video

---

name: terrain-route-video description: Generate a minimalist terrain-style animated driving route video (MP4) from a list of stops (cities/POIs) without Remotion. Uses OSRM for road-following geometry, OpenTopoMap terrain tiles for basemap, Matplotlib for frame rendering, and FFmpeg for encoding. Use when the user asks to create/export a dynamic self-driving route map video (fly-follow camera, route draw animation, labels) and wants it along roads/highways.

---

Terrain Route Video (no Remotion)

Output defaults (recommended)

Size: 1600x900

FPS: 30

Duration: 12s

Style: dark terrain basemap + red route line + cyan head dot

Inputs

Option A) Road-follow (OSRM) via stops.json

Create a stops.json file:

{
  "stops": [
    {"id": "01", "name": "襄阳", "lon": 112.1163785, "lat": 32.0109980},
    {"id": "02", "name": "老河口", "lon": 111.7575073, "lat": 32.4370526}
  ]
}

Schema reference: references/stops.schema.json.

Option B) Track-follow via .gpx / .kml

If you already have a route track (GPX/KML), you can generate the video directly from the track geometry (no OSRM calls):

GPX: uses (track points) or falls back to

KML: supports both:

- standard - 2bulu/Google-style (common in hiking app exports)

Runbook

1) Create a fresh working folder (keeps caches + frames local).

2) Create a Python venv and install deps:

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install numpy matplotlib pillow requests

3) Render video (choose one):

OSRM road-follow mode (stops.json)

python /path/to/skills/terrain-route-video/scripts/terrain_route_video.py \
  --stops stops.json \
  --out out.mp4 \
  --size 1600x900 \
  --fps 30 --duration 12 \
  --title "江汉平原到洞庭湖 · 足迹" \
  --subtitle "襄阳 → 老河口 → 荆州 → 监利 → 洪湖·峰口镇 → 岳阳"

GPX/KML track mode

python /path/to/skills/terrain-route-video/scripts/terrain_route_video.py \
  --route my-track.gpx \
  --out out.mp4 \
  --size 1600x900 \
  --fps 30 --duration 12 \
  --title "My Trip" \
  --subtitle "GPX/KML track"

Notes:

The script creates frames/ and .tile-cache/ in the current folder.

If the user complains the line is not “hugging highways”, keep full OSRM geometry (default) and avoid any simplification.

If text shows missing glyphs, pass --font /System/Library/Fonts/Hiragino Sans GB.ttc (default) or another CJK font path.

OpenTopoMap tile availability can vary by zoom/region/network. The script will auto-fallback to a lower zoom if tile requests fail.

Useful tuning flags

Camera / route

--zoom 18 (terrain tile zoom; default is 18; may auto-fallback if tiles fail)

--lookahead 0.02 (camera looks ahead on the route; smaller = steadier)

--dwell 0 (pause frames at each stop; default 0)

--no-follow (static full-route view, no fly-follow)

Basemap readability (new)

These are useful when map labels feel too dark/washed out.

--basemap-alpha 0.85 (make basemap more visible)

--overlay-alpha 0.25 (reduce the dark overlay; clearer labels)

--basemap-contrast 1.20 (increase contrast)

--basemap-sharpness 1.45 (sharpen text/lines)

--basemap-color 0.80 (saturation multiplier)