Communitygithub.com

KML/GPX → 徒步轨迹动画 HTML

将 KML 或 GPX 徒步轨迹转换为独立的动画路线 HTML 页面,包含 Leaflet 地图、海拔渐变轨迹、两个徒步小人、海拔剖面图、播放/搜索/速度控制、里程碑和关键点标注。

GPX → 徒步轨迹动画 HTML란 무엇인가요?

该技能专为将 KML 或 GPX 格式的徒步轨迹文件转化为一个自包含、可交互的 HTML 页面而设计。页面包含 Leaflet 地图、按海拔渐变的彩色轨迹线、一男一女两个并排行走的徒步小人、可点击跳转的海拔剖面图、播放/暂停/进度/倍速控制、跟随模式、图层切换、全屏显示,以及起点、终点和关键点标注,并在到达终点时显示庆祝弹窗。它支持自定义路线名称、表情符号、区域、副标题、里程碑间隔、关键点(通过 JSON 文件)、两人间距、跟随缩放、基础持续时间和默认倍速等参数。该脚本仅依赖 Python 3 标准库,解析 KML `<coordinates>` 或 GPX `<trkpt>` 数据,自动计算距离和爬升,并优先使用官方距离/爬升数据(如果轨迹文件包含来自“两步路”等平台的扩展字段)。生成的 HTML 从 CDN 加载 Leaflet 和地图瓦片,因此需要网络连接才能查看。该技能还包含一个模板系统 (`assets/template.html`),使用 `@@TOKEN@@` 占位符进行字符串替换,方便自定义页面布局和配色方案。

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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

관련 스킬