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âmetro | Descrição |
|---|---|
--name | Nome da rota (usado no título e etiquetas) |
--emoji / --badge | Ícone / texto do emblema antes do título (padrão <km>KM) |
--region | Prefixo do subtítulo (ex.: "Shenzhen") |
--subtitle | Substitui o subtítulo por HTML personalizado |
--start-label | Texto da bandeira de início/fim |
--finish-title | Título do pop-up de chegada |
--milestone-km | Espaçamento dos marcos de quilometragem (km) |
--waypoints-json | JSON personalizado de pontos-chave: [{"frac":0.82,"emoji":"🏔️","name":"Ponto Mais Alto","alt":"579m"}] |
--lead / --follow-zoom | Distância entre os dois caminhantes (metros) / zoom ao seguir |
--base-duration / --speed-mult | Duração total em segundos na velocidade ×1 / multiplicador de velocidade padrão |
--template | Caminho para um template personalizado (padrão assets/template.html) |
Problemas Conhecidos (Importante – não os reintroduza ao modificar o template)
- 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 aumenteCOLScegamente para um valor maior que o número de pontos. - 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. - 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. - 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.
- 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
- 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 - Se possível, use Playwright para abrir a página sem cabeçalho, escute
pageerrore chamewindow.__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.