KML/GPX → Hiking Track Animation HTML
Render a track file into a self-contained HTML page: Leaflet map + altitude-gradient trail + a male and a female hiker walking together + clickable elevation profile with jump-to + play/pause/seek/speed/follow/layers/fullscreen + start/end and key point labels + finish celebration popup.
The page loads Leaflet from CDN and uses Esri satellite / OpenStreetMap tiles, so browsing requires an internet connection; the generated HTML itself is a single file.
Quick Start
python3 scripts/kml_to_animation.py path/track.kml -o output/track.html \
--name "Yangshentai Double Heart" --region "Shenzhen" --emoji "🧡"
Only depends on Python 3 standard library. Default output is an .html file with the same name as the input.
python3 scripts/kml_to_animation.py route.kml # route.html
python3 scripts/kml_to_animation.py route.gpx --help # view all parameters
What It Automatically Does
- Parses KML
<coordinates>/<gx:coord>or GPX<trkpt>, removing consecutive duplicate points. - Calculates distance and elevation gain; if the KML has "2bulu" extension fields
Data name="Distance"/ElevationGain, it prefers official values and linearly scales point-wise cumulative distance/elevation to the official totals (can be disabled with--no-official). - Automatically determines color range based on max altitude, selects milestone intervals, follow zoom, default speed, and hiker spacing.
- Automatically places key points: highest point, second highest (at least 8% of the total route apart), and mid-loop point.
- Loop lines (start/end within 50m) are merged into a single "Start / End" flag.
Common Parameters
| Parameter | Description |
|---|---|
--name | Route name (used as title and default label) |
--emoji / --badge | Icon before title / badge text (default <km>KM) |
--region | Subtitle prefix (e.g., "Shenzhen") |
--subtitle | Override with a custom HTML subtitle |
--start-label | Start/end flag text |
--finish-title | Finish popup title |
--milestone-km | Milestone interval (km) |
--waypoints-json | Custom key points JSON: [{"frac":0.82,"emoji":"🏔️","name":"Highest Point","alt":"579m"}] |
--lead / --follow-zoom | Distance between the two hikers (meters) / zoom level when following |
--base-duration / --speed-mult | Total seconds at ×1 speed / default speed multiplier |
--template | Specify a custom template (default assets/template.html) |
Known Pitfalls (Important, don't reintroduce when modifying the template)
- Profile fill failure: Track points (e.g., 1006) may be fewer than profile columns. If using "min/max per column + set empty columns to Infinity", empty columns will cause the canvas fill path to become NaN and the entire area is not drawn. The template has been changed to
COLS = 600+ bucket aggregation + forward filling, ensuring no empty buckets. Do not blindly increaseCOLSbeyond the number of points. - Green trail invisible on satellite forest: Low-altitude green blends with forest color. The template uses a cyan(lo)→amber(mid)→red(hi) color scheme with a dark
rgba(8,14,22,.65)stroke beneath the colored trail. - Loop start label hidden by profile panel: When start/end is below the map, the flag HTML uses
transform: translate(-50%,-100%)so text appears above the flag, and the entire element is bottom-aligned to the coordinate point. - Official distance vs computed distance: The computed geometric distance often differs slightly from the official record (e.g., 10.29km vs 10.44km). Display should follow official values, and point-wise cumulative values are linearly scaled to match, avoiding progress/number mismatches.
- Animation duration for short routes: Total ×1 duration is estimated as
clamp(km*24, 120, 480)seconds; speed multiplier and milestone intervals adapt to route length, so a 10km route won't use parameters for 200km (which would make 25km milestones impossible to draw).
Template
assets/template.html is the complete page, using @@TOKEN@@ placeholders (e.g., @@TRACK@@, @@WAYPOINTS@@,
@@TOTAL_METERS@@, @@OFFICIAL_GAIN@@, @@ALT_LO@@, @@ALT_SPAN@@, @@SPEED_GROUP@@).
The script performs pure string replacement and verifies no residual @@…@@ remains. To change layout/color, modify the template directly and pass --template.
Validation Suggestions
- Extract the inline script for syntax checking:
python3 - <<'PY' import re;h=open("out.html",encoding="utf-8").read() js=re.search(r"<script>\s*/\* KML.*?</script>",h,re.S).group(0) js=re.sub(r"^<script>\s*","",js);js=re.sub(r"</script>\s*$","",js) open("/tmp/out.js","w",encoding="utf-8").write(js) PY node --check /tmp/out.js - When possible, open headlessly with Playwright, listen for
pageerror, and call the page-exposedwindow.__CAP.render(0.5)to capture a mid-route screenshot and verify the trail and profile look correct.
Directory Layout
kml-to-track-animation/
├── SKILL.md
├── assets/template.html # Full page template (@@TOKEN@@ placeholders)
└── scripts/kml_to_animation.py # KML/GPX parser + statistics + rendering
Global Installation
This skill is located in the personal skills directory ~/Documents/Kagol/code/my-skills/ and has been registered globally in
~/.config/opencode/opencode.json under skills.paths (all */SKILL.md under that directory are loaded globally). After modifying the configuration or skill, restart opencode for changes to take effect.