geo-flyover — Générateur d'animations de survol 3D
Rend une scène Cesium (CesiumJS) image par image dans Chrome headless, puis assemble un MP4 avec ffmpeg. Pas besoin d'After Effects ni d'Earth Studio.
Prérequis
- Node ≥ 18, Google Chrome installé, ffmpeg dans le PATH (tout est vérifié sur cette machine).
- Variable d'environnement
CESIUM_ION_TOKEN(compte gratuit sur https://ion.cesium.com → Access Tokens). Avec un token, vous obtenez l'imagerie Cesium World et le terrain mondial (montagnes 3D). Sans token, le moteur utilise l'imagerie satellite Esri World sur un ellipsoïde plat — regardable, mais sans relief 3D. - Première exécution :
cd render && npm install(installe uniquement puppeteer-core, très léger).
Flux de travail
- Créez un fichier JSON de scène (voir
scenes/putuoshan-demo.jsonet le schéma ci-dessous). Obtenez les coordonnées via une recherche web ou vos connaissances ; vérifiez approximativement que les coordonnées des POI correspondent à l'imagerie. - Rendu :
cd <dossier-compétence>/render && node render.mjs ../scenes/<scène>.json <chemin-sortie>- Écrit les
frames/f_0001.png...puis assemble automatiquement<chemin-sortie>/<nom>.mp4. - Vitesse de rendu ~1 à 3 ips ; une vidéo de 10 s / 300 images prend quelques minutes. Exécutez en arrière-plan et vérifiez.
- Écrit les
- Vérifiez : Lisez 2–3 images échantillons (début/milieu/fin). Vérifiez : le terrain est chargé (pas vide), les étiquettes lisibles, le tracé progresse.
- Fournissez le chemin du MP4 à l'utilisateur. Pour les vidéos finales, suggérez 1920×1080.
Recommandé : caméra basée sur les plans (calcul automatique, à utiliser de préférence à un cameraPath écrit à la main)
"preset": "1080p", // 720p | 1080p | 4k — les tailles de police/points/lignes s'adaptent automatiquement à la résolution
"shots": [
{ "type": "flyin", "duration": 5, "pitch": -33, "viewFrom": 178 }, // viewFrom : relèvement cible→caméra (178 = caméra presque au sud)
{ "type": "orbit", "duration": 6, "sweep": -14 }, // arc de la caméra de sweep°, la cible reste centrée
{ "type": "flyin", "duration": 4, "cut": true, "transition": "white", // coupure franche masquée par un volet blanc
"target": "玉皇顶·山顶", "radius": 1200, "targetHeight": 1530, // gros plan sur un POI nommé ; targetHeight = son altitude (m) — OBLIGATOIRE pour les gros plans de montagne, sinon le sommet sort du cadre
"pitch": -30, "viewFrom": 165, "distanceFactor": 4.5 },
{ "type": "orbit", "duration": 5, "sweep": 20 } // orbite autour de la cible de la coupure
]
Plan travel — pour les éléments linéaires longs (couloirs, chaînes, road trips)
{ "type": "travel", // duration OMISE → rythme automatique basé sur la longueur du chemin (recommandé)
"path": [[lng,lat],...], // ou omettre pour suivre routes[0].path
"offsetBearing": 32, // relèvement de chaque point du chemin vers la caméra (32 = caméra au NE)
"offsetDist": 52000, // décalage latéral par rapport au chemin, en mètres
"alt": 16000, // altitude de la caméra, en mètres (BASSE pour le relief — voir ci-dessous)
"targetHeight": 3400, // altitude à laquelle la caméra regarde
"groundSpeed": 15000, // mètres de sol par seconde ; durée = longueurChemin / groundSpeed
"lookAhead": 0.05 } // biais du regard vers l'avant le long du chemin (0..0.15 = sensation de voyage)
// duration: <n> // optionnel, écrase la valeur ; l'échantillonnage auto ≈ duration/1.5 si omis
Rythme automatique (ne PAS coder en dur duration pour les travel) : omettez duration et le plan se chronomètre automatiquement à partir de la longueur du chemin ÷ groundSpeed (défaut 15000 m/s, calibré pour qu'environ 1000 km dure ~65 s). Une portion de 300 km et une boucle de 1500 km se lisent alors à une vitesse confortable et constante. Ralentissez globalement en diminuant groundSpeed (ex. 12000) ; accélérez avec une valeur plus élevée. Le nombre d'images clés s'adapte automatiquement.
La caméra maintient un décalage latéral constant + une altitude et glisse d'une extrémité du chemin à l'autre, regardant toujours le point de chemin en mouvement (interpolation linéaire = panoramique à vitesse constante, pas d'accélération). C'est l'outil idéal pour un couloir d'environ 1000 km : un plan fixe devrait aller dans l'espace pour tout voir, mais un plan travel reste bas et le révèle au fil du temps.
Rythme et relief pour les plans travel (appris en réglant le couloir de Hexi) :
- Vitesse = longueur du chemin ÷ durée. Un couloir de 1000 km en 16 s est un flou ; donnez-lui ~30 s+ pour que les villes soient lisibles. Une vitesse au sol supérieure à ~30 km/s donne une impression de « trop rapide ».
- Relief (ressentir la différence de hauteur montagne vs plaine) nécessite trois choses ensemble : une caméra BASSE (
alt~12–18 km, pas 40 km — une haute altitude aplatit tout), un angle de visée PEU PROFOND (grandoffsetDistpar rapport àalt→ tangage ~-12..-16°, de sorte que les pics s'élèvent à l'horizon au lieu d'être vus de dessus), et une exagération verticale au niveau de la scène"verticalExaggeration": 2.0–2.5(voir ci-dessous). Vue de dessus + loin = plat ; bas + peu profond + exagéré = dramatique.
verticalExaggeration (niveau scène) — fait ressortir le relief du terrain
"verticalExaggeration": 2.3 // multiplie toutes les hauteurs du terrain ; 1 = réel, 2–2.5 = le look 三维地图看世界
Le levier le plus puissant pour transmettre l'altitude. Les chaînes de montagnes se dressent comme des murs ; le relief des canyons/gorges devient lisible à distance. Les ancres des POI/étiquettes/itinéraires sont ajustées en hauteur en conséquence, donc rien ne flotte ni ne coule. Utilisez-le pour toute histoire de relief du terrain (couloirs, chaînes, canyons) ; laissez-le à 1 pour les plans de ville (buildings3d). Définissez l'appear de chaque POI approximativement au moment où la caméra le dépasse ; les POI derrière la caméra sortent naturellement du cadre. Tracez l'itinéraire avec tStart/tEnd couvrant le plan pour que la ligne se déroule pendant le vol.
Le compilateur centre les flyin/orbite sur la boîte englobante de tous les POI/itinéraires/régions (ou la target du plan), calcule la distance oblique à partir de la dispersion (distanceFactor, défaut 3.8), dérive le cap automatiquement à partir du calcul du relèvement, et avertit si un POI intermédiaire dérive de >28° hors axe (les plans travel sautent cette vérification — ils passent devant les POI par conception). La durée totale = somme des durées des plans. cut: true fait sauter la caméra à la limite du plan sous une transition en volet blanc/noir (transition, transitionDuration par défaut 0.8 s). Un cameraPath écrit à la main fonctionne toujours pour un contrôle total.
Taille des étiquettes
"labelScale": 3 // multiplie la taille des étiquettes + points des POI (ville/montagne) ; défaut 1. Les grands plans d'ensemble/voyage veulent 2–3.
Met à l'échelle la police de l'étiquette, le contour, le point et — crucial — les espacements d'anti-collision et l'alignement des bords, de sorte que des étiquettes 3× ne se chevauchent jamais et ne sortent pas du cadre. Le titre a sa propre taille fixe (non affectée).
Comportements intégrés (aucune configuration nécessaire)
- Anti-collision des étiquettes : chaque image, les étiquettes sont projetées dans l'espace écran et désengorgées — les étiquettes des POI s'empilent vers le haut (les espacements s'adaptent à la taille de la police), le grand titre se déplace (décalages persistants, pas de tremblement). Les étiquettes proches d'un bord du cadre s'alignent automatiquement vers l'intérieur (origine gauche/droite) pour que les grandes étiquettes ne soient jamais coupées. Les ancres des POI/titre sont échantillonnées en hauteur sur le terrain pour une projection précise sur les montagnes. Lorsqu'une étiquette est poussée vers le haut, une ligne blanche de liaison la relie à son point.
- Apparition des POI : les points s'agrandissent avec un rebond en easing arrière ; les étiquettes apparaissent en fondu/traînée sur 0,6 s après leur temps
appear. - Dessin des régions : les régions s'animent comme les itinéraires (
tStart/tEndpour le contour ;appearfonctionne toujours comme tStart)."fill": true, "fillOpacity": 0.10optionnel pour une teinte drapée sur le terrain après la fin du contour.
Transitions : volet vs fondu enchaîné
"transition": "white" | "black"— volet vers une couleur, un seul passage de rendu (économique, par défaut)."transition": "fade"(+transitionDurationoptionnel, défaut 0.8 s) — VRAI fondu enchaîné : la timeline est divisée en segments rendus séparément (le segment sortant conserve une queue figée), puis ffmpegxfadeles enchaîne. Coûte des images supplémentaires ≈ fps × transitionDuration par coupure.
Tuiles Google Photorealistic 3D (villes)
"buildings3d": true, // ion asset 2275207 ; nécessite CESIUM_ION_TOKEN ; le globe est masqué
"buildings3dQuality": 16 // maximumScreenSpaceError ; plus bas = plus net = plus lent
Pour les plans héroïques de ville, allez BAS et PROCHE : pitch -18..-25, minSlant 1200–2000 (remplace le plancher oblique de 3000 m), targetHeight ≈ hauteur d'une tour (150–250 m). Note : les tuiles Google se rendent plus lentement par image et consomment du quota ion ; --workers par défaut à 1 quand buildings3d est activé.
Rendu parallèle
node render.mjs scene.json outdir --workers=2 — N instances Chrome rendent des blocs d'images contigus en concurrence (reprise + auto-réparation par worker). Défaut 2 (1 avec buildings3d). 3–4 workers uniquement sur des machines puissantes.
Audio optionnel (narration TTS / BGM)
"audio": { // omettre entièrement pour une vidéo silencieuse
"tts": { "text": "泰山,五岳之首……", // narration
"voice": "zh-CN-YunxiNeural", // voix edge-tts (si edge-tts installé)
"sayVoice": "Tingting" }, // voix de secours macOS `say`
"bgm": { "file": "/chemin/vers/musique.mp3", "volume": 0.22 } // bouclé et rogné à la durée de la vidéo
}
Le moteur utilise edge-tts s'il est installé, sinon macOS say (Tingting), sinon il ignore avec un avertissement. La sortie est écrite à côté sous <nom>-audio.mp4 ; la vidéo silencieuse <nom>.mp4 est toujours conservée. Les échecs audio ne font jamais échouer le rendu.
Toujours prévisualiser avant un rendu complet
node render.mjs <scene>.json <outdir> --preview
~1 min : rend 3 images (t=0.35/0.65/0.95) avec TOUS les POI/itinéraires forcés d'apparaître. Vérifiez le placement des POI, le cadrage, les collisions d'étiquettes — puis lancez le rendu complet. Cela détecte les erreurs de coordonnées 6× plus vite qu'un rendu complet.
Schéma JSON de la scène
{
"name": "putuoshan", // nom du fichier de sortie
"width": 1280, "height": 720, "fps": 30, "duration": 10, // secondes
"cameraPath": [ // images clés, t dans [0,1] de la durée, interpolation cubique
{ "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": [ // point vert + étiquette blanche, apparaissent avec fondu à t=appear
{ "name": "普济禅寺", "lng": 122.3875, "lat": 29.9887, "appear": 0.45 }
],
"title": { "text": "普陀山", "lng": 122.387, "lat": 30.001, "appear": 0.35 },
"routes": [ // polyligne lumineuse, animation de dessin 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": [ // contour de polygone lumineux optionnel (mise en évidence de région)
{ "color": "#ffe94a", "width": 6, "appear": 0.5, "polygon": [[lng,lat],...] }
]
}
Fichiers
render/flyover.html— scène Cesium ; exposewindow.__setup(cfg)/window.__frame(t)pour un pas à pas déterministe.render/render.mjs— pilote puppeteer-core : parcourt les images, attend le chargement des tuiles, capture d'écran, exécute ffmpeg.scenes/putuoshan-demo.json— exemple fonctionnel.TODO.md— backlog d'itération (multi-plans, dessin de région, TTS, préréglages 1080p…).
Conseils
- Les survols de caméra sont les meilleurs : plan haut en plongée → inclinaison à ~-30..-40° de tangage à 3–8 km d'altitude.
- Vérification de composition (faites le calcul !) : à chaque image clé, le heading doit pointer de la position de la caméra vers la cible — relèvement ≈ atan2(Δlng·cos(lat), Δlat) en degrés depuis le nord. Gardez la caméra d'un côté (par ex. au sud de la cible, heading ≈ 0±25°) et faites un arc doux ; un heading qui s'éloigne laisse le sujet (et votre animation d'itinéraire) hors cadre. Vérifiez toujours visuellement les images de début/milieu/fin avant de livrer.
- Limitez le changement de heading par plan à < 120° pour éviter un mouvement flou.
- POI
appearlégèrement après que la caméra se soit stabilisée ; le titre après le survol. - Si les images montrent des tuiles océaniques vides/noires, augmentez la variable d'environnement
TILE_TIMEOUT_MSou ralentissez la caméra. - Pas de scintillement « rafraîchissement de carte » : chaque image attend que les tuiles soient chargées ET restent chargées pendant
SETTLE_MS(par défaut 500 ms) avant la capture — vous n'attrapez donc jamais une image encore en streaming qui se résoudrait plus nette sur la suivante. Pour les scènes lourdes (voyage à basse altitude, forteverticalExaggeration, 4K), effectuez le rendu avecTILE_TIMEOUT_MS=60000 SETTLE_MS=500pour laisser le temps aux tuiles de se stabiliser complètement. AugmenterSETTLE_MS(ex. 800) échange du temps de rendu contre des images stables. - Rythme pour la lisibilité : vitesse au sol = longueur du chemin ÷ durée. Si les villes/le relief défilent en flou, doublez la
duration. Un couloir de 1000 km demande environ 60 s pour vraiment lire les lieux. - Attribution : l'imagerie Cesium ion nécessite une attribution visible — le moteur de rendu conserve le conteneur de crédit Cesium visible ; ne le recadrez pas pour les vidéos publiées.