Communitygithub.com

Vibetool/GeoReel

映画のような3Dマップフライオーバー動画をJSONシーンから生成します——「三次元地図で世界を見る」ジャンルに対応したエージェントスキル(実地形、自動カメラ、自己描画ルート、トラベルショット、3Dタイル、TTS対応)。

GeoReel とは?

このスキルは、CesiumJS 3D地球儀シーンをヘッドレスChromeでフレームごとにレンダリングし、ffmpegでMP4に合成するエージェントスキルです。After EffectsやEarth Studioは不要で、Node.js 18以上、Google Chrome、ffmpegがインストールされた環境で動作します。CESIUM_ION_TOKENを設定すれば、Cesium World ImageryとWorld Terrainによる3D地形(山岳)が利用可能。トークンがない場合も、Esri World Imageryの衛星タイルで平坦な楕円体上にレンダリングできます。ユーザーはJSONシーンを記述し、カメラのフライイン、オービット、トラベルショットを組み合わせて、POIのポップイン、ルートの描画アニメーション、ラベルの衝突回避、垂直 exaggeration による地形表現などを自動で処理。TTSナレーションやBGMの追加、Google Photorealistic 3D Tiles(建物)にも対応。プレビューモードで簡単に確認でき、並列レンダリングもサポートしています。このスキルは、視聴者を地図上で旅させるようなドキュメンタリータッチの映像制作に最適です。

対応~Claude Code~Codex CLI~Cursor
npx skills add Vibetool/GeoReel

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

geo-flyover — 三次元地図フライオーバー動画生成器

Cesium(CesiumJS)3D地球儀シーンをヘッドレスChromeでフレームごとにレンダリングし、ffmpegでMP4に合成します。After Effects / Earth Studioは不要です。

要件

  • Node ≥ 18、Google Chromeインストール済み、ffmpegがPATHに存在すること(すべてこのマシンで確認済み)。
  • CESIUM_ION_TOKEN環境変数(無料アカウント作成 https://ion.cesium.com → アクセストークン)。トークンがあればCesium World Imagery + World Terrain(三次元山岳)が利用可能。トークンがない場合、Esri World Imagery衛星タイルを平坦な楕円体上にレンダリングします(視聴可能ですが、3D地形はありません)。
  • 初回実行:cd render && npm install(puppeteer-coreのみインストール、軽量)。

ワークフロー

  1. シーンJSONを作成(scenes/putuoshan-demo.jsonと以下のスキーマを参照)。座標はWeb検索や自身の知識で取得し、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 = その地形標高(m) — 山のクローズアップでは必須、さもないとピークがフレームから外れます
    "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 = pathLength / groundSpeed
  "lookAhead": 0.05 }        // 注視点をパス前方にバイアス(0..0.15 = トラベル感)
  // duration: <n>           // オプションでハードオーバーライド;省略時は自動的に duration ≈ パス長/15000 でサンプリング

自動ペーシング(トラベルではdurationをハードコードしないこと): durationを省略すると、ショットはパス長 ÷ groundSpeed(デフォルト15000 m/s、約1000kmを約65秒で再生するよう調整済み)で自動的に時間設定されます。300kmの区間も1500kmのループも、快適で一貫した速度で再生されます。全体的に遅くするにはgroundSpeedを下げ(例:12000)、速くするには上げてください。キーフレーム数も自動スケーリングされます。 カメラは一定の水平オフセット+高度を維持し、パスの一端から他端までグライドし、常に移動するパス点を注視します(線形補間=一定速度のパン、イージングなし)。これは約1000kmの回廊に適したツールです:固定ショットでは全体を見るために宇宙まで上がる必要がありますが、トラベルショットは低く保ち、時間をかけて明らかにします。

トラベルショットのペーシングと地形感(河西回廊のチューニングで学習):

  • 速度 = パス長 ÷ 時間。1000kmの回廊を16秒で通過するとぼやけます;約30秒以上にすると街が読み取れます。地表速度が約30 km/sを超えると「速すぎ」と感じます。
  • 地形感(山と平野の高低差を感じる) には3つの要素が必要です:低いカメラ(alt 約12~18 km、40 kmではない — 高高度はすべてを平坦にする)、浅い注視角度(altに対して大きなoffsetDist → ピッチ約-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)、方位計算から自動的にヘディングを導出し、セグメント内のPOIが軸から28°以上ずれた場合に警告します(トラベルショットはこのチェックをスキップ — 設計上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秒) — 真のクロスフェード:タイムラインが分割され、各セグメントが個別にレンダリング(出力側セグメントはフリーズテールを保持)、その後ffmpegのxfadeで連結。余分なフレーム数 ≈ fps × transitionDuration × カット数。

Google Photorealistic 3D Tiles(都市)

"buildings3d": true,            // ionアセット2275207;CESIUM_ION_TOKEN必須;地球儀は非表示
"buildings3dQuality": 16        // maximumScreenSpaceError;低いほどシャープ=低速

都市のヒーローショットでは低く、近くに:pitch -18~-25、minSlant 1200~2000(3000mのスラントフロアをオーバーライド)、targetHeight ≈ 中層タワー(150~250m)。注意:Googleタイルはフレームごとにレンダリングが遅く、ionクォータを消費します;buildings3dがオンの場合、--workersはデフォルトで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°に傾ける。
  • 構図確認(計算する!):各キーフレームで、ヘディングはカメラ位置からターゲットを向いている必要があります — ベアリング ≈ atan2(Δlng·cos(lat), Δlat) で北からの角度。カメラを片側(例:ターゲットの南、ヘディング約0±25°)に保ち、優雅に弧を描かせる;ヘディングが逸れると、被写体(とルートアニメーション)がフレームから外れます。常に開始/中間/終了フレームを目視確認してから提供すること。
  • ショットあたりのヘディング変化は120°未満に抑える。さもないと動きが泳いで見えます。
  • POIのappearはカメラが落ち着いた少し後、タイトルはフライインの後に設定。
  • フレームが空白/黒い海タイルを表示する場合、TILE_TIMEOUT_MS環境変数を増やすか、カメラを遅くする。
  • 「地図更新中」のちらつきなし:各フレームはタイルが読み込まれ、かつSETTLE_MS(デフォルト500ms)の間読み込まれたままになるのを待ってからキャプチャ — したがって、次フレームでよりシャープになるストリーミング中のフレームを取得することはありません。重いシーン(低高度トラベル、高いverticalExaggeration、4K)では、TILE_TIMEOUT_MS=60000 SETTLE_MS=500でレンダリングし、タイルが完全に落ち着く余裕を持たせてください。SETTLE_MSを上げる(例:800)と、レンダリング時間と引き換えに安定したフレームが得られます。
  • 読みやすさのためのペーシング:地表速度 = パス長 ÷ duration。都市/地形がぼやけて通過する場合は、durationを2倍に。1000kmの回廊は、実際に場所を読むために約60秒を目安に。
  • 帰属表示:Cesium ion画像には可視の帰属表示が必要です — レンダラーはCesiumクレジットコンテナを表示したままにします;公開動画で切り取らないでください。

関連スキル