Communitygithub.com

Vibetool/GeoReel

Genera videos cinematográficos de sobrevuelo 3D de mapas a partir de escenas JSON — una skill para el género de mapas 3D (terreno real, cámara automática, rutas autodibujadas, tomas de viaje, tiles 3D, TTS).

¿Qué es GeoReel?

GeoReel es una skill que convierte escenas JSON en vídeos MP4 de sobrevuelo 3D sobre el globo terráqueo mediante CesiumJS, Puppeteer y ffmpeg, sin necesidad de After Effects ni Earth Studio. Soporta terrenos reales con relieve 3D, rutas animadas que se dibujan a sí mismas, etiquetas inteligentes con anticolisión, tomas predefinidas (fly-in, órbita, viaje) y exageración vertical para resaltar montañas. Funciona en Node ≥18 con Chrome y ffmpeg instalados, y requiere un token de Cesium ion para el terreno 3D completo. La skill es ideal para creadores de contenido del género '三维地图看世界' (mapas 3D chinos), generando vídeos de alta calidad con narración TTS opcional y música de fondo. Los usuarios deben proporcionar coordenadas de POIs y rutas, y la skill se encarga del renderizado fotograma a fotograma en Chrome headless, ensamblando finalmente el vídeo con ffmpeg.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add Vibetool/GeoReel

Preguntar en tu IA favorita

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

Documentación

geo-flyover — Generador de animaciones de sobrevuelo 3D

Renderiza una escena del globo terráqueo 3D de Cesium (CesiumJS) fotograma a fotograma en Chrome headless, luego ensambla un MP4 con ffmpeg. No necesita After Effects / Earth Studio.

