- 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 requests3) 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)