geo-flyover — 三維地圖飛行動效產生器
在無頭 Chrome 中逐幀渲染 Cesium (CesiumJS) 3D 地球場景,然後使用 ffmpeg 組裝成 MP4。無需 After Effects / Earth Studio。
需求
- Node ≥ 18、已安裝 Google Chrome、ffmpeg 在 PATH 中(此機器上皆已驗證)。
CESIUM_ION_TOKEN環境變數(在 https://ion.cesium.com → Access Tokens 免費註冊帳號取得)。有了 token 即可獲得 Cesium World Imagery + World Terrain(3D 山脈)。若無 token,渲染器會降級使用 Esri World Imagery 衛星圖磚,但地形為平坦橢球體——仍可觀看,但無 3D 立體感。- 初次執行:
cd render && npm install(僅安裝 puppeteer-core,體積很小)。
工作流程
- 撰寫場景 JSON(請參考
scenes/putuoshan-demo.json及下方 schema)。透過網路搜尋或您的知識取得座標;在圖資上粗略驗證 POI 的經緯度正確性。 - 渲染:
cd <skill-dir>/render && node render.mjs ../scenes/<scene>.json /path/to/outdir- 寫入
frames/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 = 該點的地形高程 (公尺) — 山區特寫必填,否則山峰會超出畫面
"pitch": -30, "viewFrom": 165, "distanceFactor": 4.5 },
{ "type": "orbit", "duration": 5, "sweep": 20 } // 繞著切換後的目標旋轉
]
旅行運鏡 — 適用於長條形地貌(走廊、山脈、公路旅行)
{ "type": "travel", // 不填 duration → 自動根據路徑長度決定時長(建議使用)
"path": [[lng,lat],...], // 或省略以 routes[0].path 為準
"offsetBearing": 32, // 從每個路徑點指向攝影機的方位角(32 = 攝影機在東北方)
"offsetDist": 52000, // 與路徑的橫向偏移距離,單位公尺
"alt": 16000, // 攝影機海拔高度,單位公尺(低才能展現地形起伏——詳見下方)
"targetHeight": 3400, // 攝影機注視點的海拔高度
"groundSpeed": 15000, // 每秒覆蓋的地面距離,單位公尺;duration = 路徑長度 / groundSpeed
"lookAhead": 0.05 } // 讓注視點沿路徑稍微超前(0..0.15 = 有旅行感)
// duration: <n> // 可選的強制覆蓋值;若省略,自動取樣約 duration/1.5
自動配速(旅行運鏡請勿手寫 duration): 省略 duration,運鏡時長會根據路徑長度 ÷ groundSpeed(預設 15000 m/s,約 1000 km 需 65 秒)自動計算。如此一來,300 km 和 1500 km 的路線都能以舒適且一致的速度播放。若要整體放慢,可降低 groundSpeed(例如 12000);若要加快則使用較大數值。關鍵幀數量也會自動縮放。
攝影機會保持固定的橫向偏移和高度,從路徑一端平滑移動到另一端,始終注視移動中的路徑點(線性插值 = 等速平移,無緩動泵效)。這是處理約 1000 km 走廊的最佳工具:靜態運鏡需要飛到太空中才能一覽全貌,但旅行運鏡能保持低空並隨時間逐步展現。
旅行運鏡的配速與地形起伏感(調整河西走廊學到的技巧):
- 速度 = 路徑長度 ÷ 時長。一條 1000 km 的走廊若在 16 秒內播完會模糊不清;請給它約 30 秒以上,讓城市名稱可讀。地面速度超過約 30 km/s 就會感覺「太快」。
- 地形起伏感(感受到山與平原的高度落差) 需要三個條件同時具備:低角度攝影機(
alt約 12–18 km,不要 40 km — 高海拔會抹平一切)、淺的俯視角(offsetDist相對於alt要大 → pitch 約 -12..-16°,這樣山脊會在地平線上聳起,而非被俯視)、以及場景層級的"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),並自動從方位角計算推導出 heading,若區段內任何 POI 偏離軸線超過 28° 會發出警告(旅行運鏡跳過此檢查——它們設計上就是會經過 POI)。總時長 = 所有運鏡時長總和。cut: true 會在運鏡邊界處以 dip-to-white/black 轉場(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 秒)— 真正的交叉溶接:時間軸會分割成獨立渲染的區段(前一個區段會保留一個凍結的尾部),然後由 ffmpeg 的xfade濾鏡將它們串接起來。每次切換會增加約 fps × transitionDuration 的額外幀數。
Google 立體 3D 圖磚(城市)
"buildings3d": true, // ion 資產 2275207;需要 CESIUM_ION_TOKEN;地球會被隱藏
"buildings3dQuality": 16 // maximumScreenSpaceError;數值越低越清晰,但渲染越慢
都市特寫運鏡時應飛得低且近:pitch -18..-25、minSlant 1200–2000(覆蓋預設的 3000 公尺傾斜距離下限)、targetHeight 約為中高層建築(150–250 公尺)。注意:Google 圖磚每幀渲染較慢且會消耗 ion 配額;--workers 在啟用 buildings3d 時預設為 1。
平行渲染
node render.mjs scene.json outdir --workers=2 — N 個 Chrome 實例同時渲染連續的幀區塊(每個 worker 可續傳並自我修復)。預設為 2(啟用 buildings3d 時為 1)。僅在效能強大的機器上建議使用 3–4 個 worker。
可選音訊(TTS 旁白 / 背景音樂)
"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 schema
{
"name": "putuoshan", // 輸出檔案名稱
"width": 1280, "height": 720, "fps": 30, "duration": 10, // 秒數
"cameraPath": [ // 關鍵幀,t 在 duration 的 [0,1] 範圍內,中間以三次緩動插值
{ "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 預設……)。
小技巧
- 飛入運鏡的最佳效果:高處俯視 → 傾斜至約 -30..-40° 俯仰角,高度 3–8 km。
- 構圖檢查(動手算!):在每個關鍵幀,heading 必須從攝影機位置指向目標——方位角 ≈ atan2(Δlng·cos(lat), Δlat) 以度為單位,從北方算起。將攝影機保持在同一側(例如目標南方,heading 約 0±25°)並柔和緩動;若 heading 偏離目標,則主體(及路線動畫)會移出畫面。務必在交付前視覺檢查開始/中間/結尾幀。
- 每個運鏡的 heading 變化請保持在 120° 以內,否則動態看起來會像在游泳。
- POI 的
appear時間應略晚於攝影機穩定後;標題則在飛入之後。 - 若畫面顯示空白/黑色海洋圖磚,請增加
TILE_TIMEOUT_MS環境變數或放慢攝影機速度。 - 無「地圖重新整理」閃爍:每一幀都會等到圖磚已載入且保持載入狀態達
SETTLE_MS(預設 500 毫秒)後才捕捉——因此絕不會捕捉到仍在串流中、下一幀會更清晰的畫面。對於負載較重的場景(低空旅行、高verticalExaggeration、4K),請使用TILE_TIMEOUT_MS=60000 SETTLE_MS=500來渲染,讓圖磚有足夠時間完全穩定。提高SETTLE_MS(例如 800)會以渲染時間換取更穩定的幀。 - 以可讀性為配速依據:地面速度 = 路徑長度 ÷ 時長。若城市/地形模糊掠過,請將
duration加倍。一條 1000 km 的走廊需要約 60 秒才能讓觀眾真正讀取到地名。 - 歸屬說明:Cesium ion 圖資需要顯示歸屬——渲染器會保留 Cesium 版權標示;發布影片時請勿將其裁剪掉。