Communitygithub.com

kml-to-track-animation

Convierte un track KML o GPX en una página HTML animada de ruta de senderismo con mapa Leaflet, sendero con gradiente de altitud, dos excursionistas caminando, perfil de elevación, reproducción/búsqueda/velocidad, hitos y etiquetas de puntos clave.

¿Qué es kml-to-track-animation?

Esta habilidad toma un archivo KML o GPX de una ruta de senderismo y genera un archivo HTML autónomo que muestra la ruta en un mapa Leaflet con un sendero coloreado por altitud, dos figuras animadas (un hombre y una mujer) caminando juntos, un perfil de elevación interactivo con clics, controles de reproducción/pausa/avance/velocidad/seguimiento, capas de mapa, pantalla completa, etiquetas de inicio, fin y puntos clave, y una ventana emergente de celebración al llegar al final. La página se puede abrir en cualquier navegador moderno con conexión a Internet para cargar Leaflet desde CDN y los mosaicos de mapas. Es compatible con plataformas como Claude Code, Cursor y Codex, y se ejecuta con Python 3 estándar. La habilidad calcula automáticamente la distancia, el desnivel, los colores del sendero, los intervalos de hitos y la velocidad de animación, y admite parámetros opcionales como nombre de ruta, región, emoji, etiquetas personalizadas y puntos de referencia. Es útil para creadores de contenido, excursionistas o desarrolladores que desean compartir rutas de senderismo de forma visual e interactiva sin necesidad de servicios en línea más allá de la carga inicial de mapas.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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ámetroDescripción
--nameNombre de la ruta (usado por defecto en el título y las etiquetas)
--emoji / --badgeIcono / texto de insignia antes del título (por defecto <km>KM)
--regionPrefijo del subtítulo (ej. "Shenzhen")
--subtitleSobrescribe el subtítulo con HTML personalizado
--start-labelTexto de la bandera de inicio/fin
--finish-titleTítulo de la ventana emergente de finalización
--milestone-kmIntervalo entre hitos de distancia (km)
--waypoints-jsonJSON personalizado de puntos clave: [{"frac":0.82,"emoji":"🏔️","name":"Punto más alto","alt":"579m"}]
--lead / --follow-zoomSeparación entre los dos excursionistas (metros) / zoom durante el seguimiento
--base-duration / --speed-multSegundos a ×1 de duración total / velocidad predeterminada
--templateEspecifica una plantilla personalizada (por defecto assets/template.html)

Problemas conocidos (importante, no reintroducir al modificar la plantilla)

  1. 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 aumentes COLS ciegamente por encima del número de puntos.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  1. 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
    
  2. Si es posible, abrir sin cabeza con Playwright, escuchar pageerror, y llamar a la función expuesta window.__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.

Skills relacionados