Terrain Route Video

Generate a minimalist terrain-style animated driving route video (MP4) from a list of stops (cities/POIs) without Remotion. Uses OSRM for road-following geom...

Security Scan

The skill's code and runtime instructions match its stated purpose: it renders route videos by calling public map/tile services, drawing frames with Matplotlib, and encoding with ffmpeg — nothing requested or installed is disproportionate.

Purpose & Capability

Name/description (terrain route video) align with the implementation: the script fetches OSRM routes, downloads OpenTopoMap tiles, renders frames with Matplotlib/Pillow, and encodes with ffmpeg. Required tools and libraries (requests, numpy, matplotlib, pillow, ffmpeg) are appropriate for the task.

Instruction Scope

SKILL.md stays within scope: it instructs creating a venv, installing Python deps, running the script with stops.json or GPX/KML, and notes that frames/ and .tile-cache/ are created. Important runtime behaviors are network calls to public OSRM (router.project-osrm.org) and OpenTopoMap tile servers (a.tile.opentopomap.org) and local file I/O (reading GPX/KML, writing cached tiles and frames). These actions are expected for the stated purpose but have privacy implications (coordinates are sent to public services).

Install Mechanism

No install spec; the skill is instruction-only with a Python script. That is the lowest-risk install model. Dependencies are standard PyPI libraries; the script requires ffmpeg present on PATH (checked at runtime).

Credentials

The skill requests no environment variables, no credentials, and no config paths. That is proportional: the implementation uses only public HTTP endpoints and local files. There are no unexpected secret- or credential-related requests.

Persistence & Privilege

The skill is not always-enabled and does not request elevated persistent privileges. It writes caches and frames into the current working directory only (documented). It does spawn subprocesses (ffmpeg) locally which is expected for encoding.

Assessment

This skill appears to do what it says, but note three practical things before running: (1) The script sends coordinates to public services (router.project-osrm.org and a.tile.opentopomap.org) — if your stops/GPX contain sensitive location data, consider anonymizing them or running a private routing/tile service. (2) It creates local folders (frames/ and .tile-cache/) and caches tiles on disk; run it in a dedicated working folder and delete caches when you’re done. (3) Ensure ffmpeg is installed and on PATH; the script will call it via subprocess. If you need stronger privacy or to avoid external network calls, you would need a local OSRM/tile server or to modify the script to use only local tiles/tracks.

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)