Communitygithub.com

KML/GPX → Animação de Trilha para Caminhada

Use este skill para converter um arquivo KML ou GPX de uma trilha para caminhada em uma página HTML independente e animada, com mapa Leaflet, trilha colorida por altitude, dois caminhantes animados, perfil de elevação interativo e controles de reprodução.

O que é GPX → Animação de Trilha para Caminhada?

Este skill converte arquivos de rota nos formatos KML e GPX em uma página HTML autônoma e interativa, ideal para visualizar e compartilhar trilhas de caminhada. A página gerada inclui um mapa Leaflet com tiles do Esri Satellite ou OpenStreetMap, uma trilha colorida de acordo com a altitude (gradiente do azul ao vermelho), dois caminhantes animados (um masculino e um feminino) que percorrem a rota juntos, um perfil de elevação clicável que permite pular para qualquer ponto da trilha, controles de reprodução (play/pause, velocidade, busca, modo seguir) e suporte a tela cheia. O script analisa automaticamente as coordenadas KML ou GPX, calcula distância e ganho de elevação (priorizando valores oficiais presentes em extensões como '2bulu'), ajusta a escala de cores com base na altitude máxima, insere marcadores para pontos-chave (pico mais alto, ponto médio, início/fim) e gera um pop-up de celebração no final da rota. O skill foi desenvolvido para ser executado com Python 3 padrão, não requer dependências externas, e é compatível com qualquer sistema operacional que tenha Python 3 instalado. É particularmente útil para entusiastas de caminhadas, desenvolvedores criando visualizações de rotas, ou qualquer pessoa que queira compartilhar uma trilha de forma visual e interativa sem depender de serviços online específicos.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que GPX → Animação de Trilha para Caminhada faz?

Renderiza um arquivo de rota em um HTML autônomo: mapa Leaflet + trilha com gradiente de altitude + dois caminhantes (um homem e uma mulher) percorrendo a rota juntos + perfil de elevação clicável + controles de reprodução/pausa/progresso/velocidade/seguir/camadas/tela cheia + marcadores de início, fim e pontos-chave + pop-up de celebração no final.

A página carrega Leaflet de um CDN e usa tiles do Esri Satellite / OpenStreetMap, então requer internet para visualização; o HTML gerado é um único arquivo.

Início Rápido

python3 scripts/kml_to_animation.py caminho/trilha.kml -o saida/trilha.html \
  --name "Coração Duplo de Yangtai" --region "Shenzhen" --emoji "🧡"

Depende apenas da biblioteca padrão do Python 3. A saída padrão é um arquivo .html com o mesmo nome da entrada.

python3 scripts/kml_to_animation.py route.kml            # route.html
python3 scripts/kml_to_animation.py route.gpx --help     # Ver todos os parâmetros

O que ele faz automaticamente

  • Analisa as coordenadas KML <coordinates> / <gx:coord> ou GPX <trkpt>, removendo pontos duplicados consecutivos.
  • Calcula distância e ganho de elevação; se o KML tiver campos de extensão "2bulu" Data name="Distance" / ElevationGain, usa os valores oficiais como prioridade e dimensiona linearmente a distância acumulada e o ganho de elevação ponto a ponto para os totais oficiais (pode ser desabilitado com --no-official).
  • Determina automaticamente o intervalo de cores com base na altitude máxima, escolhe o espaçamento dos marcos de quilometragem, o zoom de seguimento, a velocidade padrão e a distância entre os caminhantes.
  • Coloca automaticamente pontos-chave: ponto mais alto, segundo ponto mais alto (com distância mínima de 8% do percurso total), ponto médio de rotas circulares.
  • Rotas circulares (início e fim com distância < 50m) são combinadas em uma única bandeira "Início / Fim".

Parâmetros Comuns

