Communitygithub.com

kml-to-track-animation

Convert a KML or GPX hiking track into a standalone animated route HTML page (Leaflet map, altitude-gradient trail, two walking hikers, elevation profile, play/seek/speed, milestones, key-point labels).

What is kml-to-track-animation?

This skill transforms a KML or GPX hiking track file into a feature-rich, self-contained HTML page that visualizes the route as an animated tour. It powers a Leaflet map with an altitude-colored trail, two animated hiker icons (male and female), an interactive elevation profile with clickable jump-to-point functionality, playback controls (play/pause, seek, speed, follow mode, layer toggle, fullscreen), and labeled start/end and milestone points. The page loads Leaflet and map tiles from CDN on open, so internet is required for browsing. The generated HTML is a single file with no external dependencies. It automatically parses KML `<coordinates>` / `<gx:coord>` or GPX `<trkpt>` elements, deduplicates consecutive points, calculates cumulative distance and elevation gain, and intelligently determines color ranges, milestone intervals, follow zoom, default speed, and hiker spacing based on the route's characteristics. It can also respect official distance/elevation values from '2bulu' extension fields in KML. Key waypoints (highest, second highest, mid-loop) are auto-placed, and loops with start/end within 50m are merged into a single flag. The skill supports extensive customization via command-line parameters like `--name`, `--emoji`, `--region`, `--milestone-km`, `--waypoints-json`, and `--template` for using a custom HTML template. It relies only on Python 3 standard library and works on any platform where Python runs. The HTML template uses `@@TOKEN@@` placeholders replaced by the script, and it includes workarounds for known rendering issues (e.g., profile fill gaps, green trail invisible on satellite forests, loop start labels hidden by profile panel).

Works with✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add https://github.com/kagol/kml-to-track-animation-skill/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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

ParameterDescription
--nameRoute name (used as title and default label)
--emoji / --badgeIcon before title / badge text (default <km>KM)
--regionSubtitle prefix (e.g., "Shenzhen")
--subtitleOverride with a custom HTML subtitle
--start-labelStart/end flag text
--finish-titleFinish popup title
--milestone-kmMilestone interval (km)
--waypoints-jsonCustom key points JSON: [{"frac":0.82,"emoji":"🏔️","name":"Highest Point","alt":"579m"}]
--lead / --follow-zoomDistance between the two hikers (meters) / zoom level when following
--base-duration / --speed-multTotal seconds at ×1 speed / default speed multiplier
--templateSpecify a custom template (default assets/template.html)

Known Pitfalls (Important, don't reintroduce when modifying the template)

  1. 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 increase COLS beyond the number of points.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  1. 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
    
  2. When possible, open headlessly with Playwright, listen for pageerror, and call the page-exposed window.__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.

Related Skills