Communitygithub.com

Vibetool/GeoReel

從 JSON 場景檔生成電影級 3D 地圖飛越影片 — 專為「三維地圖看世界」類型設計的 AI 智能體技能(真實地形、自動運鏡、自繪路線、旅遊運鏡、3D 圖磚、TTS)。

GeoReel 是什麼?

Vibetool/GeoReel 是一款 AI 智能體技能,能夠將場景 JSON 描述直接轉換為電影級的 3D 地圖飛越影片。它使用無頭 Chrome 瀏覽器逐一渲染 CesiumJS 3D 地球場景,再透過 ffmpeg 組裝成 MP4 影片,完全無需依賴 After Effects 或 Earth Studio 等專業軟體。此技能支援多種運鏡類型,包括自動計算的飛入、軌道環繞與沿路徑旅行運鏡,並能自動處理標籤防碰撞、POI 彈出動畫、路線繪製與區域高亮。此外,它還支援 Google 立體城市 3D 圖磚、邊緣 TTS 語音旁白、背景音樂以及 dip-to-white/black 或真正 crossfade 的場景轉場。開發者可透過 `--preview` 快速預覽關鍵幀,以便及早修正座標與構圖問題,大幅提升迭代效率。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add Vibetool/GeoReel

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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,體積很小)。

工作流程

  1. 撰寫場景 JSON(請參考 scenes/putuoshan-demo.json 及下方 schema)。透過網路搜尋或您的知識取得座標;在圖資上粗略驗證 POI 的經緯度正確性。
  2. 渲染: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 幀的影片需要幾分鐘。請在背景執行並輪詢進度。
  3. 驗證:讀取 2–3 張樣本幀(開始/中間/結尾)。檢查:地形已載入(非空白)、標籤清晰可讀、路線揭示進度正常。
  4. 將 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 版權標示;發布影片時請勿將其裁剪掉。

相關技能