Communitygithub.com

Vibetool/GeoReel

Gera vídeos cinematográficos de sobrevoo em mapas 3D a partir de uma cena JSON — uma skill de agente para o gênero 三维地图看世界 (terreno real, câmera automática, rotas autodesenháveis, tomadas de viagem, tiles 3D, TTS).

O que é GeoReel?

Esta skill permite que agentes de IA (como Claude Code) criem vídeos de sobrevoo em mapas 3D de alta qualidade, sem necessidade de After Effects ou Earth Studio. Ela renderiza cenas do CesiumJS quadro a quadro em um Chrome headless e monta o vídeo final em MP4 usando ffmpeg. O usuário descreve a cena em um arquivo JSON, definindo pontos de interesse, rotas animadas, tomadas de câmera (fly-in, órbita, viagem), narração por TTS e músicas de fundo. A skill suporta terrenos 3D reais do Cesium World Terrain, tiles 3D fotorealísticos do Google (para cidades) e uma exageração vertical que faz o relevo das montanhas se destacar. Recursos inteligentes como anticolisão de rótulos, animação de desenho de rotas e transições suaves (dip-to-white ou crossfade) são automáticos. O renderizador é paralelizável (várias instâncias do Chrome), inclui um modo de pré-visualização rápida e gerencia timeouts de tiles para evitar quadros piscando. O resultado é um vídeo silencioso ou com áudio, pronto para publicação.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add Vibetool/GeoReel

Perguntar na sua IA favorita

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

Documentação

geo-flyover — Gerador de Animação de Sobrevoo 3D

Renderiza uma cena do globo 3D do Cesium (CesiumJS) quadro a quadro no Chrome headless, depois monta um MP4 com ffmpeg. Sem necessidade de After Effects / Earth Studio.

