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) |
已知坑(重要,改模板時別踩回去)
- 剖面填充失效:軌跡點(如 1006)可能少於剖面列數。若用「每列 min/max + 遇空列置 Infinity」,空列會讓 canvas 填充路徑變 NaN 而整塊不繪製。模板已改為
COLS = 600+ 分桶聚合 + 前向填充,保證無空桶。不要盲目把COLS調到大於點數。 - 綠色軌跡在衛星森林上看不見:低海拔用綠色會與林地同色。模板使用 青藍(低)→琥珀(中)→紅(高) 配色,並在彩色軌跡下加一條深色底襯
rgba(8,14,22,.65)描邊。 - 循環線起點標籤被剖面面板擋住:起終點在地圖下方時,把旗幟 HTML 用
transform: translate(-50%,-100%)讓文字在旗幟上方、整體底部對齊坐標點。 - 官方里程 vs 實測里程:實測幾何里程常與官方記錄有小差異(本例 10.29km vs 10.44km),展示應以官方為準,並把逐點累計值線性縮放,避免進度/數值對不上。
- 短路線的動畫時長:×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。
驗證建議
- 提取內聯腳本做語法檢查:
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 - 有條件時用 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 才會生效。