Communitygithub.com

kml-to-track-animation

Wandelt eine KML- oder GPX-Wanderroute in eine eigenständige HTML-Animationsseite um (Leaflet-Karte, höhenverlaufende Spur, zwei Wanderer, Höhenprofil, Wiedergabe/Steuerung, Meilensteine, Ortsmarken).

Was ist kml-to-track-animation?

Dieses Skill wandelt KML- oder GPX-Wanderroutendateien in eine vollständige, eigenständige HTML-Datei um, die eine animierte Route auf einer Leaflet-Karte anzeigt. Es eignet sich ideal für Wanderer, Trailrunner und Outdoor-Enthusiasten, die ihre Routen interaktiv teilen möchten. Die erzeugte HTML-Seite enthält eine Leaflet-Karte mit Esri-Satelliten- oder OpenStreetMap-Kacheln, einen farblich nach Höhe gestuften Weg, zwei animierte Wanderer (Mann und Frau), ein klickbares Höhenprofil, Wiedergabe-/Pause-/Vor-/Zurückspul-Steuerung, Geschwindigkeitsanpassung, Kamerafolge, Ebenenumschaltung, Vollbildmodus sowie Start-, End- und Schlüsselpunkte-Markierungen. Es analysiert die Koordinaten aus KML oder GPX, berechnet Distanz und Höhenmeter, skaliert die kumulativen Werte auf die offiziellen Angaben (falls vorhanden) und passt Farben, Meilensteinabstände und Animationsgeschwindigkeiten automatisch an die Streckenlänge und Höhe an. Das Skill ist als Python-Skript implementiert (keine externen Abhängigkeiten außer der Python-Standardbibliothek) und verwendet eine anpassbare HTML-Vorlage mit Platzhaltern.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

KML/GPX → Wanderrouten-Animations-HTML

Wandelt eine Routendatei in ein eigenständiges HTML um: Leaflet-Karte + nach Höhe verlaufende Spur + zwei Wanderer (Mann/Frau) + klickbares Höhenprofil + Wiedergabe/Pause/Fortschritt/Geschwindigkeit/Folgen/Ebenen/Vollbild + Start-/Ziel- und Schlüsselpunkte-Markierungen + Ziel-Feier-Popup.

Die Seite lädt Leaflet beim Öffnen von einem CDN und verwendet Esri-Satelliten-/OpenStreetMap-Kacheln; daher ist eine Internetverbindung zum Betrachten erforderlich. Das generierte HTML ist eine einzelne Datei.

Schnellstart

python3 scripts/kml_to_animation.py Pfad/route.kml -o Ausgabe/route.html \
  --name "Doppelherz auf dem Yangtai-Berg" --region "Shenzhen" --emoji "🧡"

Benötigt nur die Python-3-Standardbibliothek. Die Ausgabedatei heißt standardmäßig wie die Eingabe mit .html.

python3 scripts/kml_to_animation.py route.kml            # route.html
python3 scripts/kml_to_animation.py route.gpx --help     # Alle Parameter anzeigen

Automatische Funktionen

  • Analysiert KML <coordinates> / <gx:coord> oder GPX <trkpt>, entfernt aufeinanderfolgende Duplikate.
  • Berechnet Distanz und Höhenmeter; falls das KML die 2bulu-Erweiterungsfelder Data name="Distance" / ElevationGain enthält, werden die offiziellen Werte bevorzugt und die kumulativen Distanzen/Höhenmeter werden linear auf die offiziellen Summen skaliert (kann mit --no-official deaktiviert werden).
  • Passt die Farbpalette automatisch an die maximale Höhe an, wählt Meilensteinabstände, Folgezoom, Standardgeschwindigkeit und Wanderabstände.
  • Platziert automatisch Schlüsselpunkte: Höchster Punkt, zweithöchster Punkt (mindestens 8 % der Gesamtstrecke entfernt), Mittelpunkt bei Rundwegen.
  • Rundwege (Start/Ziel Abstand < 50 m) werden zu einer einzigen „Start/Ziel“-Markierung zusammengefasst.

Häufig verwendete Parameter

