Communitygithub.com

kml-to-track-animation

KML または GPX のハイキングトラックを、スタンドアロンのアニメーションルート HTML ページ(Leaflet 地図、標高グラデーションのトレイル、二人のハイカー、標高プロファイル、再生/シーク/速度、マイルストーン、キーポイントラベル)に変換します。

kml-to-track-animation とは?

このスキルは、KML または GPX 形式のハイキングトラックデータを、一つの自己完結型 HTML ファイルに変換します。生成される HTML は、Leaflet マップ上に標高に応じたグラデーションのルート、男女二人のハイカーのアニメーション、インタラクティブな標高プロファイル、再生/一時停止/速度変更などのコントロールを備えています。主な機能として、KML/GPX の解析、距離と累積標高差の自動計算、主要地点(最高点、スタート/ゴール)の自動配置、カスタマイズ可能なテンプレート、サイクリングルートの自動検出などがあります。このスキルは、Claude Code、Cursor、Codex などの AI エージェントが、ハイキングコースやサイクリングルートのビジュアライゼーションを迅速に作成するために使用できます。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

KML/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 に「2歩路/2bulu」拡張フィールド Data name="Distance" / ElevationGain がある場合、公式の値を優先し、各ポイントの累積距離と累積標高差を公式の総数に線形スケーリングします(--no-official で無効化可能)。
  • 最大標高に基づいて色の範囲を自動設定し、距離マーカー間隔、追従時のズームレベル、デフォルト速度、ハイカー間の距離を選択します。
  • キーポイントを自動配置: 最高点、次高点(ルート全体の8%以上離れている場合)、環状ルートの中間点。
  • 循環ルート(スタート/ゴールの距離が < 50m)は、1つの「スタート/ゴール」フラグに統合します。

よく使うパラメータ

パラメータ説明
--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-zoom2人の前後間隔(メートル)/ 追従時のズーム
--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 ごとのマーカーが1つも描画されないなどの問題を防ぎます)。

テンプレート

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 を再起動する必要があります。

関連スキル