KML/GPX → Animación de ruta de senderismo HTML
Convierte un archivo de ruta en un HTML autónomo: mapa Leaflet + sendero con gradiente de altitud + dos excursionistas (hombre y mujer) caminando juntos + perfil de elevación interactivo con clics + reproducción/pausa/progreso/velocidad/seguimiento/capas/pantalla completa + etiquetas de inicio, fin y puntos clave + ventana emergente de celebración al llegar al final.
Al abrir la página, carga Leaflet desde un CDN y utiliza mosaicos de Esri satélite / OpenStreetMap, por lo que se necesita conexión a Internet durante la navegación; el HTML generado es un solo archivo.
Inicio rápido
python3 scripts/kml_to_animation.py ruta/track.kml -o salida/ruta.html \
--name "Doble Corazón de Yángtái" --region "Shenzhen" --emoji "🧡"
Solo depende de la biblioteca estándar de Python 3. Por defecto, genera un archivo .html con el mismo nombre que la entrada.
python3 scripts/kml_to_animation.py route.kml # route.html
python3 scripts/kml_to_animation.py route.gpx --help # Ver todos los parámetros
Lo que hace automáticamente
- Analiza las coordenadas
<coordinates>/<gx:coord>de KML o los puntos<trkpt>de GPX, eliminando puntos consecutivos duplicados. - Calcula la distancia y el desnivel acumulado; si el KML incluye campos extendidos de "2bulu" como
Data name="Distance"/ElevationGain, usa los valores oficiales y escala linealmente la distancia y el desnivel acumulados punto a punto a los totales oficiales (se puede desactivar con--no-official). - Determina automáticamente el rango de colores según la altitud máxima, la separación de los hitos de distancia, el zoom de seguimiento, la velocidad predeterminada y la separación entre los dos excursionistas.
- Coloca automáticamente puntos clave: el punto más alto, el segundo punto más alto (al menos a un 8% de la ruta total) y un punto intermedio en rutas circulares.
- Las rutas circulares (puntos de inicio y fin a menos de 50 m) fusionan las banderas de inicio y fin en una sola.
Parámetros comunes
| Parámetro | Descripción |
|---|---|
--name | Nombre de la ruta (usado por defecto en el título y las etiquetas) |
--emoji / --badge | Icono / texto de insignia antes del título (por defecto <km>KM) |
--region | Prefijo del subtítulo (ej. "Shenzhen") |
--subtitle | Sobrescribe el subtítulo con HTML personalizado |
--start-label | Texto de la bandera de inicio/fin |
--finish-title | Título de la ventana emergente de finalización |
--milestone-km | Intervalo entre hitos de distancia (km) |
--waypoints-json | JSON personalizado de puntos clave: [{"frac":0.82,"emoji":"🏔️","name":"Punto más alto","alt":"579m"}] |
--lead / --follow-zoom | Separación entre los dos excursionistas (metros) / zoom durante el seguimiento |
--base-duration / --speed-mult | Segundos a ×1 de duración total / velocidad predeterminada |
--template | Especifica una plantilla personalizada (por defecto assets/template.html) |
Problemas conocidos (importante, no reintroducir al modificar la plantilla)
- Relleno del perfil roto: Los puntos del track (ej. 1006) pueden ser menos que las columnas del perfil. Si se usa "min/max por columna + Infinity en columna vacía", las columnas vacías hacen que el trazado de relleno del canvas sea NaN y todo el bloque no se dibuja. La plantilla ahora usa
COLS = 600+ agregación por cubos + relleno hacia adelante, garantizando que no haya cubos vacíos. No aumentesCOLSciegamente por encima del número de puntos. - Sendero verde invisible en bosques satelitales: El verde en altitudes bajas se confunde con el color del bosque. La plantilla usa una combinación de colores cian (bajo) → ámbar (medio) → rojo (alto) y añade un borde oscuro de fondo
rgba(8,14,22,.65)debajo del sendero coloreado. - Etiqueta de inicio de ruta circular oculta por el panel de perfil: Cuando el punto de inicio/fin está en la parte inferior del mapa, la bandera HTML se desplaza con
transform: translate(-50%,-100%)para que el texto quede encima de la bandera y la parte inferior esté alineada con las coordenadas. - Distancia oficial vs. distancia medida: La distancia geométrica medida suele diferir ligeramente de la oficial (ej. 10.29 km vs. 10.44 km). La visualización debe basarse en la oficial, escalando linealmente los valores acumulados punto a punto para evitar discrepancias en el progreso/números.
- Duración de la animación para rutas cortas: La duración total a ×1 se estima como
clamp(km*24, 120, 480)segundos; la velocidad y el intervalo de hitos se adaptan a la longitud de la ruta para evitar que rutas de 10 km usen parámetros de 200 km (de lo contrario, podría no dibujarse ningún hito de 25 km).
Plantilla
assets/template.html es la página completa, con marcadores de posición @@TOKEN@@ (como @@TRACK@@, @@WAYPOINTS@@,
@@TOTAL_METERS@@, @@OFFICIAL_GAIN@@, @@ALT_LO@@, @@ALT_SPAN@@, @@SPEED_GROUP@@, etc.).
El script realiza reemplazos de cadenas y verifica que no queden @@...@@ sin reemplazar. Para cambiar el diseño/colores, simplemente modifica la plantilla y luego pasa --template.
Sugerencias de validación
- Extraer el script en línea para verificar la sintaxis:
python3 - <<'PY' import re;h=open("salida.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/salida.js","w",encoding="utf-8").write(js) PY node --check /tmp/salida.js - Si es posible, abrir sin cabeza con Playwright, escuchar
pageerror, y llamar a la función expuestawindow.__CAP.render(0.5)para capturar la parte media de la ruta y verificar que el sendero y el perfil sean correctos.
Estructura del directorio
kml-to-track-animation/
├── SKILL.md
├── assets/template.html # Plantilla de página completa (marcadores @@TOKEN@@)
└── scripts/kml_to_animation.py # Análisis KML/GPX + estadísticas + renderizado
Instalación global
Esta habilidad se encuentra en el repositorio de habilidades personales ~/Documents/Kagol/code/my-skills/ y está registrada globalmente en ~/.config/opencode/opencode.json en la clave skills.paths (todos los */SKILL.md en ese directorio se cargan globalmente). Tras modificar la configuración o la habilidad, es necesario reiniciar opencode para que los cambios surtan efecto.