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 <trkpt> (track points) or falls back to <rtept>
• KML: supports both:
  • standard <LineString><coordinates>
  • 2bulu/Google-style <gx:Track><gx:coord> (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)