Communitygithub.com

kml-to-track-animation

Transformez un fichier KML ou GPX en une page HTML autonome d'animation de randonnée (carte Leaflet, tracé coloré par altitude, deux randonneurs, profil d'élévation, lecture/pause/vitesse, jalons, étiquettes).

Qu'est-ce que kml-to-track-animation ?

Ce skill transforme un fichier de trace GPS au format KML ou GPX en une page HTML autonome affichant une animation interactive de randonnée. La page générée inclut une carte Leaflet avec un tracé coloré en fonction de l'altitude, deux personnages marchant (un homme et une femme), un profil d'élévation cliquable, des commandes de lecture/pause/avance rapide, des jalons de distance, et une fenêtre de célébration à l'arrivée. Le script Python (sans dépendances externes) calcule la distance et le dénivelé, gère les points clés (sommet, point intermédiaire, départ/arrivée), et s'adapte automatiquement aux données officielles si présentes (ex. depuis l'application 2bulu). La sortie est un fichier HTML unique qui charge Leaflet et les tuiles cartographiques depuis un CDN. Le skill est utilisé via une commande en ligne avec de nombreux paramètres de personnalisation (nom de l'itinéraire, emoji, badges, intervalle des jalons, etc.).

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

KML/GPX → Animation de trace de randonnée en HTML

Transformez un fichier de trace en un fichier HTML autonome : carte Leaflet + tracé dégradé selon l'altitude + duettiste de randonneurs (homme + femme) + profil d'élévation cliquable + lecture/pause/progression/vitesse/suivi/calques/plein écran + étiquettes de départ, d'arrivée et de points clés + popup de célébration à la fin.

Lors de l'ouverture de la page, Leaflet est chargé depuis un CDN et utilise les tuiles Esri Satellite / OpenStreetMap ; une connexion réseau est donc nécessaire. Le fichier HTML généré est un fichier unique.

Démarrage rapide

python3 scripts/kml_to_animation.py chemin/trace.kml -o sortie/trace.html \
  --name "Double cœur du mont Yangtai" --region "Shenzhen" --emoji "🧡"

Ne dépend que de la bibliothèque standard de Python 3. Par défaut, le fichier de sortie a le même nom que l'entrée avec l'extension .html.

python3 scripts/kml_to_animation.py route.kml            # route.html
python3 scripts/kml_to_animation.py route.gpx --help     # Voir tous les paramètres

Ce qu'il fait automatiquement

  • Analyse les <coordinates> / <gx:coord> KML ou <trkpt> GPX, supprime les points consécutifs en double.
  • Calcule la distance et le dénivelé ; si le KML contient les champs étendus "两步路/2bulu" Data name="Distance" / ElevationGain, il utilise en priorité les valeurs officielles et redimensionne linéairement les distances cumulatives et le dénivelé par point pour correspondre aux totaux officiels (peut être désactivé avec --no-official).
  • Définit automatiquement la plage de couleurs en fonction de l'altitude maximale, choisit l'intervalle des jalons de distance, le zoom de suivi, la vitesse par défaut et l'espacement entre les randonneurs.
  • Place automatiquement les points clés : point culminant, deuxième point le plus haut (à au moins 8 % de la distance totale), et un point intermédiaire pour les boucles.
  • Pour les boucles (distance départ-arrivée < 50 m), il fusionne les drapeaux en un seul « Départ / Arrivée ».

Paramètres courants

ParamètreDescription
--nameNom de l'itinéraire (utilisé par défaut pour le titre et les étiquettes)
--emoji / --badgeEmoji / texte du badge avant le titre (par défaut <km>KM)
--regionPréfixe du sous-titre (ex. « Shenzhen »)
--subtitleRemplace le sous-titre par un code HTML personnalisé
--start-labelTexte du drapeau de départ/arrivée
--finish-titleTitre du popup de fin
--milestone-kmIntervalle des jalons de distance (en km)
--waypoints-jsonJSON personnalisé des points clés : [{"frac":0.82,"emoji":"🏔️","name":"Sommet","alt":"579m"}]
--lead / --follow-zoomDistance entre les deux randonneurs (m) / zoom lors du suivi
--base-duration / --speed-multDurée totale à ×1 (secondes) / multiplicateur de vitesse par défaut
--templateSpécifie un modèle personnalisé (par défaut assets/template.html)

Pièges connus (importants, ne pas réintroduire lors de la modification du modèle)

  1. Remplissage du profil défaillant : Le nombre de points de trace (ex. 1006) peut être inférieur au nombre de colonnes du profil. Si l'on utilise « min/max par colonne + Infinity pour les colonnes vides », les colonnes vides rendent le chemin de remplissage du canvas NaN et l'ensemble n'est pas dessiné. Le modèle a été modifié pour utiliser COLS = 600 + agrégation par bucket + remplissage avant, garantissant l'absence de bucket vide. Ne réglez pas COLS à une valeur supérieure au nombre de points.
  2. Le tracé vert est invisible sur la forêt satellite : Les basses altitudes en vert se fondent avec la couleur forestière. Le modèle utilise une palette Cyan (bas) → Ambre (moyen) → Rouge (haut), et ajoute un liseré foncé rgba(8,14,22,.65) en dessous du tracé coloré.
  3. L'étiquette du départ d'une boucle est masquée par le panneau du profil : Lorsque le départ/arrivée est en bas de la carte, le code HTML du drapeau utilise transform: translate(-50%,-100%) pour placer le texte au-dessus du drapeau, alignant le bas de l'élément sur les coordonnées.
  4. Distance officielle vs distance mesurée : La distance géométrique mesurée diffère souvent légèrement de la distance officielle (ex. 10,29 km vs 10,44 km). L'affichage doit privilégier la valeur officielle, et les cumuls par point sont redimensionnés linéairement pour éviter les décalages de progression.
  5. Durée d'animation pour les courtes distances : La durée totale à ×1 est estimée par clamp(km*24, 120, 480) secondes. La vitesse et l'intervalle des jalons s'adaptent à la longueur du parcours pour éviter qu'une trace de 10 km utilise les paramètres d'une trace de 200 km (ce qui ne dessinerait aucun jalon).

Modèle

assets/template.html est la page complète, utilisant des marqueurs @@TOKEN@@ (@@TRACK@@, @@WAYPOINTS@@, @@TOTAL_METERS@@, @@OFFICIAL_GAIN@@, @@ALT_LO@@, @@ALT_SPAN@@, @@SPEED_GROUP@@, etc.). Le script effectue un remplacement de chaîne pur et vérifie qu'il ne reste aucun @@…@@. Pour modifier la mise en page ou les couleurs, éditez directement le modèle, puis passez --template.

Suggestions de validation

  1. Extraire le script inline pour une vérification syntaxique :
    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. Si possible, ouvrez la page avec Playwright en mode headless, écoutez pageerror, et appelez la fonction exposée window.__CAP.render(0.5) pour capturer une image du milieu du trajet et vérifier que la trace et le profil sont corrects.

Arborescence

kml-to-track-animation/
├── SKILL.md
├── assets/template.html          # Modèle de page complet (marqueurs @@TOKEN@@)
└── scripts/kml_to_animation.py   # Analyse KML/GPX + statistiques + rendu

Installation globale

Ce skill se trouve dans le dossier de compétences personnel ~/Documents/Kagol/code/my-skills/, déjà enregistré globalement dans ~/.config/opencode/opencode.json via skills.paths (tous les */SKILL.md de ce dossier sont chargés globalement). Après une modification de la configuration ou du skill, redémarrez opencode pour que les changements prennent effet.

Skills associés