ParameterBeschreibung
--nameRoutenname (wird standardmäßig für Titel und Etiketten verwendet)
--emoji / --badgeSymbol vor dem Titel / Text des Abzeichens (Standard: <km>KM)
--regionPräfix für Untertitel (z. B. „Shenzhen“)
--subtitleÜberschreibt den Untertitel mit benutzerdefiniertem HTML
--start-labelText der Start-/Ziel-Markierung
--finish-titleTitel des Ziel-Popups
--milestone-kmAbstand zwischen Meilensteinen (km)
--waypoints-jsonBenutzerdefinierte Schlüsselpunkte als JSON: [{"frac":0.82,"emoji":"🏔️","name":"Höchster Punkt","alt":"579m"}]
--lead / --follow-zoomAbstand der beiden Wanderer (Meter) / Zoom beim Folgen
--base-duration / --speed-mult×1 Gesamtzeit in Sekunden / Standardgeschwindigkeitsmultiplikator
--templatePfad zu einer benutzerdefinierten Vorlage (Standard: assets/template.html)

Bekannte Fallstricke (wichtig beim Bearbeiten der Vorlage)

  1. Höhenprofil-Füllung fehlgeschlagen: Die Anzahl der Streckenpunkte (z. B. 1006) kann geringer sein als die Anzahl der Spalten im Profil. Bei Verwendung von „Min/Max pro Spalte + Infinity für leere Spalten“ führen leere Spalten zu NaN-Werten im Canvas-Füllpfad, sodass der gesamte Bereich nicht gezeichnet wird. Die Vorlage verwendet daher COLS = 600 + Bucket-Aggregation + Vorwärts-Füllung, um leere Buckets zu vermeiden. Nicht blind COLS auf einen Wert größer als die Punktanzahl erhöhen.
  2. Grüne Spur im Satelliten-Wald unsichtbar: Niedrige Höhen in Grün heben sich nicht vom Wald ab. Die Vorlage verwendet die Farbpalette Blaugrün (niedrig) → Bernstein (mittel) → Rot (hoch) und fügt unter der farbigen Spur eine dunkle Kontur rgba(8,14,22,.65) hinzu.
  3. Startetikett bei Rundwegen durch Höhenprofil-Panel verdeckt: Liegt Start/Ziel unterhalb der Karte, wird das Markierungs-HTML mit transform: translate(-50%,-100%) so positioniert, dass der Text oberhalb der Markierung und der untere Rand am Koordinatenpunkt ausgerichtet ist.
  4. Offizielle vs. tatsächliche Distanz: Die gemessene geometrische Distanz weicht oft geringfügig von den offiziellen Angaben ab (z. B. 10,29 km vs. 10,44 km). Die Anzeige sollte die offiziellen Werte priorisieren und die kumulativen Punktwerte linear skalieren, um Abweichungen bei Fortschritt/Werten zu vermeiden.
  5. Animationsdauer bei kurzen Strecken: Die ×1-Gesamtzeit wird mit clamp(km*24, 120, 480) Sekunden geschätzt; Geschwindigkeitsmultiplikator und Meilensteinabstände passen sich automatisch an die Streckenlänge an, sodass eine 10 km-Strecke nicht die Parameter einer 200 km-Strecke verwendet (sonst könnte bei 25 km-Abständen kein Meilenstein gezeichnet werden).

Vorlage

assets/template.html ist die vollständige Seite und verwendet @@TOKEN@@-Platzhalter (@@TRACK@@, @@WAYPOINTS@@, @@TOTAL_METERS@@, @@OFFICIAL_GAIN@@, @@ALT_LO@@, @@ALT_SPAN@@, @@SPEED_GROUP@@ usw.). Das Skript führt eine reine Zeichenkettenersetzung durch und prüft auf verbleibende @@…@@. Zum Ändern von Layout/Farben einfach die Vorlage direkt bearbeiten und mit --template übergeben.

Validierungsvorschläge

  1. Inline-Skript extrahieren und Syntax prüfen:
    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. Falls möglich, die Seite mit Playwright im Headless-Modus öffnen, pageerror überwachen und das von der Seite bereitgestellte window.__CAP.render(0.5) aufrufen, um eine Momentaufnahme der Mitte der Strecke zu machen und Spur sowie Profil zu überprüfen.

Verzeichnisstruktur

kml-to-track-animation/
├── SKILL.md
├── assets/template.html          # Vollständige Seitenvorlage (@@TOKEN@@ Platzhalter)
└── scripts/kml_to_animation.py   # KML/GPX-Parsing + Statistik + Rendering

Globale Installation

Dieses Skill befindet sich im persönlichen Skill-Repository ~/Documents/Kagol/code/my-skills/ und wurde in der globalen Konfiguration ~/.config/opencode/opencode.json unter skills.paths registriert (dieses Verzeichnis enthält alle */SKILL.md, die global geladen werden). Nach Änderungen an der Konfiguration oder am Skill muss opencode neu gestartet werden, damit die Änderungen wirksam werden.

Verwandte Skills