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
- Crie uma cena JSON (veja
scenes/putuoshan-demo.jsone o esquema abaixo). Obtenha coordenadas via pesquisa na web ou seu conhecimento; verifique aproximadamente a lng/lat dos POIs na imagem. - 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>.mp4automaticamente. - Velocidade de renderização ~1–3 fps; um vídeo de 10 s / 300 quadros leva alguns minutos. Execute em segundo plano e consulte.
- Gera
- 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.
- 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 (offsetDistgrande em relação aalt→ 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/tEnddesenham o contorno;appearainda funciona como tStart)."fill": true, "fillOpacity": 0.10opcional 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"(+transitionDurationopcional, 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 ffmpegxfadeos 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õewindow.__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
appearligeiramente 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_MSou 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,verticalExaggerationalto, 4K) renderize comTILE_TIMEOUT_MS=60000 SETTLE_MS=500para que os tiles tenham espaço para se estabilizar completamente. AumentarSETTLE_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.