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 才会生效。