Communitygithub.com

KML/GPX → 徒步轨迹动画 HTML

将 KML 或 GPX 徒步轨迹转换为一个自含式的动态路线 HTML 页面(Leaflet 地图、海拔渐变轨迹、双人徒步动画、海拔剖面、播放/搜索/速度控制、里程碑与关键点标注)。

GPX → 徒步轨迹动画 HTML 是什麼?

此技能用于将 KML 或 GPX 格式的徒步轨迹文件转换为一个功能丰富的单文件 HTML 动画页面。页面包含 Leaflet 交互式地图,轨迹线根据海拔高度显示渐变色,并配有一男一女两个徒步小人沿路径行走。它还提供可点击跳转的海拔剖面图、播放/暂停/进度/倍速控制、跟随视图、图层切换和全屏模式。支持起点、终点和关键点的自定义标注,完成时有庆祝弹窗。页面从 CDN 加载 Leaflet 和 Esri/OpenStreetMap 瓦片,因此需要网络连接;生成的 HTML 文件是自包含的,方便分享。该工具主要面向徒步爱好者、户外路线记录者,可在 Claude Code、Cursor 或 Codex 等环境中使用。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

GPX → 徒步轨迹动画 HTML 是做什麼的?

將一個軌跡檔案渲染成一個自包含的 HTML:Leaflet 地圖 + 按海拔漸變的軌跡 + 一男一女結伴徒步小人 + 可點擊跳轉的海拔剖面 + 播放/暫停/進度/倍速/跟隨/圖層/全螢幕 + 起終點與關鍵點標註 + 終點慶祝彈窗。

頁面打開時從 CDN 載入 Leaflet,並使用 Esri 衛星 / OpenStreetMap 瓦片,因此瀏覽時需要連網;生成的 HTML 本身是單檔案。

快速開始

python3 scripts/kml_to_animation.py 路徑/軌跡.kml -o 輸出/軌跡.html \
  --name "陽台山雙愛心" --region "深圳" --emoji "🧡"

只依賴 Python 3 標準庫。預設輸出與輸入同名的 .html。

python3 scripts/kml_to_animation.py route.kml            # route.html
python3 scripts/kml_to_animation.py route.gpx --help     # 查看全部參數

它會自動做的事

  • 解析 KML <coordinates> / <gx:coord> 或 GPX <trkpt>,去除連續重複點。
  • 計算里程與爬升;若 KML 帶「兩步路/2bulu」擴展欄位 Data name="Distance" / ElevationGain,優先使用官方值並把逐點累計里程、爬升線性縮放到官方總數(可用 --no-official 關閉)。
  • 依據最大海拔自動配色範圍,選擇里程樁間隔、跟隨縮放、預設倍速與徒步間距。
  • 自動放置關鍵點:最高點、次高點(至少相隔全程 8%)、環線中段。
  • 循環線(起終點相距 < 50m)合併成一個「起點 / 終點」旗幟。

常用參數

參數說明
--name路線名(標題、標籤預設使用)
--emoji / --badge標題前的圖示 / 徽章文字(預設 <km>KM)
--region副標題前綴(如「深圳」)
--subtitle直接用自訂副標題 HTML 覆蓋
--start-label起終點旗幟文字
--finish-title終點彈窗標題
--milestone-km里程樁間隔(km)
--waypoints-json自訂關鍵點 JSON:[{"frac":0.82,"emoji":"🏔️","name":"最高點","alt":"579m"}]
--lead / --follow-zoom兩人前後間距(公尺)/ 跟隨時縮放
--base-duration / --speed-mult×1 全程秒數 / 預設倍速
--template指定自訂模板(預設 assets/template.html)

已知坑(重要,改模板時別踩回去)

  1. 剖面填充失效:軌跡點(如 1006)可能少於剖面列數。若用「每列 min/max + 遇空列置 Infinity」,空列會讓 canvas 填充路徑變 NaN 而整塊不繪製。模板已改為 COLS = 600 + 分桶聚合 + 前向填充,保證無空桶。不要盲目把 COLS 調到大於點數。
  2. 綠色軌跡在衛星森林上看不見:低海拔用綠色會與林地同色。模板使用 青藍(低)→琥珀(中)→紅(高) 配色,並在彩色軌跡下加一條深色底襯 rgba(8,14,22,.65) 描邊。
  3. 循環線起點標籤被剖面面板擋住:起終點在地圖下方時,把旗幟 HTML 用 transform: translate(-50%,-100%) 讓文字在旗幟上方、整體底部對齊坐標點。
  4. 官方里程 vs 實測里程:實測幾何里程常與官方記錄有小差異(本例 10.29km vs 10.44km),展示應以官方為準,並把逐點累計值線性縮放,避免進度/數值對不上。
  5. 短路線的動畫時長:×1 全程按 clamp(km*24, 120, 480) 秒估算,倍速、里程樁間隔隨路線長度自適應,避免 10km 也用 200km 的參數(會有 25km 樁一個都畫不出來)。

模板

assets/template.html 是完整頁面,用 @@TOKEN@@ 佔位(@@TRACK@@、@@WAYPOINTS@@、 @@TOTAL_METERS@@、@@OFFICIAL_GAIN@@、@@ALT_LO@@、@@ALT_SPAN@@、@@SPEED_GROUP@@ 等)。 腳本做純字串替換並校驗無殘留 @@…@@。要改版式/配色,直接改模板即可,再傳 --template。

驗證建議

  1. 提取內聯腳本做語法檢查:
    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. 有條件時用 Playwright 無頭打開,監聽 pageerror,並調用頁面暴露的 window.__CAP.render(0.5) 截圖中段畫面確認軌跡與剖面正常。

目錄

kml-to-track-animation/
├── SKILL.md
├── assets/template.html          # 完整頁面模板(@@TOKEN@@ 佔位)
└── scripts/kml_to_animation.py   # KML/GPX 解析 + 統計 + 渲染

全域安裝

本技能位於個人技能庫 ~/Documents/Kagol/code/my-skills/,已在全域 ~/.config/opencode/opencode.json 的 skills.paths 中註冊該目錄(該目錄下所有 */SKILL.md 都會被全域載入)。修改設定或技能後需重啟 opencode 才會生效。

相關技能