geo-flyover — 3D 지도 비행 모션 생성기
Cesium(CesiumJS) 3D 지구 장면을 헤드리스 Chrome에서 프레임별로 렌더링한 다음, ffmpeg로 MP4를 조립합니다. After Effects / Earth Studio가 필요 없습니다.
요구사항
- Node ≥ 18, Google Chrome 설치, ffmpeg가 PATH에 있어야 함 (모두 이 머신에서 확인됨).
CESIUM_ION_TOKEN환경 변수 (https://ion.cesium.com에서 무료 계정 → Access Tokens). 토큰이 있으면 Cesium World Imagery + World Terrain(3D 산)을 사용할 수 있습니다. 토큰이 없으면 렌더러는 평평한 타원체에 Esri World Imagery 위성 타일을 사용합니다 — 시청은 가능하지만 3D 입체감은 없습니다.- 첫 실행:
cd render && npm install(puppeteer-core만 설치, 용량 작음).
워크플로우
- 장면 JSON 작성 (
scenes/putuoshan-demo.json및 아래 스키마 참조). 웹 검색이나 지식을 통해 좌표를 얻고, POI의 경도/위도가 대략 이미지와 일치하는지 확인합니다. - 렌더링:
cd <skill-dir>/render && node render.mjs ../scenes/<scene>.json /path/to/outdirframes/f_0001.png...파일을 쓴 다음 자동으로<outdir>/<name>.mp4를 조립합니다.- ~1–3 fps 렌더링 속도; 10초/300프레임 비디오는 몇 분 걸립니다. 백그라운드에서 실행하고 상태를 폴링하세요.
- 확인: 샘플 프레임 2–3장(시작/중간/끝)을 이미지로 읽습니다. 확인할 사항: 지형 로드(비어 있지 않음), 라벨 가독성, 경로 표시 진행.
- MP4 경로를 사용자에게 전달합니다. 최종 비디오는 1920x1080을 권장합니다.
권장: 샷 기반 카메라(자동 계산, 수동 cameraPath 대신 사용)
"preset": "1080p", // 720p | 1080p | 4k — 글꼴/포인트/선 두께가 해상도에 따라 자동 조정됨
"shots": [
{ "type": "flyin", "duration": 5, "pitch": -33, "viewFrom": 178 }, // viewFrom: 대상→카메라 방위각(178 = 카메라가 거의 정남쪽)
{ "type": "orbit", "duration": 6, "sweep": -14 }, // 카메라를 sweep°만큼 호 모양으로 이동, 대상은 중앙에 고정
{ "type": "flyin", "duration": 4, "cut": true, "transition": "white", // 하드 컷, 흰색으로 전환 마스크
"target": "옥황정·산정상", "radius": 1200, "targetHeight": 1530, // 특정 POI 클로즈업; targetHeight = 해당 지형 고도(m) — 산악 클로즈업에 필수, 그렇지 않으면 봉우리가 프레임에서 벗어남
"pitch": -30, "viewFrom": 165, "distanceFactor": 4.5 },
{ "type": "orbit", "duration": 5, "sweep": 20 } // 컷된 대상을 공전
]
travel 샷 — 긴 선형 특징(회랑, 산맥, 로드 트립)용
{ "type": "travel", // duration 생략 → 경로 길이에 따라 자동 템포 조절 (권장)
"path": [[lng,lat],...], // 또는 생략 시 routes[0].path를 따름
"offsetBearing": 32, // 각 경로 지점에서 카메라까지의 방위각 (32 = 카메라가 북동쪽)
"offsetDist": 52000, // 경로로부터의 측면 오프셋(미터)
"alt": 16000, // 카메라 고도(미터) (낮을수록 지형감 UP — 아래 참조)
"targetHeight": 3400, // 카메라가 바라보는 고도
"groundSpeed": 15000, // 초당 지상 이동 미터; duration = 경로 길이 / groundSpeed
"lookAhead": 0.05 } // 경로를 따라 앞을 바라보는 편향 (0..0.15 = 이동감)
// duration: <n> // 선택적 하드 오버라이드; 생략 시 자동 샘플링 ≈ duration/1.5
자동 템포 조절(travel 샷에는 duration을 하드코딩하지 마세요): duration을 생략하면 샷 시간이 경로 길이 ÷ groundSpeed(기본값 15000 m/s, 약 1000km를 65초에 재생하도록 보정됨)로 결정됩니다. 300km 구간과 1500km 루프 모두 편안하고 일관된 속도로 재생됩니다. groundSpeed를 낮추면(예: 12000) 전체 속도를 늦추고, 높이면 속도가 빨라집니다. 키프레임 개수도 자동으로 조정됩니다.
카메라는 일정한 측면 오프셋 + 고도를 유지하며 경로의 한쪽 끝에서 다른 쪽 끝으로 글라이드하며 항상 이동 중인 경로 지점을 바라봅니다(선형 보간 = 일정 속도 패닝, 이징 펌프 없음). 이것은 약 1000km 회랑에 적합한 도구입니다. 정적 샷은 모두 보려면 우주로 가야 하지만, travel 샷은 낮게 유지되며 시간이 지남에 따라 모습을 드러냅니다.
Travel 샷의 템포와 지형감(Hexi Corridor 튜닝 경험):
- 속도 = 경로 길이 ÷ duration. 1000km 회랑을 16초에 보여주면 흐릿합니다. 도시를 식별할 수 있도록 30초 이상을 주세요. 지상 속도가 약 30km/s를 넘으면 "너무 빠름"으로 읽힙니다.
- 지형감(산과 평야의 고도 차이를 느끼는 것) 은 세 가지가 함께 필요합니다: 낮은 카메라(
alt약 1218km, 40km가 아님 — 높은 고도는 모든 것을 평평하게 만듦), 얕은 시야각(-16°, 그래서 봉우리가 내려다보이는 대신 수평선 위로 솟아오름), 장면 레벨alt에 비해 큰offsetDist→ 피치 약 -12"verticalExaggeration": 2.0–2.5(아래 참조). 위에서 내려다보고 멀면 = 평평함; 낮고 얕고 과장하면 = 극적입니다.
verticalExaggeration (장면 레벨) — 지형 입체감 극대화
"verticalExaggeration": 2.3 // 모든 지형 높이 배율; 1 = 실제, 2–2.5 = "三维地图看世界" 스타일
고도를 전달하는 가장 강력한 단일 레버입니다. 산맥은 벽처럼 서고, 협곡/계곡의 입체감이 멀리서도 식별 가능해집니다. POI/라벨/경로 앵커는 이에 맞춰 높이가 조정되므로 떠 있거나 가라앉지 않습니다. 지형 입체감 스토리(회랑, 산맥, 협곡)에 사용하고, 도시(buildings3d) 샷에는 1로 두십시오. 각 POI의 appear를 카메라가 대략적으로 통과하는 시간으로 설정하세요. 카메라 뒤의 POI는 자연스럽게 프레임을 벗어납니다. 샷 전체에 tStart/tEnd가 걸쳐 있도록 경로를 그리면 비행하면서 선이 풀려나옵니다.
컴파일러는 flyin/orbit을 모든 POI/경로/지역의 경계 상자(또는 샷의 target) 중심에 맞추고, 퍼짐으로부터 경사 거리를 계산하며(distanceFactor, 기본값 3.8), 방위각 수학에서 자동으로 방향을 도출하고, 세그먼트 내 POI가 축에서 28° 이상 벗어나면 경고합니다(travel 샷은 이 검사를 건너뜁니다 — 설계상 POI를 지나쳐 패닝합니다). 총 지속 시간 = 샷 지속 시간의 합. cut: true는 흰색/검은색 전환(transition, transitionDuration 기본값 0.8초) 아래 샷 경계에서 카메라를 점프시킵니다. 수동 cameraPath는 전체 제어를 위해 여전히 작동합니다.
라벨 크기 조정
"labelScale": 3 // POI(도시/산) 라벨 + 점 크기 배율; 기본값 1. 큰 여행/개요 샷에는 2–3을 권장.
라벨 글꼴, 윤곽선, 점, 그리고 중요한 것은 충돌 방지 스태킹 간격과 가장자리 정렬을 확장하여 3배 라벨이 절대 겹치거나 화면 밖으로 잘리지 않도록 합니다. 제목은 고유한 고정 크기를 가집니다(영향 없음).
내장 동작 (설정 불필요)
- 라벨 충돌 방지: 매 프레임마다 라벨이 화면 공간에 투영되고 중복이 제거됩니다 — POI 라벨은 위로 쌓이고(간격은 글꼴 크기에 비례), 큰 제목은 비켜갑니다(고정 오프셋, 지터 없음). 프레임 가장자리 근처의 라벨은 자동으로 안쪽으로 정렬(왼쪽/오른쪽 기준)되어 큰 라벨이 화면 밖으로 잘리지 않습니다. POI/제목 앵커는 지형 높이를 샘플링하여 산에서도 정확하게 투영됩니다. 라벨이 위로 밀리면 흰색 리더 선이 점에 연결됩니다.
- POI 팝인: 점이 백 이즈 바운스로 확대되고, 라벨은
appear시간 이후 0.6초에 걸쳐 페이드인/트레일인됩니다. - 지역 드로우 온: 지역은 경로처럼 애니메이션됩니다(
tStart/tEnd윤곽선 드로우;appear는 여전히 tStart로 작동). 선택적"fill": true, "fillOpacity": 0.10은 윤곽선 완료 후 지형에 드리워진 색조를 페이드 인합니다.
전환: 딥 vs 크로스페이드
"transition": "white" | "black"— 색상 오버레이로 딥, 단일 렌더 패스(저렴함, 기본값)."transition": "fade"(+ 선택적transitionDuration, 기본값 0.8초) — 진정한 크로스페이드: 타임라인이 개별 렌더링된 세그먼트로 분할되고(나가는 세그먼트는 고정된 테일을 유지), ffmpegxfade가 체인으로 연결됩니다. 컷당 추가 프레임 ≈ fps × transitionDuration만큼 소요됩니다.
Google Photorealistic 3D Tiles (도시)
"buildings3d": true, // ion asset 2275207; CESIUM_ION_TOKEN 필요; 지구는 숨겨짐
"buildings3dQuality": 16 // maximumScreenSpaceError; 낮을수록 선명 = 느림
도시 히어로 샷의 경우 낮고 가깝게: pitch -18..-25, minSlant 1200–2000(3000m 경사 하한 재정의), targetHeight ≈ 중간 타워(150–250m). 참고: Google 타일은 프레임당 렌더링 속도가 느리고 ion 할당량을 소비합니다. --workers는 buildings3d가 켜져 있을 때 기본값 1입니다.
병렬 렌더링
node render.mjs scene.json outdir --workers=2 — N개의 Chrome 인스턴스가 동시에 연속적인 프레임 청크를 렌더링합니다(워커당 재개 + 자가 복구). 기본값 2(buildings3d 사용 시 1). 3–4 워커는 고성능 머신에서만 사용하세요.
선택적 오디오 (TTS 내레이션 / BGM)
"audio": { // 무음 비디오를 위해 완전히 생략
"tts": { "text": "태산, 오악의 으뜸……", // 내레이션
"voice": "zh-CN-YunxiNeural", // edge-tts 음성(edge-tts 설치 시)
"sayVoice": "Tingting" }, // macOS `say` 대체 음성
"bgm": { "file": "/path/to/music.mp3", "volume": 0.22 } // 반복 + 비디오 길이에 맞게 트림
}
엔진은 edge-tts가 설치되어 있으면 사용하고, 그렇지 않으면 macOS say(Tingting)를 사용하며, 둘 다 없으면 경고와 함께 건너뜁니다. 출력은 <name>-audio.mp4로 함께 기록됩니다. 무음 <name>.mp4는 항상 유지됩니다. 오디오 실패는 렌더링을 실패시키지 않습니다.
전체 렌더링 전에 항상 미리보기
node render.mjs <scene>.json <outdir> --preview
약 1분: 3프레임(t=0.35/0.65/0.95)을 모든 POI/경로를 강제로 표시하여 렌더링합니다. POI 배치, 구도, 라벨 충돌을 확인한 후 전체 렌더링을 실행하세요. 이렇게 하면 전체 렌더링보다 6배 빠르게 좌표 오류를 잡을 수 있습니다.
장면 JSON 스키마
{
"name": "putuoshan", // 출력 파일 이름
"width": 1280, "height": 720, "fps": 30, "duration": 10, // 초
"cameraPath": [ // 키프레임, t는 duration의 [0,1] 범위, 사이는 3차 이징
{ "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": [ // 녹색 점 + 흰색 라벨, t=appear에서 페이드 인
{ "name": "보제선사", "lng": 122.3875, "lat": 29.9887, "appear": 0.45 }
],
"title": { "text": "보타산", "lng": 122.387, "lat": 30.001, "appear": 0.35 },
"routes": [ // 빛나는 폴리라인, 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": [ // 선택적 빛나는 다각형 윤곽선 (지역 강조)
{ "color": "#ffe94a", "width": 6, "appear": 0.5, "polygon": [[lng,lat],...] }
]
}
파일
render/flyover.html— Cesium 장면; 결정적 단계 진행을 위해window.__setup(cfg)/window.__frame(t)를 노출합니다.render/render.mjs— puppeteer-core 드라이버: 프레임 단계 진행, 타일 로드 대기, 스크린샷, ffmpeg 실행.scenes/putuoshan-demo.json— 작동 예제.TODO.md— 반복 백로그 (멀티 샷, 지역 드로우 온, TTS, 1080p 프리셋…).
팁
- 카메라 플라이인은 가장 잘 읽힙니다: 위에서 내려다보는 높은 샷 → 3–8km 고도에서 약 -30~-40° 피치로 기울이기.
- 구성 확인 (계산해 보세요!): 각 키프레임에서 heading은 카메라 위치에서 대상을 향해야 합니다 — 방위각 ≈ atan2(Δlng·cos(lat), Δlat) (북쪽 기준 도). 카메라를 한쪽(예: 대상 남쪽, heading ≈ 0±25°)에 유지하고 부드럽게 호를 그리세요. heading이 멀어지면 대상(그리고 경로 애니메이션)이 프레임 밖으로 나갑니다. 전달하기 전에 항상 시작/중간/끝 프레임을 시각적으로 확인하세요.
- 샷당 heading 변화를 120° 미만으로 유지하세요. 그렇지 않으면 움직임이 어지러워 보입니다.
- POI
appear는 카메라가 안정된 후 약간 늦게, 제목은 플라이인 후에 설정하세요. - 프레임이 텅 빈/검은 바다 타일을 표시하면
TILE_TIMEOUT_MS환경 변수를 늘리거나 카메라 속도를 늦추세요. - "지도 새로 고침" 깜빡임 없음: 모든 프레임은 타일이 로드되고
SETTLE_MS(기본값 500ms) 동안 로드된 상태를 유지할 때까지 기다린 후 캡처합니다 — 따라서 다음 프레임에서 더 선명해지는 스트리밍 중인 프레임을 절대 잡지 않습니다. 무거운 장면(저고도 여행, 높은verticalExaggeration, 4K)의 경우TILE_TIMEOUT_MS=60000 SETTLE_MS=500으로 렌더링하여 타일이 완전히 안정될 시간을 확보하세요.SETTLE_MS를 높이면(예: 800) 렌더링 시간과 안정적인 프레임이 트레이드오프됩니다. - 가독성을 위한 템포: 지상 속도 = 경로 길이 ÷ duration. 도시/지형이 흐릿하게 지나가면
duration을 두 배로 늘리세요. 1000km 회랑은 실제로 장소를 읽을 수 있도록 약 60초가 필요합니다. - 저작자 표시: Cesium ion 이미지에는 눈에 띄는 저작자 표시가 필요합니다 — 렌더러는 Cesium 크레딧 컨테이너를 계속 표시합니다. 게시된 비디오에서 잘라내지 마세요.