Communitygithub.com

kml-to-track-animation

Use when turning 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). 把 KML/GPX 轨迹生成为“徒步动画 HTML”。触发词:轨迹动画、徒步动画、KML、GPX、海拔剖面、把轨迹做成网页。

kml-to-track-animation 是什么?

kml-to-track-animation is a Claude Code agent skill that use when turning 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). 把 KML/GPX 轨迹生成为“徒步动画 HTML”。触发词:轨迹动画、徒步动画、KML、GPX、海拔剖面、把轨迹做成网页。.

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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.

相关技能