gcd
1.0.0
Basile Van Hoorick, Rundi Wu, Ege Ozguroglu, Kyle Sargent, Ruoshi Liu, Pavel Tokmakov, Achal Dave, Changxi Zheng, Carl Vondrick
Université Columbia, Université Stanford, Institut de recherche Toyota
Publié dans ECCV 2024 (Oral)
Papier | Site Web | Résultats | Ensembles de données | Modèles
Ce référentiel contient le code Python publié dans le cadre de notre article "Generative Camera Dolly: Extreme Monocular Dynamic Novel View Synthesis" (en abrégé GCD ).
Nous fournissons des instructions de configuration, des modèles pré-entraînés, un code d'inférence, un code de formation, un code d'évaluation et la génération d'ensembles de données.
Veuillez noter que j'ai refactorisé et nettoyé la base de code pour la publication publique, principalement pour simplifier la structure ainsi que pour améliorer la lisibilité et la modularité, mais je n'ai pas encore tout vérifié, donc si vous rencontrez des problèmes, veuillez nous le faire savoir en ouvrant un numéro. , et n'hésitez pas à suggérer d'éventuelles corrections de bugs si vous en avez.
Table des matières:
Je recommande de configurer un environnement virtuel et d'installer les packages nécessaires comme suit :
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
Le projet a été principalement développé avec la version 2.0.1 de PyTorch, mais il devrait également fonctionner avec les versions ultérieures. En particulier, je n'ai rencontré aucun problème jusqu'à présent avec PyTorch 2.3.1, qui est la dernière version au moment de la rédaction.
Notez que le fichier d'exigences ne spécifie pas les versions de package, car je suis fan de flexibilité (l'ajout de contraintes de version rendrait autrement l'adoption de bases de code existantes dans vos nouveaux projets plus lourdes). Si vous rencontrez des problèmes, veuillez nous en informer en ouvrant un ticket. J'ai également fourni les versions exactes dans requirements_versions.txt pour votre référence.
Le sous-dossier gcd-model est à l'origine basé sur le référentiel officiel de modèles génératifs Stability AI.
Vous trouverez ci-dessous les principaux points de contrôle Kubric-4D que nous avons entraînés et utilisés dans nos expériences, ainsi que les valeurs PSNR sur l'ensemble de test. La colonne de gauche indique le déplacement maximum de la caméra en termes de rotation horizontale.
| Azimut | Graduel | Direct |
|---|---|---|
| Max 90 degrés | Lien (17,88 dB) | Lien (17,23 dB) |
| Max 180 degrés | Lien (17,81 dB) | Liaison (16,65 dB) |
Vous trouverez ci-dessous les principaux points de contrôle ParallelDomain-4D que nous avons formés et utilisés dans nos expériences, ainsi que les valeurs PSNR ou mIoU sur l'ensemble de test. La colonne de gauche indique la modalité de sortie prévue (l'entrée est toujours RVB).
| Modalité | Graduel | Direct |
|---|---|---|
| Couleur (RVB) | Lien (23,47 dB) | Lien (23,32 dB) |
| Sémantique | Lien (39,0%) | Lien (36,7%) |
Tous les points de contrôle ci-dessus ont une taille de 20,3 Go. Placez-les dans pretrained/ de telle sorte qu'ils portent le même nom que les fichiers de configuration .yaml correspondants.
Cette section est destinée à exécuter notre modèle avec désinvolture sur des vidéos personnalisées. Pour une évaluation quantitative approfondie sur Kubric-4D ou ParallelDomain-4D, ou pour toute inférence de ligne de commande en dehors de ces deux ensembles de données qui enregistre les résultats et les visualisations sur votre disque, veuillez plutôt consulter la section Évaluation ci-dessous.
Pour un modèle Kubric-4D , exécutez :
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'
Pour essayer d'autres modèles, modifiez simplement config_path , model_path et task_desc , par exemple pour un modèle 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)'
Pour la formation et l'évaluation sur Kubric-4D et/ou ParallelDomain-4D, vous devez prétraiter les ensembles de données et stocker les nuages de points fusionnés. En effet, les ensembles de données eux-mêmes ne fournissent que des vidéos RVB-D de certains points de vue, mais nous souhaitons voler librement dans la scène 4D et permettre également l'apprentissage de commandes de caméra arbitraires (et d'interpolations de trajectoires).
Pour 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
Ici, /path/to/Kubric-4D/data doit être le dossier qui contient scn00000 , scn00001 , etc. Le script lira à partir data et écrira dans pcl/ (assurez-vous de disposer de 7,0 To d'espace libre).
Pour 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
Ici, /path/to/ParallelDomain-4D/data doit être le dossier qui contient scene_000000 , scene_000001 , etc. Le script lira depuis data/ et écrira dans pcl/ (assurez-vous de disposer de 4,4 To d'espace libre).
Les deux scripts de conversion ci-dessus s'appuient principalement sur des GPU pour un traitement rapide et peuvent appliquer la parallélisation au niveau du processus. Par exemple, --gpus=0,0,1,1 signifie générer 4 nœuds de calcul (2 par GPU). Pendant la formation, la plupart des E/S du disque seront concentrées dans le dossier pcl/ , je recommande donc de les stocker sur un SSD local rapide.
Si vous vous entraînez sur votre propre ensemble de données, je vous recommande de créer un nouveau chargeur de données en utilisant le code fourni comme référence. Si vous utilisez nos données, veuillez d'abord suivre la section Traitement des ensembles de données ci-dessus.
Tout d'abord, téléchargez l'un des deux points de contrôle de diffusion vidéo stable disponibles suivants : SVD (14 images) ou SVD-XT (25 images), et placez-le dans pretrained/ (ou mettez à jour le chemin du point de contrôle dans les fichiers de configuration référencés ci-dessous). Nous travaillons exclusivement avec la version à 14 images de SVD dans nos expériences en raison de contraintes de ressources, veuillez donc modifier les autres valeurs de configuration pertinentes si vous travaillez avec le SVD-XT à 25 images.
Pour démarrer une formation GCD sur Kubric-4D (progressive, max 90 degrés) :
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"
Pour passer à un modèle de synthèse en vue directe (sans interpolation), ajustez cette valeur : data.params.move_time=0 . Pour augmenter l'angle de rotation horizontale (azimut) maximum, sélectionnez l'autre fichier de configuration : train_kubric_max180.yaml .
Le modèle résultant sera capable d'effectuer une nouvelle synthèse de vue dynamique monoculaire 3-DoF sur n'importe quelle vidéo RVB, mais fonctionnera généralement mieux dans le domaine Kubric et d'autres vidéos ne contenant pas d'humains.
Pour démarrer une formation GCD sur ParallelDomain-4D (progressive, RVB) :
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"
Pour passer à un modèle de synthèse en vue directe (sans interpolation), ajustez cette valeur : data.params.move_time=0 . Pour changer la modalité de sortie en catégories sémantiques, sélectionnez l'autre fichier de configuration : train_pardom_semantic.yaml .
Le modèle résultant sera capable d'effectuer une nouvelle synthèse de vue dynamique monoculaire vers le haut sur n'importe quelle vidéo RVB, mais fonctionnera généralement mieux sur les scènes de conduite (à la fois synthétiques et réelles) enregistrées face vers l'avant au niveau de la rue. J'ai également des modèles internes qui sont capables d'effectuer des contrôles de caméra 3-DoF (transformations de l'ego vers le surround ainsi que du surround vers surround) sur cet ensemble de données, et bien qu'ils ne fassent pas partie des expériences de notre article, je pourrais présentez-les et/ou publiez-les ici à l’avenir.
Notez que dans toutes les commandes ci-dessus, l'index GPU 0 ( data.params.data_gpu ) est réservé à la construction de paires de vidéos (d'entrée, vérité terrain) à la volée pendant le chargement des données à partir des nuages de points fusionnés mis en cache dans pcl/ . Je recommande de ne pas entraîner le réseau sur le même GPU, c'est pourquoi lightning.trainer.devices est disjoint et couvre tous les GPU restants.
L'utilisation de la VRAM pour ceux-ci sera d'environ 50 Go par GPU dans les exemples fournis. Les trois principaux facteurs déterminants pour la VRAM sont : (1) la taille du lot, (2) la résolution spatiale ( frame_width et frame_height ), (3) le nombre d'images (SVD versus SVD-XT) et (4) si le poids EMA la moyenne est active. La plupart de nos expériences ont été réalisées sur des nœuds uniques avec des appareils 8x NVIDIA A100 ou 8x NVIDIA A6000, le tout sans EMA en raison d'un calcul limité.
Les journaux et les visualisations seront stockés dans un sous-dossier daté du dossier logs/ , qui réside au même niveau que gcd-model/ . Pour chaque exécution, les visualisations d'entraînement sont stockées dans le sous-dossier visuals/ . Si la formation est interrompue, vous pouvez reprendre en pointant --resume_from_checkpoint vers le dernier fichier de point de contrôle valide, par exemple --resume_from_checkpoint=../logs/2024-02-30T12-15-05_kb_v1/checkpoints/last.ckpt .
Le script suivant génère de nombreux types de résultats pour l'inspection et l'évaluation visuelles, et doit être adapté pour chaque référence. Pour des opérations plus légères, voir la section Inférence ci-dessus. Si vous utilisez nos données, assurez-vous d'abord d'avoir suivi la section Traitement des ensembles de données ci-dessus. Si vous évaluez votre propre ensemble de données personnalisé avec une vérité terrain, je vous recommande de créer un nouveau chargeur de données et de modifier le script de test ci-dessous.
Pour évaluer un modèle GCD affiné sur Kubric-4D , mettez à jour les chemins dans kubric_test20.txt et exécutez :
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
Par souci de cohérence et d'équité, cette commande applique un ensemble déterministe d'angles de caméra et de limites d'images associés à chaque scène, décrit dans kubric_valtest_controls_gradual.json . Ces nombres ont été générés aléatoirement une seule fois et sont ensuite restés fixes, mais de telle sorte que la perspective d'entrée (c'est-à-dire spherical_src ) soit alignée sur l'index de vue 4 dans l'ensemble de données. Remplacez ceci par kubric_valtest_controls_direct.json si vous évaluez un modèle de synthèse à vue directe. En outre, vous pouvez évaluer sur plusieurs échantillons en augmentant --num_samples (mêmes contrôles) ou en faisant varier --control_idx (différents contrôles par scène).
Pour évaluer un modèle GCD affiné sur ParallelDomain-4D , mettez à jour les chemins dans pardom_test20.txt et exécutez :
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
De la même manière que précédemment, toujours par souci de cohérence et d'équité, les signaux de contrôle pardom_valtest_controls.json ne contiennent que des limites de trame (c'est-à-dire le décalage et l'intervalle) pour chaque scène.
Dans tous les cas, pour l'argument --model_path , grep est appliqué pour gérer les caractères génériques de telle sorte que vous n'avez pas à vous soucier d'avoir à écrire des dates. Les images de vérité terrain correspondantes sont également restituées et stockées dans le dossier de sortie, permettant des évaluations numériques (voir Métriques ci-dessous).
Si vous souhaitez ignorer les contrôles JSON fournis et exécuter à la place une évaluation de manière plus libre avec les angles et les limites de cadre choisis dans 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
Dans ParallelDomain-4D, les six arguments liés à la pose ne sont pas applicables, mais les limites des images du clip vidéo peuvent toujours être choisies.
Le script test.py ci-dessus enregistre les fichiers *_metrics.json par scène dans le sous-dossier extra/ qui contiennent les numéros PSNR et SSIM globaux et par image. Il enregistre également toutes les images d'entrée individuelles, prédites et cibles sous forme d'images pour chaque exemple traité par le modèle. N'hésitez pas à utiliser ces différents résultats dans votre propre flux de travail d'évaluation quantitative si vous souhaitez calculer des mesures supplémentaires et/ou globales.
Comparé à la section principale d'évaluation , ce script ne dépend pas de la vérité terrain, qui peut ne pas exister. Par rapport à la section Inférence (Gradio) , ce script exporte plus d'informations et de visualisations.
Préparez un chemin direct vers un fichier vidéo ou un dossier d'images, ou une liste de fichiers vidéo ou de dossiers d'images (dans un fichier .txt avec des chemins complets), et exécutez :
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
Notez que --frame_rate doit refléter le FPS cible après le sous-échantillonnage temporel de la vidéo d'entrée, pas avant . Si vous souhaitez évaluer plusieurs exemples, je vous recommande d'utiliser une liste en définissant --input=/path/to/list.txt pour réduire la surcharge de chargement du modèle.
Si vous souhaitez utiliser exactement les mêmes données que dans nos expériences, veuillez consulter ce lien de téléchargement pour une description et des copies de Kubric-4D et ParallelDomain-4D. Le reste de cette section se concentre sur la question de savoir si vous souhaitez peaufiner notre pipeline et/ou générer vos propres données synthétiques.
Suivez ces instructions pour installer la bibliothèque OpenEXR. Ensuite, exécutez les commandes suivantes pour préparer votre environnement :
conda activate gcd
pip install bpy==3.4.0
pip install pybullet
pip install OpenEXR
cd data-gen/kubric/
pip install -e .
Le sous-dossier data-gen/kubric est en grande partie le même que ce commit du référentiel officiel Google Research Kubric, mais j'ai ajouté une correction de bug mineure pour éviter les conditions de concurrence lors de la gestion des cartes de profondeur.
Il s'agit de la commande que nous avons utilisée pour générer l'ensemble de données final Kubric-4D (notez la ligne 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
L'ensemble de données est essentiellement une variante de TCOW Kubric et comprend des améliorations telles que des objets plus dynamiques et un réalisme de masse accru. Voir le supplément TCOW pour plus de détails.
Pour les besoins de GCD, nous rendons 16 vidéos multi-vues synchronisées à partir de caméras statiques. Quatre points de vue se trouvent à une altitude élevée de 45 degrés et les douze autres points de vue se trouvent à une altitude faible de 5 degrés. Je recommande d'inspecter export_kub_mv.py pour mieux comprendre ses paramètres et sa logique.
Toutes les scènes sont générées iid, donc dans notre version de cet ensemble de données, nous définissons respectivement les 2800 premiers comme ensemble d'entraînement et les 100 + 100 derniers comme ensemble de validation + test. La boucle for externe efface régulièrement le dossier /tmp/ pour éviter les problèmes d'espace disque.
Cet ensemble de données provient d'un service et ne peut pas être régénéré. Veuillez consulter le lien de téléchargement pour notre copie.
Notez que certains dossiers de scènes n'existent pas (il y a 1531 dossiers de scènes mais l'index va jusqu'à 2143), et certaines scènes ont quelques images manquantes, c'est pourquoi notre chargeur de données est conçu pour être robuste aux deux problèmes. Vous pourriez voir quelques messages d’avertissement pendant l’entraînement, mais c’est normal. De plus, contrairement à Kubric, les scènes ne sont pas décorrélées par rapport à l'index, c'est pourquoi dans pardom_datasplit.json nous avons présélectionné des sous-ensembles aléatoires pour la formation, la validation et les tests.
Nous définissons la taille de l'ensemble de validation + test comme étant respectivement de 61 + 61 scènes (chacune représentant environ 4 % de l'ensemble de données total).
J'ai écrit quelques outils, basés sur TRI camviz, pour visualiser de manière interactive des exemples de scènes de Kubric-4D et ParallelDomain-4D sur votre ordinateur local. Je les publierai peut-être ici plus tard, mais n'hésitez pas à me contacter (Basile) en attendant pour le code source.
Si vous utilisez cette base de code dans votre travail (ou toute partie importante de celui-ci, comme les modifications nécessaires pour affiner SVD), veuillez citer notre article :
@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}
}
Je recommande également de citer l'article SVD original :
@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}
}
Si vous utilisez l'un de nos ensembles de données dans votre travail, veuillez également citer la source correspondante :
@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/}}
}
