Basile Van Hoorick, Rundi Wu, Ege Ozguroglu, Kyle Sargent, Ruoshi Liu, Pavel Tokmakov, Achal Dave, Changxi Zheng, Carl Vondrick
Universitas Columbia, Universitas Stanford, Institut Penelitian Toyota
Diterbitkan di ECCV 2024 (Lisan)
Kertas | Situs web | Hasil | Kumpulan Data | Model
Repositori ini berisi kode Python yang diterbitkan sebagai bagian dari makalah kami "Generative Camera Dolly: Extreme Monocular Dynamic Novel View Synthesis" (disingkat GCD ).
Kami menyediakan instruksi penyiapan, model terlatih, kode inferensi, kode pelatihan, kode evaluasi, dan pembuatan kumpulan data.
Harap dicatat bahwa saya memfaktorkan ulang dan membersihkan basis kode untuk rilis publik, sebagian besar untuk menyederhanakan struktur serta meningkatkan keterbacaan dan modularitas, namun saya belum memeriksa semuanya secara menyeluruh, jadi jika Anda mengalami masalah, beri tahu kami dengan membuka masalah , dan jangan ragu untuk menyarankan kemungkinan perbaikan bug jika ada.
Daftar isi:
Saya sarankan menyiapkan lingkungan virtual dan menginstal paket yang diperlukan sebagai berikut:
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
Proyek ini sebagian besar dikembangkan dengan PyTorch versi 2.0.1, namun juga dapat digunakan dengan versi yang lebih baru. Secara khusus, sejauh ini saya tidak mengalami masalah dengan PyTorch 2.3.1, yang merupakan versi terbaru pada saat penulisan.
Perhatikan bahwa file persyaratan tidak menentukan versi paket, karena saya penggemar fleksibilitas (menambahkan batasan versi akan membuat penerapan basis kode yang ada di proyek baru Anda menjadi lebih rumit). Namun jika Anda mengalami masalah, beri tahu kami dengan membuka masalah. Saya juga memberikan versi persisnya di requirements_versions.txt
untuk referensi Anda.
Subfolder gcd-model
awalnya didasarkan pada repositori model generatif Stability AI resmi.
Di bawah ini adalah pos pemeriksaan Kubric-4D utama yang kami latih dan gunakan dalam eksperimen kami, bersama dengan nilai PSNR pada set pengujian. Kolom kiri menunjukkan perpindahan maksimum kamera dalam hal rotasi horizontal.
Azimut | Bertahap | Langsung |
---|---|---|
Maks 90 derajat | Tautan (17,88 dB) | Tautan (17,23 dB) |
Maks 180 derajat | Tautan (17,81 dB) | Tautan (16,65 dB) |
Di bawah ini adalah pos pemeriksaan ParallelDomain-4D utama yang kami latih dan gunakan dalam eksperimen kami, bersama dengan nilai PSNR atau mIoU pada set pengujian. Kolom kiri menunjukkan modalitas keluaran yang diprediksi (inputnya selalu RGB).
Pengandaian | Bertahap | Langsung |
---|---|---|
Warna (RGB) | Tautan (23,47 dB) | Tautan (23,32 dB) |
Semantik | Tautan (39,0%) | Tautan (36,7%) |
Semua pos pemeriksaan di atas berukuran 20,3 GB. Tempatkan mereka di pretrained/
sedemikian rupa sehingga memiliki nama yang sama dengan file konfigurasi .yaml
yang sesuai.
Bagian ini untuk menjalankan model kami dengan santai di video khusus. Untuk evaluasi kuantitatif menyeluruh pada Kubric-4D atau ParallelDomain-4D, atau inferensi baris perintah apa pun di luar kedua kumpulan data tersebut yang menyimpan hasil dan visualisasi ke disk Anda, silakan lihat bagian Evaluasi di bawah.
Untuk model Kubric-4D , jalankan:
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'
Untuk mencoba model lain, cukup ubah config_path
, model_path
dan task_desc
, misalnya untuk model 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)'
Untuk pelatihan dan evaluasi pada Kubric-4D dan/atau ParallelDomain-4D, Anda perlu melakukan praproses pada kumpulan data dan menyimpan point cloud gabungan. Hal ini karena kumpulan datanya sendiri hanya menyediakan video RGB-D dari sudut pandang tertentu, namun kami ingin terbang bebas dalam adegan 4D dan memungkinkan untuk mempelajari kontrol kamera sewenang-wenang (dan menginterpolasi lintasan) juga.
Untuk 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
Di sini, /path/to/Kubric-4D/data
seharusnya merupakan folder yang berisi scn00000
, scn00001
, dan seterusnya. Skrip akan membaca dari data
dan menulis ke pcl/
(pastikan Anda memiliki ruang kosong 7,0 TB).
Untuk 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
Di sini, /path/to/ParallelDomain-4D/data
seharusnya merupakan folder yang berisi scene_000000
, scene_000001
, dan seterusnya. Skrip akan membaca dari data/
dan menulis ke pcl/
(pastikan Anda memiliki ruang kosong sebesar 4,4 TB).
Kedua skrip konversi di atas terutama mengandalkan GPU untuk pemrosesan cepat dan dapat menerapkan paralelisasi pada tingkat proses. Misalnya, --gpus=0,0,1,1
berarti menghasilkan 4 pekerja (2 per GPU). Selama pelatihan, sebagian besar I/O disk akan terkonsentrasi di folder pcl/
, jadi saya sarankan menyimpannya di SSD lokal yang cepat.
Jika Anda berlatih dengan kumpulan data Anda sendiri, saya sarankan untuk membuat pemuat data baru menggunakan kode yang disediakan sebagai referensi. Jika Anda menggunakan data kami, silakan ikuti bagian Pemrosesan Dataset di atas terlebih dahulu.
Pertama, unduh salah satu dari dua pos pemeriksaan Difusi Video Stabil berikut yang tersedia: SVD (14 frame) atau SVD-XT (25 frame), dan letakkan di pretrained/
(atau perbarui jalur pos pemeriksaan di file konfigurasi yang dirujuk di bawah). Kami bekerja secara eksklusif dengan SVD versi 14-frame dalam eksperimen kami karena keterbatasan sumber daya, jadi harap ubah nilai konfigurasi relevan lainnya jika Anda bekerja dengan SVD-XT 25-frame.
Untuk memulai pelatihan GCD yang dijalankan di Kubric-4D (bertahap, maks 90 derajat):
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"
Untuk beralih ke model sintesis tampilan langsung (tanpa interpolasi), sesuaikan nilai ini: data.params.move_time=0
. Untuk meningkatkan sudut rotasi horizontal (azimuth) maksimum, pilih file konfigurasi lainnya: train_kubric_max180.yaml
.
Model yang dihasilkan akan mampu melakukan sintesis tampilan novel dinamis monokuler 3-DoF pada video RGB apa pun, tetapi biasanya akan memiliki performa terbaik dalam domain Kubric dan video lain yang tidak berisi manusia.
Untuk memulai pelatihan GCD di ParallelDomain-4D (bertahap, 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"
Untuk beralih ke model sintesis tampilan langsung (tanpa interpolasi), sesuaikan nilai ini: data.params.move_time=0
. Untuk mengubah modalitas keluaran ke kategori semantik, pilih file konfigurasi lainnya: train_pardom_semantic.yaml
.
Model yang dihasilkan akan mampu melakukan sintesis tampilan novel dinamis monokuler ke atas pada video RGB apa pun, namun biasanya akan memberikan performa terbaik pada adegan berkendara (baik sintetik maupun nyata) yang direkam menghadap ke depan di permukaan jalan. Saya juga memiliki model internal yang mampu mengontrol kamera 3-DoF (transformasi ego-to-surround serta surround-to-surround) pada kumpulan data ini, dan meskipun itu bukan bagian dari eksperimen dalam makalah kami, saya mungkin pamerkan dan/atau rilis di sini di masa mendatang.
Perhatikan bahwa dalam semua perintah di atas, indeks GPU 0 ( data.params.data_gpu
) dicadangkan untuk membuat pasangan video (input, ground truth) dengan cepat selama pemuatan data dari cloud titik gabungan yang di-cache di pcl/
. Saya sarankan untuk tidak melatih jaringan pada GPU yang sama, itulah sebabnya lightning.trainer.devices
terputus-putus dan mencakup semua GPU yang tersisa.
Penggunaan VRAM untuk perangkat tersebut adalah sekitar 50 GB per GPU dalam contoh yang diberikan. Tiga faktor penentu terbesar untuk VRAM adalah: (1) ukuran batch, (2) resolusi spasial ( frame_width
dan frame_height
), (3) jumlah frame (SVD versus SVD-XT), dan (4) apakah bobot EMA rata-rata aktif. Sebagian besar eksperimen kami dilakukan pada node tunggal dengan 8x perangkat NVIDIA A100 atau 8x NVIDIA A6000, semuanya tanpa EMA karena keterbatasan komputasi.
Log dan visualisasi akan disimpan ke subfolder bertanggal di dalam folder logs/
, yang berada pada level yang sama dengan gcd-model/
. Untuk setiap lari, visualisasi latihan disimpan dalam subfolder visuals/
. Jika pelatihan terhenti, Anda dapat melanjutkan dengan mengarahkan --resume_from_checkpoint
ke file checkpoint terbaru yang valid, misalnya --resume_from_checkpoint=../logs/2024-02-30T12-15-05_kb_v1/checkpoints/last.ckpt
.
Skrip berikut menghasilkan banyak jenis keluaran untuk inspeksi dan evaluasi visual, dan harus disesuaikan untuk setiap tolok ukur. Untuk pengoperasian yang lebih ringan, lihat bagian Inferensi di atas. Jika Anda menggunakan data kami, pastikan Anda mengikuti bagian Pemrosesan Kumpulan Data di atas terlebih dahulu. Jika Anda mengevaluasi kumpulan data khusus Anda sendiri dengan kebenaran dasar, saya sarankan untuk membuat pemuat data baru dan memodifikasi skrip pengujian di bawah.
Untuk mengevaluasi model GCD yang disempurnakan di Kubric-4D , perbarui jalur di kubric_test20.txt
dan jalankan:
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
Agar konsisten dan adil, perintah ini menerapkan serangkaian sudut kamera dan batas bingkai deterministik yang terkait dengan setiap adegan, yang dijelaskan dalam kubric_valtest_controls_gradual.json
. Angka-angka ini dihasilkan secara acak hanya sekali dan kemudian ditetapkan tetap, namun sedemikian rupa sehingga perspektif masukan (yaitu spherical_src
) selaras dengan indeks tampilan 4 dalam kumpulan data. Ubah ini menjadi kubric_valtest_controls_direct.json
jika Anda mengevaluasi model sintesis tampilan langsung. Selain itu, Anda dapat mengevaluasi beberapa sampel dengan meningkatkan --num_samples
(kontrol yang sama) atau dengan memvariasikan --control_idx
(kontrol berbeda per adegan).
Untuk mengevaluasi model GCD yang disempurnakan pada ParallelDomain-4D , perbarui jalur di pardom_test20.txt
dan jalankan:
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
Sama seperti sebelumnya, sekali lagi untuk konsistensi dan keadilan, sinyal kontrol pardom_valtest_controls.json
hanya berisi batas bingkai (yaitu offset dan interval) untuk setiap adegan.
Dalam semua kasus, untuk argumen --model_path
, grep
diterapkan untuk menangani wildcard sehingga Anda tidak perlu khawatir harus menulis tanggal. Kerangka kebenaran dasar yang sesuai juga dirender dan disimpan dalam folder keluaran, sehingga memungkinkan evaluasi numerik (lihat Metrik di bawah).
Jika Anda ingin mengabaikan kontrol JSON yang disediakan dan menjalankan evaluasi dalam bentuk yang lebih bebas dengan sudut dan batas bingkai yang dipilih di 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
Di ParallelDomain-4D, enam argumen terkait pose tidak berlaku, namun batas bingkai klip video masih dapat dipilih.
Skrip test.py
di atas menyimpan file *_metrics.json
per adegan di bawah subfolder extra/
yang berisi nomor PSNR dan SSIM secara keseluruhan serta per frame. Ini juga menyimpan semua frame input, prediksi, dan target individual sebagai gambar untuk setiap contoh yang diproses oleh model. Jangan ragu untuk menggunakan berbagai keluaran ini dalam alur kerja evaluasi kuantitatif Anda sendiri jika Anda ingin menghitung metrik tambahan dan/atau agregat.
Dibandingkan dengan bagian Evaluasi utama, skrip ini tidak bergantung pada kebenaran dasar, yang mungkin tidak ada. Dibandingkan dengan bagian Inferensi (Gradio) , skrip ini mengekspor lebih banyak informasi dan visualisasi.
Siapkan jalur langsung ke file video atau folder gambar, atau daftar file video atau folder gambar (dalam file .txt
dengan jalur lengkap), dan jalankan:
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
Perhatikan bahwa --frame_rate
harus mencerminkan target FPS setelah subsampling sementara dari video input, bukan sebelum . Jika Anda ingin mengevaluasi beberapa contoh, saya sarankan menggunakan daftar dengan menyetel --input=/path/to/list.txt
untuk mengurangi overhead pemuatan model.
Jika Anda ingin menggunakan data yang sama persis seperti dalam eksperimen kami, silakan lihat tautan unduhan ini untuk deskripsi dan salinan Kubric-4D dan ParallelDomain-4D. Sisa bagian ini berfokus pada apakah Anda ingin mengubah saluran kami dan/atau membuat data sintetis Anda sendiri.
Ikuti petunjuk ini untuk menginstal perpustakaan OpenEXR. Kemudian, jalankan perintah berikut untuk mempersiapkan lingkungan Anda:
conda activate gcd
pip install bpy==3.4.0
pip install pybullet
pip install OpenEXR
cd data-gen/kubric/
pip install -e .
Subfolder data-gen/kubric
sebagian besar sama dengan komit ini dari repositori resmi Google Research Kubric, tetapi saya menambahkan perbaikan bug kecil untuk menghindari kondisi balapan saat menangani peta kedalaman.
Ini adalah perintah yang kami gunakan untuk menghasilkan kumpulan data akhir Kubric-4D (perhatikan baris 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
Kumpulan data ini pada dasarnya adalah variasi dari TCOW Kubric dan mencakup peningkatan seperti objek yang lebih dinamis dan peningkatan realisme massa. Lihat tambahan TCOW untuk rinciannya.
Untuk keperluan GCD, kami merender 16 video multi-tayangan tersinkronisasi dari kamera statis. Empat titik pandang berada pada ketinggian tinggi 45 derajat, dan dua belas sudut pandang lainnya berada pada ketinggian rendah 5 derajat. Saya sarankan untuk memeriksa export_kub_mv.py
untuk mendapatkan lebih banyak wawasan tentang parameter dan logikanya.
Semua adegan dihasilkan iid, jadi dalam versi kumpulan data ini, kami mendefinisikan 2800 pertama sebagai set pelatihan dan 100 + 100 terakhir sebagai set validasi + pengujian. Loop for luar secara teratur membersihkan folder /tmp/
untuk menghindari masalah ruang disk.
Kumpulan data ini berasal dari layanan dan tidak dapat dibuat ulang. Silakan lihat tautan unduhan untuk salinan kami.
Perhatikan bahwa beberapa folder adegan tidak ada (ada 1.531 folder adegan tetapi indeksnya naik hingga 2.143), dan beberapa adegan memiliki beberapa bingkai yang hilang, itulah sebabnya pemuat data kami dirancang agar tahan terhadap kedua masalah tersebut. Anda mungkin melihat beberapa pesan peringatan selama latihan, tetapi ini normal. Selain itu, tidak seperti Kubric, adegannya tidak terkait dengan indeks, oleh karena itu di pardom_datasplit.json
kami telah memilih subset acak untuk pelatihan, validasi, dan pengujian.
Kami mendefinisikan ukuran set validasi + pengujian masing-masing menjadi 61 + 61 adegan (masing-masing sekitar 4% dari total kumpulan data).
Saya telah menulis beberapa alat, berdasarkan TRI camviz, untuk memvisualisasikan contoh adegan secara interaktif dari Kubric-4D dan ParallelDomain-4D di komputer lokal Anda. Saya mungkin akan merilisnya di sini nanti, tetapi jangan ragu untuk menghubungi saya (Basile) sementara itu untuk mendapatkan kode sumbernya.
Jika Anda menggunakan basis kode ini dalam pekerjaan Anda (atau bagian penting lainnya, seperti perubahan yang diperlukan untuk menyempurnakan SVD), harap kutip makalah kami:
@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}
}
Saya sarankan juga mengutip makalah SVD asli:
@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}
}
Jika Anda menggunakan salah satu kumpulan data kami dalam karya Anda, harap kutip juga sumbernya masing-masing:
@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/}}
}