Requisitos

  • Node ≥ 18, Google Chrome instalado, ffmpeg no PATH (tudo verificado nesta máquina).
  • Variável de ambiente CESIUM_ION_TOKEN (conta gratuita em https://ion.cesium.com → Access Tokens). Com um token você obtém Cesium World Imagery + World Terrain (montanhas 3D). Sem ele, o renderizador cai para os tiles de satélite Esri World Imagery em um elipsoide PLANO — assistível, mas sem relevo 3D.
  • Primeira execução: cd render && npm install (instala apenas puppeteer-core, leve).

Fluxo de trabalho

  1. Crie uma cena JSON (veja scenes/putuoshan-demo.json e o esquema abaixo). Obtenha coordenadas via pesquisa na web ou seu conhecimento; verifique aproximadamente a lng/lat dos POIs na imagem.
  2. Renderize: cd <diretório-da-skill>/render && node render.mjs ../scenes/<cena>.json </caminho/para/saida>
    • Gera frames/f_0001.png... e depois monta <dir-saida>/<nome>.mp4 automaticamente.
    • Velocidade de renderização ~1–3 fps; um vídeo de 10 s / 300 quadros leva alguns minutos. Execute em segundo plano e consulte.
  3. Verifique: Leia 2–3 quadros de exemplo como imagens (início/meio/fim). Verifique: terreno carregado (não em branco), rótulos legíveis, progresso do desenho da rota.
  4. Entregue o caminho do MP4 ao usuário. Para vídeos finais, sugira 1920x1080.

Recomendado: câmera baseada em tomadas (automática, use em vez de escrever cameraPath manualmente)

"preset": "1080p",   // 720p | 1080p | 4k — fontes/pontos/larguras de linha escalam automaticamente com a resolução
"shots": [
  { "type": "flyin", "duration": 5, "pitch": -33, "viewFrom": 178 },  // viewFrom: direção da bússola do alvo→câmera (178 = câmera quase ao sul)
  { "type": "orbit", "duration": 6, "sweep": -14 },                    // arqueia a câmera em sweep°, o alvo permanece centralizado
  { "type": "flyin", "duration": 4, "cut": true, "transition": "white", // corte duro mascarado por mergulho no branco
    "target": "玉皇顶·山顶", "radius": 1200, "targetHeight": 1530,        // close-up em um POI nomeado; targetHeight = elevação do terreno (m) — OBRIGATÓRIO para close-ups em montanhas ou o pico sai do quadro
    "pitch": -30, "viewFrom": 165, "distanceFactor": 4.5 },
  { "type": "orbit", "duration": 5, "sweep": 20 }                      // orbita o alvo do corte
]

tomada de viagem — para elementos lineares longos (corredores, cadeias, road trips)

{ "type": "travel",          // duration OMITIDA → ritmo automático pelo comprimento do caminho (recomendado)
  "path": [[lng,lat],...],   // ou omita para seguir routes[0].path
  "offsetBearing": 32,       // direção da bússola de cada ponto do caminho → câmera (32 = câmera a NE)
  "offsetDist": 52000,       // deslocamento lateral do caminho, em metros
  "alt": 16000,              // altitude da câmera, em metros (BAIXA para relevo — veja abaixo)
  "targetHeight": 3400,      // elevação para a qual a câmera olha
  "groundSpeed": 15000,      // metros de solo por segundo; duração = comprimentoDoCaminho / groundSpeed
  "lookAhead": 0.05 }        // viés do olhar para frente ao longo do caminho (0..0.15 = sensação de viagem)
  // duration: <n>           // substituição opcional forçada; amostras automáticas ≈ duração/1.5 se omitida

Ritmo automático (NÃO codifique duration para travel): omita duration e a tomada se autotemporiza a partir do comprimento do caminho ÷ groundSpeed (padrão 15000 m/s, calibrado para ~1000 km tocar em ~65 s). Um trecho de 300 km e um loop de 1500 km serão lidos em uma velocidade confortável e consistente. Desacelere globalmente diminuindo groundSpeed (ex.: 12000); acelere com um valor maior. O número de keyframes também escala automaticamente. A câmera mantém um deslocamento lateral constante + altitude e desliza de uma extremidade à outra do caminho, sempre olhando para o ponto em movimento do caminho (interpolação linear = panorâmica de velocidade constante, sem aceleração). Esta é a ferramenta CERTA para um corredor de ~1000 km: uma tomada estática teria que ir ao espaço para ver tudo, mas uma tomada de viagem fica baixa e o revela ao longo do tempo.

Ritmo e relevo para tomadas de viagem (aprendido ajustando o Corredor Hexi):

  • Velocidade = comprimento do caminho ÷ duração. Um corredor de 1000 km em 16 s é um borrão; dê a ele ~30 s+ para que as cidades sejam legíveis. Velocidade no solo acima de ~30 km/s parece "muito rápida".
  • Relevo (sentir a queda de altura montanha vs. planície) precisa de três coisas juntas: uma câmera BAIXA (alt ~12–18 km, não 40 km — altitude alta achata tudo), um ângulo de visão RASO (offsetDist grande em relação a alt → pitch ~-12..-16°, para que os picos se ergam contra o horizonte em vez de serem vistos de cima) e, no nível da cena, "verticalExaggeration": 2.0–2.5 (veja abaixo). Olhar de cima + longe = plano; baixo + raso + exagerado = dramático.

verticalExaggeration (nível da cena) — faça o relevo do terreno se destacar

"verticalExaggeration": 2.3   // multiplica todas as alturas do terreno; 1 = real, 2–2.5 = o visual 三维地图看世界

A alavanca mais forte para transmitir elevação. Cadeias de montanhas se erguem como paredes; o relevo de cânions/ravinas se torna legível à distância. As âncoras de POIs/rótulos/rotas são ajustadas em altura para corresponder, então nada flutua ou afunda. Use-o para qualquer história de relevo de terreno (corredores, cadeias, cânions); deixe em 1 para tomadas de cidade (buildings3d). Defina o appear de cada POI aproximadamente quando a câmera passa por ele; POIs atrás da câmera naturalmente saem do quadro. Desenhe a rota com tStart/tEnd abrangendo a tomada para que a linha se desenrole enquanto você voa.

O compilador centraliza flyin/orbit na caixa delimitadora de todos os POIs/rotas/regiões (ou no target da tomada), calcula o alcance oblíquo a partir da dispersão (distanceFactor, padrão 3.8), deriva a direção do cálculo da orientação automaticamente e avisa se qualquer POI dentro do segmento se desvia >28° do eixo (tomadas de travel pulam essa verificação — elas passam pelos POIs por design). Duração total = soma das durações das tomadas. cut: true pula a câmera no limite da tomada sob uma transição de mergulho no branco/preto (transition, transitionDuration padrão 0.8s). cameraPath escrito à mão ainda funciona para controle total.

Dimensionamento de rótulos

"labelScale": 3   // multiplica o tamanho do rótulo + ponto do POI (cidade/montanha); padrão 1. Tomadas grandes de visão geral/viagem querem 2–3.

Escala a fonte do rótulo, contorno, ponto e — crucialmente — as lacunas de empilhamento anticolisão e alinhamento de borda, de modo que rótulos 3× nunca se sobreponham ou cortem fora da tela. O título tem seu próprio tamanho fixo (não afetado).

Comportamentos integrados (sem necessidade de configuração)

  • Anticolisão de rótulos: a cada quadro, os rótulos são projetados para o espaço da tela e desoverlapados — os rótulos dos POIs empilham para cima (lacunas escalam com o tamanho da fonte), o título grande se move para fora do caminho (deslocamentos adesivos, sem oscilação). Rótulos próximos a uma borda do quadro alinham-se automaticamente para dentro (origem esquerda/direita) para que rótulos grandes nunca cortem fora da tela. As âncoras de POIs/título são amostradas na altura do terreno para que a projeção seja precisa em montanhas. Quando um rótulo é empurrado para cima, uma linha líder branca o conecta ao seu ponto.
  • Aparecimento de POIs: os pontos aumentam de escala com um bounce suave; os rótulos aparecem/desvanecem em 0,6 s após seu tempo appear.
  • Desenho de regiões: as regiões animam como rotas (tStart/tEnd desenham o contorno; appear ainda funciona como tStart). "fill": true, "fillOpacity": 0.10 opcional esmaece uma tonalidade sobre o terreno após o contorno ser concluído.

Transições: mergulho vs. crossfade

  • "transition": "white" | "black" — sobreposição de mergulho na cor, passagem de renderização única (barato, padrão).
  • "transition": "fade" (+ transitionDuration opcional, padrão 0.8 s) — TRUE crossfade: a linha do tempo é dividida em segmentos renderizados separadamente (o segmento de saída mantém uma cauda congelada), então ffmpeg xfade os encadeia. Custa quadros extras ≈ fps × transitionDuration por corte.

Google Photorealistic 3D Tiles (cidades)

"buildings3d": true,            // ion asset 2275207; requer CESIUM_ION_TOKEN; o globo fica oculto
"buildings3dQuality": 16        // maximumScreenSpaceError; menor = mais nítido = mais lento

Para tomadas heroicas de cidade, vá BAIXO e PERTO: pitch -18..-25, minSlant 1200–2000 (substitui o piso de 3000 m de slant), targetHeight ≈ meio do edifício (150–250 m). Nota: os tiles do Google renderizam mais devagar por quadro e consomem cota do ion; --workers padrão 1 quando buildings3d está ativo.

Renderização paralela

node render.mjs cena.json dir-saida --workers=2 — N instâncias do Chrome renderizam blocos contíguos de quadros simultaneamente (retomada + autocorreção por worker). Padrão 2 (1 com buildings3d). 3–4 workers apenas em máquinas potentes.

Áudio opcional (narração TTS / BGM)

"audio": {                                       // omita completamente para um vídeo silencioso
  "tts": { "text": "泰山,五岳之首……",              // narração
           "voice": "zh-CN-YunxiNeural",          // voz edge-tts (se edge-tts estiver instalado)
           "sayVoice": "Tingting" },              // voz de fallback do `say` do macOS
  "bgm": { "file": "/caminho/para/musica.mp3", "volume": 0.22 }   // repetido e ajustado ao comprimento do vídeo
}

O mecanismo escolhe edge-tts se instalado, senão say do macOS (Tingting), senão pula com um aviso. A saída é gravada junto como <nome>-audio.mp4; o <nome>.mp4 silencioso é sempre mantido. Falhas de áudio nunca falham a renderização.

Sempre pré-visualize antes de uma renderização completa

node render.mjs <cena>.json <dir-saida> --preview

~1 min: renderiza 3 quadros (t=0.35/0.65/0.95) com TODOS os POIs/rotas forçados a aparecer. Verifique o posicionamento dos POIs, enquadramento, colisões de rótulos — depois execute a renderização completa. Isso detecta erros de coordenadas 6× mais rápido que uma renderização completa.

Esquema da cena JSON

{
  "name": "putuoshan",           // nome do arquivo de saída
  "width": 1280, "height": 720, "fps": 30, "duration": 10,  // segundos
  "cameraPath": [                 // keyframes, t em [0,1] da duração, interpolação cúbica suave entre eles
    { "t": 0.0, "lng": 122.387, "lat": 29.85, "alt": 60000, "heading": 0, "pitch": -90 },
    { "t": 0.4, "lng": 122.387, "lat": 29.95, "alt": 6000,  "heading": 10, "pitch": -35 },
    { "t": 1.0, "lng": 122.40,  "lat": 29.96, "alt": 4500,  "heading": 80, "pitch": -30 }
  ],
  "pois": [                       // ponto verde + rótulo branco, aparecem com fade em t=appear
    { "name": "普济禅寺", "lng": 122.3875, "lat": 29.9887, "appear": 0.45 }
  ],
  "title": { "text": "普陀山", "lng": 122.387, "lat": 30.001, "appear": 0.35 },
  "routes": [                     // polilinha brilhante, animação de desenho entre tStart..tEnd
    { "color": "#ffe94a", "width": 8, "tStart": 0.55, "tEnd": 0.95,
      "path": [[122.3963,29.9770],[122.3960,29.9805],[122.3875,29.9887]] }
  ],
  "regions": [                    // contorno poligonal brilhante opcional (destaque de região)
    { "color": "#ffe94a", "width": 6, "appear": 0.5, "polygon": [[lng,lat],...] }
  ]
}

Arquivos

  • render/flyover.html — Cena Cesium; expõe window.__setup(cfg) / window.__frame(t) para avanço determinístico.
  • render/render.mjs — Driver puppeteer-core: avança quadros, espera carregamento de tiles, captura de tela, executa ffmpeg.
  • scenes/putuoshan-demo.json — Exemplo funcional.
  • TODO.md — Backlog de iteração (multi-shot, desenho de regiões, TTS, predefinições 1080p…).

Dicas

  • Fly-ins de câmera funcionam melhor: tomada alta de cima para baixo → inclinação para ~-30..-40° de pitch a 3–8 km de altitude.
  • Verificação de composição (faça as contas!): em cada keyframe, o heading deve apontar da posição da câmera para o alvo — bearing ≈ atan2(Δlng·cos(lat), Δlat) em graus a partir do norte. Mantenha a câmera de um lado (ex.: sul do alvo, heading ≈ 0±25°) e arqueie suavemente; um heading que se desvia deixa o assunto (e sua animação de rota) fora do quadro. Sempre verifique visualmente os quadros de início/meio/fim antes de entregar.
  • Mantenha a mudança de heading por tomada < 120° ou o movimento parecerá confuso.
  • POI appear ligeiramente depois que a câmera se estabiliza; título após o fly-in.
  • Se os quadros mostrarem tiles de oceano em branco/preto, aumente a variável de ambiente TILE_TIMEOUT_MS ou diminua a velocidade da câmera.
  • Sem oscilação de "mapa recarregando": cada quadro espera até que os tiles sejam carregados E tenham permanecido carregados por SETTLE_MS (padrão 500 ms) antes da captura — para que você nunca capture um quadro ainda em streaming que ficará mais nítido no próximo. Para cenas pesadas (viagem em baixa altitude, verticalExaggeration alto, 4K) renderize com TILE_TIMEOUT_MS=60000 SETTLE_MS=500 para que os tiles tenham espaço para se estabilizar completamente. Aumentar SETTLE_MS (ex.: 800) troca tempo de renderização por quadros perfeitamente estáveis.
  • Ritmo para legibilidade: velocidade no solo = comprimento do caminho ÷ duração. Se cidades/terreno passarem como um borrão, dobre a duration. Um corredor de 1000 km quer ~60 s para realmente ler os lugares.
  • Atribuição: as imagens do Cesium ion exigem atribuição visível — o renderizador mantém o contêiner de crédito do Cesium visível; não o corte para vídeos publicados.

Habilidades Relacionadas