ParâmetroDescrição
--nameNome da rota (usado no título e etiquetas)
--emoji / --badgeÍcone / texto do emblema antes do título (padrão <km>KM)
--regionPrefixo do subtítulo (ex.: "Shenzhen")
--subtitleSubstitui o subtítulo por HTML personalizado
--start-labelTexto da bandeira de início/fim
--finish-titleTítulo do pop-up de chegada
--milestone-kmEspaçamento dos marcos de quilometragem (km)
--waypoints-jsonJSON personalizado de pontos-chave: [{"frac":0.82,"emoji":"🏔️","name":"Ponto Mais Alto","alt":"579m"}]
--lead / --follow-zoomDistância entre os dois caminhantes (metros) / zoom ao seguir
--base-duration / --speed-multDuração total em segundos na velocidade ×1 / multiplicador de velocidade padrão
--templateCaminho para um template personalizado (padrão assets/template.html)

Problemas Conhecidos (Importante – não os reintroduza ao modificar o template)

  1. Falha no preenchimento do perfil: Os pontos da trilha (ex.: 1006) podem ser menos que o número de colunas do perfil. Se for usado "min/max por coluna + Infinity em coluna vazia", colunas vazias fazem com que o caminho de preenchimento do canvas se torne NaN e nada seja desenhado. O template foi alterado para COLS = 600 + agregação por balde + preenchimento para frente, garantindo que não haja baldes vazios. Não aumente COLS cegamente para um valor maior que o número de pontos.
  2. Trilha verde invisível em floresta de satélite: Verde em baixas altitudes se confunde com a vegetação. O template usa um esquema de cores azul (baixo) → âmbar (médio) → vermelho (alto) e adiciona um contorno escuro rgba(8,14,22,.65) abaixo da trilha colorida.
  3. Etiqueta de início em rota circular fica oculta pelo painel de perfil: Quando o ponto de início/fim está na parte inferior do mapa, a bandeira HTML usa transform: translate(-50%,-100%) para que o texto fique acima da bandeira e a base do elemento alinhe com as coordenadas.
  4. Distância oficial vs. distância calculada: A distância geométrica calculada geralmente difere um pouco do valor oficial (ex.: 10,29 km vs. 10,44 km). A exibição deve priorizar o valor oficial e escalar linearmente os valores acumulados ponto a ponto para evitar discrepâncias entre progresso e valores.
  5. Duração da animação para rotas curtas: A duração total em ×1 é estimada como clamp(km*24, 120, 480) segundos. A velocidade e o espaçamento dos marcos de quilometragem se adaptam ao comprimento da rota, para evitar que uma rota de 10 km use parâmetros de uma de 200 km (o que resultaria em nenhum marco de 25 km sendo desenhado).

Template

assets/template.html é a página completa, usando placeholders @@TOKEN@@ (@@TRACK@@, @@WAYPOINTS@@, @@TOTAL_METERS@@, @@OFFICIAL_GAIN@@, @@ALT_LO@@, @@ALT_SPAN@@, @@SPEED_GROUP@@ etc.). O script faz substituição de string e verifica se não restou nenhum @@…@@. Para alterar layout/cores, modifique o template diretamente e use --template.

Sugestões de Validação

  1. Extraia o script inline para verificação de sintaxe:
    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. Se possível, use Playwright para abrir a página sem cabeçalho, escute pageerror e chame window.__CAP.render(0.5) exposto pela página para capturar uma imagem do meio do percurso e confirmar que a trilha e o perfil estão corretos.

Estrutura do Diretório

kml-to-track-animation/
├── SKILL.md
├── assets/template.html          # Template completo da página (placeholders @@TOKEN@@)
└── scripts/kml_to_animation.py   # Análise KML/GPX + estatísticas + renderização

Instalação Global

Este skill está localizado no repositório pessoal de skills ~/Documents/Kagol/code/my-skills/, já registrado no caminho skills.paths do arquivo global ~/.config/opencode/opencode.json (todos os */SKILL.md nesse diretório são carregados globalmente). Após modificar a configuração ou o skill, é necessário reiniciar o opencode para que as alterações tenham efeito.

Habilidades Relacionadas