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ètre | Description |
|---|---|
--name | Nom de l'itinéraire (utilisé par défaut pour le titre et les étiquettes) |
--emoji / --badge | Emoji / texte du badge avant le titre (par défaut <km>KM) |
--region | Préfixe du sous-titre (ex. « Shenzhen ») |
--subtitle | Remplace le sous-titre par un code HTML personnalisé |
--start-label | Texte du drapeau de départ/arrivée |
--finish-title | Titre du popup de fin |
--milestone-km | Intervalle des jalons de distance (en km) |
--waypoints-json | JSON personnalisé des points clés : [{"frac":0.82,"emoji":"🏔️","name":"Sommet","alt":"579m"}] |
--lead / --follow-zoom | Distance entre les deux randonneurs (m) / zoom lors du suivi |
--base-duration / --speed-mult | Durée totale à ×1 (secondes) / multiplicateur de vitesse par défaut |
--template | Spé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)
- 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 pasCOLSà une valeur supérieure au nombre de points. - 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é. - 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. - 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.
- 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
- 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 - Si possible, ouvrez la page avec Playwright en mode headless, écoutez
pageerror, et appelez la fonction exposéewindow.__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.