gcd
1.0.0
バジル・ヴァン・フーリック、ランディ・ウー、イーゲ・オズグログル、カイル・サージェント、ルオシ・リュー、パベル・トクマコフ、アチャル・デイブ、チャンシー・ジェン、カール・ヴォドリック
コロンビア大学、スタンフォード大学、トヨタ研究所
ECCV 2024 で発表（口頭）
紙 |ウェブサイト |結果 |データセット |モデル
このリポジトリには、論文「Generative Camera Dolly: Extreme Monocular Dynamic Novel View Synthesis」 (略称GCD ) の一部として公開された Python コードが含まれています。
セットアップ手順、事前トレーニング済みモデル、推論コード、トレーニング コード、評価コード、データセット生成を提供します。
主に構造を簡素化し、読みやすさとモジュール性を高めるために、公開リリースに向けてコードベースをリファクタリングしてクリーンアップしましたが、まだすべてを徹底的に精査したわけではないため、問題が発生した場合は、問題を作成してお知らせください。可能性のあるバグ修正がある場合は、お気軽に提案してください。
目次：
次のように仮想環境をセットアップし、必要なパッケージをインストールすることをお勧めします。
conda create -n gcd python=3.10
conda activate gcd
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
pip install git+https://github.com/OpenAI/CLIP.git
pip install git+https://github.com/Stability-AI/datapipelines.git
pip install -r requirements.txt
このプロジェクトは主に PyTorch バージョン 2.0.1 で開発されましたが、それ以降のバージョンでも動作するはずです。特に、この記事の執筆時点での最新バージョンである PyTorch 2.3.1 では、これまでのところ問題は発生していません。
私は柔軟性を重視しているため、要件ファイルではパッケージのバージョンが指定されていないことに注意してください (バージョン制約を追加すると、新しいプロジェクトに既存のコードベースを採用することがさらに面倒になります)。ただし、問題が発生した場合は、問題を開いてお知らせください。参考までに、 requirements_versions.txtに正確なバージョンも記載しました。
サブフォルダーgcd-model 、もともと公式の Stability AI 生成モデル リポジトリに基づいています。
以下は、テスト セットの PSNR 値とともに、トレーニングおよび実験で使用した主要なKubric-4Dチェックポイントです。左の列は、水平方向の回転に関するカメラの最大変位を示します。
| 方位角 | 徐々に | 直接 |
|---|---|---|
| 最大90度 | リンク(17.88dB) | リンク(17.23dB) |
| 最大180度 | リンク(17.81dB) | リンク(16.65dB) |
以下は、テスト セットの PSNR または mIoU 値とともに、トレーニングおよび実験で使用した主なParallelDomain-4Dチェックポイントです。左の列は、予測された出力モダリティを示します (入力は常に RGB です)。
| モダリティ | 徐々に | 直接 |
|---|---|---|
| カラー(RGB) | リンク(23.47dB) | リンク(23.32dB) |
| セマンティック | リンク (39.0%) | リンク (36.7%) |
上記のチェックポイントはすべて、サイズが 20.3 GB です。対応する config .yamlファイルと同じ名前になるように、それらをpretrained/に配置します。
このセクションは、カスタム ビデオでモデルを気軽に実行するためのものです。 Kubric-4D または ParallelDomain-4D の完全な定量的評価、または結果と視覚化をディスクに保存するこれら 2 つのデータセット以外のコマンド ライン推論については、代わりに以下の「評価」セクションを参照してください。
Kubric-4Dモデルの場合は、次を実行します。
cd gcd-model/
CUDA_VISIBLE_DEVICES=0 python scripts/gradio_app.py --port=7880
--config_path=configs/infer_kubric.yaml
--model_path=../pretrained/kubric_gradual_max90.ckpt
--output_path=../eval/gradio_output/default/
--examples_path=../eval/gradio_examples/
--task_desc='Arbitrary monocular dynamic view synthesis on Kubric scenes up to 90 degrees azimuth'
他のモデルを試してみるには、 config_path 、 model_path 、およびtask_desc変更するだけです (たとえば、 ParallelDomain-4Dモデルの場合)。
cd gcd-model/
CUDA_VISIBLE_DEVICES=1 python scripts/gradio_app.py --port=7881
--config_path=configs/infer_pardom.yaml
--model_path=../pretrained/pardom_gradual_rgb.ckpt
--output_path=../eval/gradio_output/default/
--examples_path=../eval/gradio_examples/
--task_desc='Upward monocular dynamic view synthesis on ParallelDomain scenes (RGB output)'
Kubric-4D および/または ParallelDomain-4D でトレーニングおよび評価するには、データセットを前処理し、マージされた点群を保存する必要があります。これは、データセット自体が特定の視点からの RGB-D ビデオのみを提供するためですが、4D シーン内を自由に飛び回って、任意のカメラ コントロール (および補間軌道) を学習できるようにしたいと考えているためです。
Kubric-4Dの場合:
cd data-gen/
python convert_pcl_kubric.py --gpus=0,0,1,1 --start_idx=0 --end_idx=3000
--input_root=/path/to/Kubric-4D/data
--output_root=/path/to/Kubric-4D/pcl
ここで、 /path/to/Kubric-4D/data scn00000 、 scn00001などが含まれるフォルダーである必要があります。スクリプトはdataを読み取り、 pcl/に書き込みます (7.0 TB の空き領域があることを確認してください)。
ParallelDomain-4Dの場合:
cd data-gen/
python convert_pcl_pardom.py --gpus=0,0,1,1 --start_idx=0 --end_idx=1600
--input_root=/path/to/ParallelDomain-4D/data
--output_root=/path/to/ParallelDomain-4D/pcl
ここで、 /path/to/ParallelDomain-4D/data scene_000000 、 scene_000001などが含まれるフォルダーである必要があります。スクリプトはdata/から読み取り、 pcl/に書き込みます (4.4 TB の空き領域があることを確認してください)。
上記の両方の変換スクリプトは、高速処理のために主に GPU に依存しており、プロセス レベルで並列化を適用できます。たとえば、 --gpus=0,0,1,1 4 つのワーカー (GPU ごとに 2 つ) を生成することを意味します。トレーニング中、ディスク I/O のほとんどはpcl/フォルダー内に集中するため、高速なローカル SSD に保存することをお勧めします。
独自のデータセットでトレーニングしている場合は、提供されたコードを参照として使用して新しいデータ ローダーを作成することをお勧めします。当社のデータを使用している場合は、まず上記の「データセット処理」セクションに従ってください。
まず、利用可能な 2 つの安定したビデオ拡散チェックポイント (SVD (14 フレーム) または SVD-XT (25 フレーム)) のいずれかをダウンロードし、 pretrained/に配置します (または、以下で参照する構成ファイル内のチェックポイント パスを更新します)。リソースの制約のため、実験では 14 フレーム バージョンの SVD のみを使用します。そのため、25 フレーム SVD-XT を使用している場合は、他の関連する設定値を変更してください。
Kubric-4Dで GCD トレーニングの実行を開始するには (段階的、最大 90 度):
cd gcd-model/
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 python main.py
--base=configs/train_kubric_max90.yaml
--name=kb_v1 --seed=1234 --num_nodes=1 --wandb=0
model.base_learning_rate=2e-5
model.params.optimizer_config.params.foreach=False
data.params.dset_root=/path/to/Kubric-4D/data
data.params.pcl_root=/path/to/Kubric-4D/pcl
data.params.frame_width=384
data.params.frame_height=256
data.params.trajectory=interpol_linear
data.params.move_time=13
data.params.camera_control=spherical
data.params.batch_size=4
data.params.num_workers=4
data.params.data_gpu=0
lightning.callbacks.image_logger.params.batch_frequency=50
lightning.trainer.devices="1,2,3,4,5,6,7"
ダイレクトビュー合成モデル (補間なし) に切り替えるには、この値を調整します: data.params.move_time=0 。最大水平回転 (方位角) 角度を増やすには、他の構成ファイルtrain_kubric_max180.yamlを選択します。
結果として得られるモデルは、任意の RGB ビデオ上で 3-DoF 単眼ダイナミック ノベル ビュー合成を実行できますが、通常は Kubric ドメインや人間が含まれていないその他のビデオ内で最高のパフォーマンスを発揮します。
ParallelDomain-4D (段階的、RGB) で GCD トレーニングの実行を開始するには:
cd gcd-model/
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 python main.py
--base=configs/train_pardom_rgb.yaml
--name=pd_v1 --seed=1234 --num_nodes=1 --wandb=0
model.base_learning_rate=2e-5
model.params.optimizer_config.params.foreach=False
data.params.dset_root=/path/to/ParallelDomain-4D/data
data.params.pcl_root=/path/to/ParallelDomain-4D/pcl
data.params.split_json=../eval/list/pardom_datasplit.json
data.params.frame_width=384
data.params.frame_height=256
data.params.output_modality=rgb
data.params.trajectory=interpol_sine
data.params.move_time=13
data.params.modal_time=0
data.params.camera_control=none
data.params.batch_size=4
data.params.num_workers=4
data.params.data_gpu=0
lightning.callbacks.image_logger.params.batch_frequency=50
lightning.trainer.devices="1,2,3,4,5,6,7"
ダイレクトビュー合成モデル (補間なし) に切り替えるには、この値を調整します: data.params.move_time=0 。出力モダリティをセマンティック カテゴリに変更するには、他の構成ファイルtrain_pardom_semantic.yamlを選択します。
結果として得られるモデルは、任意の RGB ビデオ上で上向きの単眼ダイナミック ノベル ビュー合成を実行できますが、通常、道路レベルで前方を向いて記録された運転シーン (合成と現実の両方) で最高のパフォーマンスを発揮します。また、このデータセット上で 3-DoF カメラ制御 (エゴからサラウンドへの変換、およびサラウンドからサラウンドへの変換) が可能な内部モデルも配置しています。これらは論文の実験の一部ではありませんが、将来的にはここで展示および/またはリリースします。
上記のすべてのコマンドで、GPU インデックス 0 ( data.params.data_gpu ) は、 pcl/にキャッシュされたマージされた点群からのデータの読み込み中に (入力、グラウンド トゥルース) ビデオのペアをオンザフライで構築するために予約されていることに注意してください。同じ GPU 上でネットワークをトレーニングしないことをお勧めします。そのため、 lightning.trainer.devices切り離されており、代わりに残りのすべての GPU をカバーします。
提供されている例では、これらの VRAM 使用量は GPU あたり約 50 GB になります。 VRAM の 3 つの最大の決定要因は、(1) バッチ サイズ、(2) 空間解像度 ( frame_widthおよびframe_height )、(3) フレーム数 (SVD と SVD-XT)、および (4) EMA の重みが適用されるかどうかです。平均化がアクティブです。私たちの実験のほとんどは、8x NVIDIA A100 デバイスまたは 8x NVIDIA A6000 デバイスを備えた単一ノードで行われました。コンピューティングが限られているため、すべて EMA を使用しませんでした。
ログと視覚化は、 gcd-model/と同じレベルにあるlogs/フォルダー内の日付付きのサブフォルダーに保存されます。実行ごとに、トレーニングの視覚化がvisuals/サブフォルダーに保存されます。トレーニングが中断された場合は、 --resume_from_checkpoint最新の有効なチェックポイント ファイル (例: --resume_from_checkpoint=../logs/2024-02-30T12-15-05_kb_v1/checkpoints/last.ckpt ) に指定することで再開できます。
次のスクリプトは、視覚的な検査と評価用にさまざまな種類の出力を生成するため、各ベンチマークに適合させる必要があります。より軽い操作については、上記の「推論」セクションを参照してください。当社のデータを使用している場合は、まず上記の「データセット処理」セクションに従っていることを確認してください。グラウンド トゥルースを使用して独自のカスタム データセットを評価している場合は、新しいデータ ローダーを作成し、以下のテスト スクリプトを変更することをお勧めします。
Kubric-4Dで GCD 微調整モデルを評価するには、 kubric_test20.txt内のパスを更新して、次を実行します。
cd gcd-model/
CUDA_VISIBLE_DEVICES=0,1 python scripts/test.py --gpus=0,1
--config_path=configs/infer_kubric.yaml
--model_path=../logs/*_kb_v1/checkpoints/epoch=00000-step=00010000.ckpt
--input=../eval/list/kubric_test20.txt
--output=../eval/output/kubric_mytest1
--control_json=../eval/list/kubric_valtest_controls_gradual.json
--control_idx=0 --autocast=1 --num_samples=2 --num_steps=25
一貫性と公平性を確保するために、このコマンドは、 kubric_valtest_controls_gradual.jsonで説明されている、各シーンに関連付けられたカメラ アングルとフレーム境界の決定的なセットを適用します。これらの数値は 1 回だけランダムに生成され、その後は固定されますが、入力パースペクティブ (すなわちspherical_src ) がデータセット内のビュー インデックス 4 と位置合わせされるようになります。ダイレクトビュー合成モデルを評価している場合は、これをkubric_valtest_controls_direct.jsonに変更します。また、 --num_samples (同じコントロール) を増やすか、 --control_idx (シーンごとに異なるコントロール) を変更することで、複数のサンプルを評価できます。
ParallelDomain-4Dで GCD 微調整モデルを評価するには、 pardom_test20.txt内のパスを更新して、次を実行します。
cd gcd-model/
CUDA_VISIBLE_DEVICES=0,1 python scripts/test.py --gpus=0,1
--config_path=configs/infer_pardom.yaml
--model_path=../logs/*_pd_v1/checkpoints/epoch=00000-step=00010000.ckpt
--input=../eval/list/pardom_test20.txt
--output=../eval/output/pardom_mytest1
--control_json=../eval/list/pardom_valtest_controls.json
--control_idx=0 --autocast=1 --num_samples=2 --num_steps=25
以前と同様に、やはり一貫性と公平性を確保するために、制御信号pardom_valtest_controls.jsonは各シーンのフレーム境界 (つまり、オフセットと間隔) のみが含まれています。
すべての場合において、 --model_path引数については、ワイルドカードを処理するためにgrepが適用されるため、日付を記述する必要があることを心配する必要はありません。対応するグラウンド トゥルース フレームもレンダリングされて出力フォルダーに保存され、数値評価が可能になります (下記のメトリクスを参照)。
提供された JSON コントロールを無視し、代わりに Kubric-4D で選択した角度とフレーム境界を使用して、より自由形式の方法で評価を実行する場合:
cd gcd-model/
CUDA_VISIBLE_DEVICES=0,1 python scripts/test.py --gpus=0,1
--config_path=configs/infer_kubric.yaml
--model_path=../logs/*_kb_v1/checkpoints/epoch=00000-step=00010000.ckpt
--input=../eval/list/kubric_test20.txt
--output=../eval/output/kubric_mytest2_cc
--azimuth_start=70.0 --elevation_start=10.0 --radius_start=15.0
--delta_azimuth=30.0 --delta_elevation=15.0 --delta_radius=1.0
--frame_start=0 --frame_stride=2 --frame_rate=12
--reproject_rgbd=0 --autocast=1 --num_samples=2 --num_steps=25
ParallelDomain-4D では、6 つのポーズ関連の引数は適用できませんが、ビデオ クリップのフレーム境界は引き続き選択できます。
上記のtest.pyスクリプトは、全体およびフレームごとの PSNR および SSIM 番号を含むシーンごとの*_metrics.jsonファイルをextra/サブフォルダーに保存します。また、すべての個々の入力フレーム、予測フレーム、およびターゲット フレームを、モデルによって処理された各サンプルの画像として保存します。追加の指標や集計指標を計算したい場合は、これらのさまざまな出力を独自の定量的評価ワークフローで自由に使用してください。
メインの評価セクションと比較すると、このスクリプトは存在しない可能性があるグラウンド トゥルースに依存しません。推論 (Gradio)セクションと比較して、このスクリプトはより多くの情報と視覚化をエクスポートします。
ビデオ ファイルまたは画像フォルダーへの直接パス、またはビデオ ファイルまたは画像フォルダーのリスト (フル パスを含む.txtファイル内) を準備し、次を実行します。
cd gcd-model/
CUDA_VISIBLE_DEVICES=0 python scripts/infer.py --gpus=0
--config_path=configs/infer_kubric.yaml
--model_path=../pretrained/kubric_gradual_max90.ckpt
--input=/path/to/video.mp4
--output=../eval/output/kubric_myinfer1
--delta_azimuth=30.0 --delta_elevation=15.0 --delta_radius=1.0
--frame_start=0 --frame_stride=2 --frame_rate=12
--autocast=1 --num_samples=2 --num_steps=25
--frame_rate 、入力ビデオの時間サブサンプリングの前ではなく、後のターゲット FPS を反映する必要があることに注意してください。複数の例を評価する場合は、モデル読み込みのオーバーヘッドを軽減するために--input=/path/to/list.txtを設定してリストを使用することをお勧めします。
実験とまったく同じデータを使用したい場合は、このダウンロード リンクで Kubric-4D および ParallelDomain-4D の説明とコピーを参照してください。このセクションの残りの部分では、パイプラインを調整したり、独自の合成データを生成したりするかどうかに焦点を当てます。
OpenEXR ライブラリをインストールするには、次の手順に従ってください。次に、次のコマンドを実行して環境を準備します。
conda activate gcd
pip install bpy==3.4.0
pip install pybullet
pip install OpenEXR
cd data-gen/kubric/
pip install -e .
サブフォルダーdata-gen/kubric Google Research Kubric 公式リポジトリのこのコミットとほぼ同じですが、深度マップを処理する際の競合状態を回避するために小さなバグ修正を追加しました。
これは、最終的な Kubric-4D データセットを生成するために使用したコマンドです ( rm -rf /tmp/行に注意してください)。
cd data-gen/
for i in {1..110}
do
python export_kub_mv.py --mass_est_fp=gpt_mass_v4.txt
--root_dp=/path/to/kubric_mv_gen
--num_scenes=3000 --num_workers=10 --restart_count=30
--seed=900000 --num_views=16 --frame_width=576 --frame_height=384
--num_frames=60 --frame_rate=24 --save_depth=1 --save_coords=1
--render_samples_per_pixel=16 --focal_length=32
--fixed_alter_poses=1 --few_views=4
rm -rf /tmp/
done
このデータセットは基本的に TCOW Kubric のバリエーションであり、よりダイナミックなオブジェクトやマス リアリズムの向上などの改良が含まれています。詳細については、TCOW の補足を参照してください。
GCD の目的で、静止カメラから 16 個の同期されたマルチビュー ビデオをレンダリングします。 4 つの視点は標高 45 度の高さにあり、他の 12 つの視点は標高 5 度の低地にあります。そのパラメータとロジックについてさらに洞察を得るために、 export_kub_mv.py検査することをお勧めします。
すべてのシーンは iid で生成されるため、このデータセットのバージョンでは、最初の 2800 をトレーニング セットとして、最後の 100 + 100 を検証 + テスト セットとしてそれぞれ定義します。外側の for ループは、ディスク容量の問題を回避するために/tmp/フォルダーを定期的にクリアします。
このデータセットはサービスから取得されたものであり、再生成できません。コピーのダウンロードリンクをご覧ください。
一部のシーン フォルダーは存在しないことに注意してください (シーン フォルダーは 1531 個ありますが、インデックスは 2143 までになります)。また、一部のシーンには欠落したフレームがいくつかあります。そのため、データローダーは両方の問題に対して堅牢になるように設計されています。トレーニング中にいくつかの警告メッセージが表示される場合がありますが、これは正常な現象です。また、Kubric とは異なり、シーンはインデックスに関して非相関化されていないため、 pardom_datasplit.jsonでは、トレーニング、検証、テスト用にランダムなサブセットを事前に選択しました。
検証 + テスト セットのサイズをそれぞれ 61 + 61 シーン (それぞれ合計データセットの約 4%) と定義します。
私は、ローカル コンピューター上で Kubric-4D および ParallelDomain-4D のサンプル シーンをインタラクティブに視覚化するための、TRI camviz に基づいたいくつかのツールを作成しました。後でここでリリースするかもしれませんが、それまでの間、ソース コードについてはお気軽に私 (Basile) までご連絡ください。
このコードベースを自分の作業 (または SVD の微調整に必要な変更などの重要な部分) で使用する場合は、次の論文を引用してください。
@article{vanhoorick2024gcd,
title={Generative Camera Dolly: Extreme Monocular Dynamic Novel View Synthesis},
author={Van Hoorick, Basile and Wu, Rundi and Ozguroglu, Ege and Sargent, Kyle and Liu, Ruoshi and Tokmakov, Pavel and Dave, Achal and Zheng, Changxi and Vondrick, Carl},
journal={European Conference on Computer Vision (ECCV)},
year={2024}
}
元の SVD 論文も引用することをお勧めします。
@article{blattmann2023stable,
title={Stable video diffusion: Scaling latent video diffusion models to large datasets},
author={Blattmann, Andreas and Dockhorn, Tim and Kulal, Sumith and Mendelevitch, Daniel and Kilian, Maciej and Lorenz, Dominik and Levi, Yam and English, Zion and Voleti, Vikram and Letts, Adam and others},
journal={arXiv preprint arXiv:2311.15127},
year={2023}
}
仕事で当社のデータセットのいずれかを使用する場合は、それぞれのソースも引用してください。
@article{greff2021kubric,
title = {Kubric: a scalable dataset generator},
author = {Klaus Greff and Francois Belletti and Lucas Beyer and Carl Doersch and Yilun Du and Daniel Duckworth and David J Fleet and Dan Gnanapragasam and Florian Golemo and Charles Herrmann and others},
booktitle = {IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
year = {2022},
}
@misc{parallel_domain,
title = {Parallel Domain},
year = {2024},
howpublished={url{https://paralleldomain.com/}}
}