Requisitos

  • Node ≥ 18, Google Chrome instalado, ffmpeg en PATH (todo verificado en esta máquina).
  • Variable de entorno CESIUM_ION_TOKEN (cuenta gratuita en https://ion.cesium.com → Access Tokens). Con un token obtienes Cesium World Imagery + World Terrain (montañas 3D). Sin él, el renderizador usa las teselas satelitales de Esri World Imagery sobre un elipsoide PLANO: visible, pero sin relieve 3D.
  • Primera ejecución: cd render && npm install (instala solo puppeteer-core, muy pequeño).

Flujo de trabajo

  1. Crea un archivo JSON de escena (consulta scenes/putuoshan-demo.json y el esquema más abajo). Obtén coordenadas mediante búsqueda web o tu conocimiento; verifica que la longitud/latitud de los POI estén aproximadamente sobre la imagen.
  2. Renderiza: cd <directorio-skill>/render && node render.mjs ../scenes/<escena>.json <directorio-salida>
    • Escribe frames/f_0001.png... y luego ensambla automáticamente <directorio-salida>/<nombre>.mp4.
    • Velocidad de renderizado ~1-3 fps; un video de 10 s / 300 fotogramas tarda unos minutos. Ejecuta en segundo plano y consulta.
  3. Verifica: Lee 2-3 fotogramas de muestra como imágenes (inicio/medio/fin). Comprueba: terreno cargado (no en blanco), etiquetas legibles, progreso de la ruta.
  4. Entrega la ruta del MP4 al usuario. Para videos finales, sugiere 1920x1080.

Recomendado: cámara basada en tomas (calculada automáticamente, usa esto en lugar de escribir cameraPath a mano)

"preset": "1080p",   // 720p | 1080p | 4k — los tamaños de fuentes/puntos/líneas se escalan automáticamente con la resolución
"shots": [
  { "type": "flyin", "duration": 5, "pitch": -33, "viewFrom": 178 },  // viewFrom: rumbo brújula del objetivo→cámara (178 = cámara casi al sur)
  { "type": "orbit", "duration": 6, "sweep": -14 },                    // arquea la cámara en sweep°, el objetivo permanece centrado
  { "type": "flyin", "duration": 4, "cut": true, "transition": "white", // corte duro enmascarado con fundido a blanco
    "target": "玉皇顶·山顶", "radius": 1200, "targetHeight": 1530,        // primer plano en un POI nombrado; targetHeight = su elevación del terreno (m) — OBLIGATORIO para primeros planos de montañas o el pico sale del encuadre
    "pitch": -30, "viewFrom": 165, "distanceFactor": 4.5 },
  { "type": "orbit", "duration": 5, "sweep": 20 }                      // orbita el objetivo del corte
]

toma de viaje — para elementos lineales largos (corredores, cadenas montañosas, viajes por carretera)

{ "type": "travel",          // duration OMITIDO → ritmo automático según la longitud de la ruta (recomendado)
  "path": [[lng,lat],...],   // u omitir para seguir rutas[0].path
  "offsetBearing": 32,       // rumbo brújula desde cada punto de la ruta → cámara (32 = cámara al NE)
  "offsetDist": 52000,       // desplazamiento lateral desde la ruta, en metros
  "alt": 16000,              // altitud de la cámara, en metros (BAJA para relieve — ver más abajo)
  "targetHeight": 3400,      // elevación que mira la cámara
  "groundSpeed": 15000,      // metros de suelo por segundo; duración = longitudRuta / groundSpeed
  "lookAhead": 0.05 }        // sesga la mirada hacia adelante a lo largo de la ruta (0..0.15 = sensación de viaje)
  // duration: <n>           // sobrescritura opcional; el muestreo automático ≈ duración/1.5 si se omite

Ritmo automático (NO codifiques duration para viaje): omite duration y la toma se temporiza a partir de la longitud de la ruta ÷ groundSpeed (predeterminado 15000 m/s, calibrado para que ~1000 km se reproduzcan en ~65 s). Un tramo de 300 km y un bucle de 1500 km se leen ambos a una velocidad cómoda y constante. Reduce la velocidad globalmente bajando groundSpeed (ej. 12000); aceléralo con un valor más alto. El número de fotogramas clave también se escala automáticamente. La cámara mantiene un desplazamiento lateral constante + altitud y se desliza de un extremo al otro de la ruta, mirando siempre al punto de ruta en movimiento (interpolación lineal = paneo a velocidad constante, sin bombeo de easing). Esta es la herramienta ADECUADA para un corredor de ~1000 km: una toma estática debe ir al espacio para verlo todo, pero una toma de viaje se mantiene baja y lo revela con el tiempo.

Ritmo y relieve para tomas de viaje (aprendido al ajustar el Corredor de Hexi):

  • Velocidad = longitud de la ruta ÷ duración. Un corredor de 1000 km en 16 s es un borrón; dale ~30 s+ para que las ciudades sean legibles. La velocidad del suelo sobre ~30 km/s se lee como "demasiado rápido".
  • Relieve (sentir la caída de altura montaña vs. llanura) necesita tres cosas juntas: una cámara BAJA (alt ~12-18 km, no 40 km — la altitud alta aplana todo), un ángulo de mirada Poco profundo (gran offsetDist relativo a alt → inclinación ~-12..-16°, para que los picos se eleven contra el horizonte en lugar de ser mirados desde arriba), y una "verticalExaggeration" a nivel de escena de 2.0-2.5 (ver más abajo). Vista superior + lejos = plano; bajo + poco profundo + exagerado = dramático.

verticalExaggeration (a nivel de escena) — hace que el relieve del terreno resalte

"verticalExaggeration": 2.3   // multiplica todas las alturas del terreno; 1 = real, 2-2.5 = el aspecto de mapas 3D

La palanca más importante para transmitir elevación. Las cadenas montañosas se yerguen como muros; el relieve de cañones/barrancos se vuelve legible desde la distancia. Los anclajes de POI/etiquetas/rutas se ajustan en altura para coincidir, por lo que nada flota ni se hunde. Úsalo para cualquier historia de relieve de terreno (corredores, cadenas montañosas, cañones); déjalo en 1 para tomas de ciudad (buildings3d). Configura el appear de cada POI aproximadamente cuando la cámara lo pasa; los POI detrás de la cámara salen del encuadre naturalmente. Dibuja la ruta con tStart/tEnd abarcando la toma para que la línea se desenrolle mientras vuelas.

El compilador centra el flyin/órbita en el cuadro delimitador de todos los POI/rutas/regiones (o el target de la toma), calcula el alcance oblicuo a partir de la dispersión (distanceFactor, predeterminado 3.8), deriva el rumbo a partir de cálculos de orientación automáticamente, y advierte si algún POI dentro del segmento se desvía >28° del eje (las tomas de viaje omiten esta comprobación — pasan junto a los POI por diseño). La duración total = suma de las duraciones de las tomas. cut: true salta la cámara en el límite de la toma bajo una transición de fundido a blanco/negro (transition, transitionDuration predeterminado 0.8 s). La cameraPath escrita a mano sigue funcionando para control total.

Escalado de etiquetas

"labelScale": 3   // multiplica el tamaño de la etiqueta y el punto del POI (ciudad/montaña); predeterminado 1. Las tomas grandes de viaje/visión general quieren 2-3.

Escala la fuente de la etiqueta, el contorno, el punto y, crucialmente, los espacios de apilamiento anticolisión y la alineación de bordes, por lo que las etiquetas 3× nunca se superponen ni se recortan fuera de la pantalla. El título tiene su propio tamaño fijo (no afectado).

Comportamientos incorporados (sin configuración necesaria)

  • Anticolisión de etiquetas: cada fotograma, las etiquetas se proyectan al espacio de la pantalla y se eliminan superposiciones — las etiquetas POI se apilan hacia arriba (los espacios se escalan con el tamaño de la fuente), el título grande se aparta (desplazamientos persistentes, sin vibración). Las etiquetas cerca del borde del fotograma se alinean hacia adentro automáticamente (origen izquierdo/derecho) para que las etiquetas grandes nunca se recorten fuera de la pantalla. Los anclajes de POI/título se muestrean con la altura del terreno para que la proyección sea precisa en las montañas. Cuando una etiqueta se empuja hacia arriba, una línea guía blanca la conecta con su punto.
  • Aparición de POI: los puntos aparecen con un rebote (back-ease); las etiquetas se desvanecen/aparecen en 0.6 s después de su tiempo appear.
  • Dibujo de regiones: las regiones se animan como rutas (tStart/tEnd dibujan el contorno; appear aún funciona como tStart). "fill": true, "fillOpacity": 0.10 opcional desvanece un tinte cubierto de terreno después de que se completa el contorno.

Transiciones: fundido vs. encadenado

  • "transition": "white" | "black" — superposición de fundido a color, una sola pasada de renderizado (económico, predeterminado).
  • "transition": "fade" (+ transitionDuration opcional, predeterminado 0.8 s) — VERDADERO encadenado: la línea de tiempo se divide en segmentos renderizados por separado (el segmento saliente mantiene una cola congelada), luego ffmpeg xfade los encadena. Cuesta fotogramas extra ≈ fps × transitionDuration por corte.

Teselas 3D fotorrealistas de Google (ciudades)

"buildings3d": true,            // activo ion 2275207; requiere CESIUM_ION_TOKEN; el globo está oculto
"buildings3dQuality": 16        // maximumScreenSpaceError; menor = más nítido = más lento

Para tomas estrella de ciudad, ve BAJO y CERCA: pitch -18..-25, minSlant 1200-2000 (anula el piso de alcance oblicuo de 3000 m), targetHeight ≈ media torre (150-250 m). Nota: las teselas de Google se renderizan más lento por fotograma y consumen cuota de ion; --workers predeterminado es 1 cuando buildings3d está activado.

Renderizado paralelo

node render.mjs escena.json directorio-salida --workers=2 — N instancias de Chrome renderizan fragmentos de fotogramas contiguos de forma concurrente (reanudación + autocuración por worker). Predeterminado 2 (1 con buildings3d). 3-4 workers solo en máquinas potentes.

Audio opcional (narración TTS / música de fondo)

"audio": {                                       // omitir completamente para un video silencioso
  "tts": { "text": "泰山,五岳之首……",              // narración
           "voice": "zh-CN-YunxiNeural",          // voz de edge-tts (si edge-tts está instalado)
           "sayVoice": "Tingting" },              // voz de respaldo `say` de macOS
  "bgm": { "file": "/path/to/music.mp3", "volume": 0.22 }   // en bucle y recortado a la duración del video
}

El motor elige edge-tts si está instalado, sino say de macOS (Tingting), sino omite con una advertencia. La salida se escribe junto a <nombre>-audio.mp4; el <nombre>.mp4 silencioso siempre se conserva. Los fallos de audio nunca fallan el renderizado.

Siempre previsualiza antes de un renderizado completo

node render.mjs <escena>.json <directorio-salida> --preview

~1 min: renderiza 3 fotogramas (t=0.35/0.65/0.95) con TODOS los POI/rutas forzados a mostrarse. Comprueba la colocación de POI, el encuadre, las colisiones de etiquetas — luego ejecuta el renderizado completo. Esto detecta errores de coordenadas 6× más rápido que un renderizado completo.

Esquema JSON de escena

{
  "name": "putuoshan",           // nombre del archivo de salida
  "width": 1280, "height": 720, "fps": 30, "duration": 10,  // segundos
  "cameraPath": [                 // fotogramas clave, t en [0,1] de la duración, interpolación cúbica suavizada entre ellos
    { "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": [                       // punto verde + etiqueta blanca, aparecen con fundido en t=appear
    { "name": "普济禅寺", "lng": 122.3875, "lat": 29.9887, "appear": 0.45 }
  ],
  "title": { "text": "普陀山", "lng": 122.387, "lat": 30.001, "appear": 0.35 },
  "routes": [                     // polilínea brillante, animación de dibujo 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 brillante opcional (resaltado de región)
    { "color": "#ffe94a", "width": 6, "appear": 0.5, "polygon": [[lng,lat],...] }
  ]
}

Archivos

  • render/flyover.html — escena de Cesium; expone window.__setup(cfg) / window.__frame(t) para avance determinista.
  • render/render.mjs — controlador de puppeteer-core: avanza fotogramas, espera la carga de teselas, captura pantallas, ejecuta ffmpeg.
  • scenes/putuoshan-demo.json — ejemplo funcional.
  • TODO.md — backlog de iteraciones (múltiples tomas, dibujo de regiones, TTS, preajustes 1080p…).

Consejos

  • Las entradas de cámara se ven mejor: toma alta cenital → inclinación a ~-30..-40° a 3-8 km de altitud.
  • Comprobación de composición (¡haz los cálculos!): en cada fotograma clave, el rumbo debe apuntar desde la posición de la cámara hacia el objetivo — rumbo ≈ atan2(Δlng·cos(lat), Δlat) en grados desde el norte. Mantén la cámara en un lado (ej. al sur del objetivo, rumbo ≈ 0±25°) y arquea suavemente; un rumbo que se desvía deja al sujeto (y tu animación de ruta) fuera del encuadre. Siempre verifica visualmente los fotogramas de inicio/medio/fin antes de entregar.
  • Mantén el cambio de rumbo por toma < 120° o el movimiento se ve ondulante.
  • appear del POI ligeramente después de que la cámara se estabilice; el título después de la entrada.
  • Si los fotogramas muestran teselas oceánicas en blanco/negro, aumenta la variable de entorno TILE_TIMEOUT_MS o ralentiza la cámara.
  • Sin parpadeo de "mapa refrescándose": cada fotograma espera hasta que las teselas se hayan cargado Y hayan permanecido cargadas durante SETTLE_MS (predeterminado 500 ms) antes de la captura — por lo que nunca capturas un fotograma aún en transmisión que se resuelve más nítido en el siguiente. Para escenas pesadas (viaje a baja altitud, verticalExaggeration alta, 4K) renderiza con TILE_TIMEOUT_MS=60000 SETTLE_MS=500 para que las teselas tengan espacio para asentarse completamente. Aumentar SETTLE_MS (ej. 800) intercambia tiempo de renderizado por fotogramas estables.
  • Ritmo para legibilidad: velocidad del suelo = longitud de la ruta ÷ duración. Si las ciudades/terreno pasan borrosos, duplica la duración. Un corredor de 1000 km quiere ~60 s para leer realmente los lugares.
  • Atribución: las imágenes de Cesium ion requieren atribución visible — el renderizador mantiene visible el contenedor de créditos de Cesium; no lo recortes para videos publicados.

Skills relacionados