gcd
1.0.0
Basile Van Hoorick、Rundi Wu、Ege Ozguroglu、Kyle Sargent、劉若詩、Pavel Tokmakov、Achal Dave、Changxi Cheng、Carl Vondrick
哥倫比亞大學、史丹佛大學、豐田研究所
發表於ECCV 2024（口頭）
紙|網站 |結果 |數據集 |型號
該儲存庫包含作為我們的論文“生成相機多莉：極端單目動態小說視圖合成” （縮寫為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 生成模型儲存庫。
以下是我們在實驗中訓練和使用的主要Kubric-4D檢查點，以及測試集上的 PSNR 值。左欄表示相機水平旋轉的最大位移。
| 方位角 | 循序漸進 | 直接的 |
|---|---|---|
| 最大90度 | 連結（17.88 分貝） | 連結（17.23 分貝） |
| 最大180度 | 連結（17.81 分貝） | 連結（16.65 分貝） |
以下是我們在實驗中訓練和使用的主要ParallelDomain-4D檢查點，以及測試集上的 PSNR 或 mIoU 值。左列表示預測的輸出模式（輸入始終為 RGB）。
| 模態 | 循序漸進 | 直接的 |
|---|---|---|
| 顏色（RGB） | 連結（23.47 分貝） | 連結（23.32 分貝） |
| 語意學 | 連結 (39.0%) | 連結 (36.7%) |
以上所有檢查點的大小為 20.3 GB。將它們放在pretrained/中，使其與對應的 config .yaml檔案具有相同的名稱。
本部分用於在自訂影片上隨意運行我們的模型。若要對 Kubric-4D 或 ParallelDomain-4D 進行徹底的定量評估，或在這兩個資料集之外將結果和視覺化儲存到磁碟的任何命令列推理，請參閱下面的評估部分。
對於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 上。
如果您正在對自己的資料集進行訓練，我建議使用提供的程式碼作為參考來建立新的資料載入器。如果您正在使用我們的數據，請先按照上面的數據集處理部分進行操作。
首先，下載以下兩個可用的穩定視訊擴散檢查點之一：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上開始 GCD 訓練（漸變，RGB）：
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。
在提供的範例中，每個 GPU 的 VRAM 使用量約為 50 GB。 VRAM 的三個最大決定因素是：(1) 批量大小、(2) 空間解析度（ frame_width和frame_height ）、(3) 幀數（SVD 與 SVD-XT）以及 (4) 是否使用 EMA 權重平均已激活。我們的大多數實驗都是在具有 8 個 NVIDIA A100 或 8 個 NVIDIA A6000 設備的單節點上完成的，由於計算有限，所有實驗都沒有使用 EMA。
日誌和視覺化將儲存到logs/資料夾內的一個帶有日期的子資料夾中，該資料夾與gcd-model/位於同一層級。對於每次運行，訓練視覺化都儲存在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中所述。這些數字僅隨機產生一次，隨後保持固定，但輸入視角（即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 中，六個與姿勢相關的參數不適用，但仍可選擇影片剪輯幀邊界。
上面的test.py腳本將每個場景的*_metrics.json檔案保存在extra/子資料夾下，其中包含整體以及每個畫面的 PSNR 和 SSIM 數字。它還將所有單獨的輸入、預測和目標幀保存為模型處理的每個範例的圖像。如果您想計算附加和/或聚合指標，請隨意在您自己的定量評估工作流程中使用這些不同的輸出。
與主要評估部分相比，該腳本不依賴可能不存在的基本事實。與推理（漸變）部分相比，此腳本導出更多資訊和視覺化。
準備視訊檔案或圖像資料夾的直接路徑，或視訊檔案或圖像資料夾的清單（在具有完整路徑的.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 個來自靜態攝影機的同步多視圖影片。四個視點位於45度的高海拔處，另外十二個視點位於5度的低海拔處。我建議檢查export_kub_mv.py以更深入地了解其參數和邏輯。
所有場景都是產生 iid，因此在我們的資料集版本中，我們將前 2800 個場景定義為訓練集，最後 100 + 100 個分別定義為驗證集 + 測試集。外部 for 迴圈定期清除/tmp/資料夾以避免磁碟空間問題。
此資料集來自服務，無法重新產生。請參閱我們副本的下載連結。
請注意，某些場景資料夾不存在（有1531 個場景資料夾，但索引高達2143），並且某些場景有幾個遺失的幀，這就是為什麼我們的資料載入器被設計為對這兩個問題都具有魯棒性。在訓練期間您可能會看到一些警告訊息，但這是正常的。此外，與 Kubric 不同，場景與索引不相關，因此在pardom_datasplit.json中，我們預先選擇了隨機子集進行訓練、驗證和測試。
我們將驗證集 + 測試集大小分別定義為 61 + 61 個場景（每個場景約佔總資料集的 4%）。
我編寫了一些基於 TRI camviz 的工具，可以在本機電腦上以互動方式視覺化 Kubric-4D 和 ParallelDomain-4D 的範例場景。我可能稍後會在這裡發布它們，但請隨時與我（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/}}
}
