gcd
1.0.0
Basile Van Hoorick, Rundi Wu, Ege Ozguroglu, Kyle Sargent, Ruoshi Liu, Pavel Tokmakov, Achal Dave, Changxi Zheng, Carl Vondrick
Universidad de Columbia, Universidad de Stanford, Instituto de Investigación Toyota
Publicado en ECCV 2024 (Oral)
Papel | Sitio web | Resultados | Conjuntos de datos | Modelos
Este repositorio contiene el código Python publicado como parte de nuestro artículo "Generative Camera Dolly: Extreme Monocular Dynamic Novel View Synthesis" (abreviado GCD ).
Proporcionamos instrucciones de configuración, modelos previamente entrenados, código de inferencia, código de entrenamiento, código de evaluación y generación de conjuntos de datos.
Tenga en cuenta que refactoricé y limpié el código base para su lanzamiento público, principalmente para simplificar la estructura y mejorar la legibilidad y la modularidad, pero aún no he examinado todo a fondo, así que si encuentra algún problema, háganoslo saber abriendo un problema. y siéntase libre de sugerir posibles correcciones de errores si tiene alguna.
Tabla de contenido:
Recomiendo configurar un entorno virtual e instalar los paquetes necesarios de la siguiente manera:
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
El proyecto se desarrolló principalmente con la versión 2.0.1 de PyTorch, sin embargo, debería funcionar también con versiones posteriores. En particular, hasta ahora no he experimentado problemas con PyTorch 2.3.1, que es la última versión al momento de escribir este artículo.
Tenga en cuenta que el archivo de requisitos no especifica las versiones de los paquetes, ya que soy un fanático de la flexibilidad (de lo contrario, agregar restricciones de versión haría que la adopción de bases de código existentes en sus nuevos proyectos sea más engorrosa). Sin embargo, si tiene algún problema, háganoslo saber abriendo un problema. También proporcioné las versiones exactas en requirements_versions.txt para su referencia.
La subcarpeta gcd-model se basa originalmente en el repositorio oficial de modelos generativos de Stability AI.
A continuación se muestran los principales puntos de control de Kubric-4D que entrenamos y utilizamos en nuestros experimentos, junto con los valores de PSNR en el conjunto de prueba. La columna de la izquierda indica el desplazamiento máximo de la cámara en términos de rotación horizontal.
| Azimut | Gradual | Directo |
|---|---|---|
| Máximo 90 grados | Enlace (17,88 dB) | Enlace (17,23 dB) |
| Máximo 180 grados | Enlace (17,81 dB) | Enlace (16,65 dB) |
A continuación se muestran los principales puntos de control de ParallelDomain-4D que entrenamos y utilizamos en nuestros experimentos, junto con los valores de PSNR o mIoU en el conjunto de prueba. La columna de la izquierda indica la modalidad de salida prevista (la entrada siempre es RGB).
| Modalidad | Gradual | Directo |
|---|---|---|
| Color (RGB) | Enlace (23,47 dB) | Enlace (23,32 dB) |
| Semántico | Enlace (39,0%) | Enlace (36,7%) |
Todos los puntos de control anteriores tienen un tamaño de 20,3 GB. Colóquelos en pretrained/ de modo que tengan el mismo nombre que los archivos de configuración .yaml correspondientes.
Esta sección es para ejecutar nuestro modelo de manera casual en videos personalizados. Para una evaluación cuantitativa exhaustiva en Kubric-4D o ParallelDomain-4D, o cualquier inferencia de línea de comando fuera de esos dos conjuntos de datos que guarde resultados y visualizaciones en su disco, consulte la sección Evaluación a continuación.
Para un modelo Kubric-4D , ejecute:
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'
Para probar otros modelos, simplemente cambie config_path , model_path y task_desc , por ejemplo para un modelo 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)'
Para la capacitación y evaluación en Kubric-4D y/o ParallelDomain-4D, debe preprocesar los conjuntos de datos y almacenar nubes de puntos fusionadas. Esto se debe a que los conjuntos de datos en sí solo proporcionan videos RGB-D desde ciertos puntos de vista, pero deseamos volar libremente en la escena 4D y permitir también aprender controles de cámara arbitrarios (e interpolar trayectorias).
Para 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
Aquí, /path/to/Kubric-4D/data debe ser la carpeta que contiene scn00000 , scn00001 , etc. El script leerá los data y escribirá en pcl/ (asegúrese de tener 7,0 TB de espacio libre).
Para 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
Aquí, /path/to/ParallelDomain-4D/data debe ser la carpeta que contiene scene_000000 , scene_000001 , etc. El script leerá data/ y escribirá en pcl/ (asegúrese de tener 4,4 TB de espacio libre).
Los dos scripts de conversión anteriores se basan principalmente en GPU para un procesamiento rápido y pueden aplicar paralelización a nivel de proceso. Por ejemplo, --gpus=0,0,1,1 significa generar 4 trabajadores (2 por GPU). Durante el entrenamiento, la mayor parte de las E/S del disco se concentrarán en la carpeta pcl/ , por lo que recomiendo almacenarlas en un SSD local rápido.
Si está entrenando con su propio conjunto de datos, le recomiendo crear un nuevo cargador de datos utilizando el código proporcionado como referencia. Si está utilizando nuestros datos, primero siga la sección Procesamiento de conjuntos de datos anterior.
Primero, descargue uno de los dos siguientes puntos de control de difusión de video estable disponibles: SVD (14 fotogramas) o SVD-XT (25 fotogramas) y colóquelo en pretrained/ (o actualice la ruta del punto de control en los archivos de configuración a los que se hace referencia a continuación). Trabajamos exclusivamente con la versión de 14 fotogramas de SVD en nuestros experimentos debido a limitaciones de recursos, así que cambie los demás valores de configuración relevantes si está trabajando con el SVD-XT de 25 fotogramas.
Para iniciar una ejecución de entrenamiento de GCD en Kubric-4D (gradual, máximo 90 grados):
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"
Para cambiar a un modelo de síntesis de vista directa (sin interpolación), ajuste este valor: data.params.move_time=0 . Para aumentar el ángulo máximo de rotación horizontal (azimut), seleccione el otro archivo de configuración: train_kubric_max180.yaml .
El modelo resultante podrá realizar una síntesis de vista novedosa dinámica monocular de 3 DoF en cualquier vídeo RGB, pero normalmente funcionará mejor dentro del dominio de Kubric y otros vídeos que no contengan humanos.
Para iniciar una ejecución de entrenamiento de GCD en ParallelDomain-4D (gradual, 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"
Para cambiar a un modelo de síntesis de vista directa (sin interpolación), ajuste este valor: data.params.move_time=0 . Para cambiar la modalidad de salida a categorías semánticas, seleccione el otro archivo de configuración: train_pardom_semantic.yaml .
El modelo resultante podrá realizar una síntesis de vista novedosa dinámica monocular hacia arriba en cualquier vídeo RGB, pero normalmente funcionará mejor en escenas de conducción (tanto sintéticas como reales) grabadas mirando hacia adelante al nivel de la calle. También tengo modelos internos por ahí que son capaces de realizar controles de cámara de 3 DoF (transformaciones de ego a envolvente y de envolvente a envolvente) en este conjunto de datos, y aunque no forman parte de los experimentos de nuestro artículo, podría mostrarlos y/o publicarlos aquí en el futuro.
Tenga en cuenta que en todos los comandos anteriores, el índice de GPU 0 ( data.params.data_gpu ) está reservado para construir pares de videos (de entrada, reales) sobre la marcha durante la carga de datos desde las nubes de puntos fusionadas almacenadas en caché en pcl/ . Recomiendo no entrenar la red en la misma GPU, razón por la cual lightning.trainer.devices está separado y cubre todas las GPU restantes.
El uso de VRAM para estos será de alrededor de 50 GB por GPU en los ejemplos proporcionados. Los tres factores determinantes más importantes para VRAM son: (1) el tamaño del lote, (2) la resolución espacial ( frame_width y frame_height ), (3) el número de fotogramas (SVD versus SVD-XT) y (4) si el peso de EMA el promedio está activo. La mayoría de nuestros experimentos se realizaron en nodos únicos con dispositivos 8x NVIDIA A100 u 8x NVIDIA A6000, todos sin EMA debido a la computación limitada.
Los registros y visualizaciones se almacenarán en una subcarpeta con fecha dentro de la carpeta logs/ , que reside en el mismo nivel que gcd-model/ . Para cada ejecución, las visualizaciones de entrenamiento se almacenan en la subcarpeta visuals/ . Si alguna vez se interrumpe el entrenamiento, puede reanudarlo señalando --resume_from_checkpoint al último archivo de punto de control válido, por ejemplo --resume_from_checkpoint=../logs/2024-02-30T12-15-05_kb_v1/checkpoints/last.ckpt .
El siguiente script genera muchos tipos de resultados para la inspección y evaluación visual y debe adaptarse para cada punto de referencia. Para operaciones más ligeras, consulte la sección Inferencia anterior. Si está utilizando nuestros datos, asegúrese de haber seguido primero la sección Procesamiento del conjunto de datos anterior. Si está evaluando su propio conjunto de datos personalizado con datos reales, le recomiendo crear un nuevo cargador de datos y modificar el script de prueba a continuación.
Para evaluar un modelo ajustado de GCD en Kubric-4D , actualice las rutas en kubric_test20.txt y ejecute:
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
Para lograr coherencia y equidad, este comando aplica un conjunto determinista de ángulos de cámara y límites de fotograma asociados con cada escena, descrito en kubric_valtest_controls_gradual.json . Estos números se generaron aleatoriamente solo una vez y posteriormente se mantuvieron fijos, pero de manera que la perspectiva de entrada (es decir, spherical_src ) esté alineada con el índice de vista 4 en el conjunto de datos. Cambie esto a kubric_valtest_controls_direct.json si está evaluando un modelo de síntesis de vista directa. Además, puede evaluar varias muestras aumentando --num_samples (mismos controles) o variando --control_idx (diferentes controles por escena).
Para evaluar un modelo ajustado de GCD en ParallelDomain-4D , actualice las rutas en pardom_test20.txt y ejecute:
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 manera similar a antes, nuevamente por coherencia y equidad, las señales de control pardom_valtest_controls.json solo contienen límites de fotograma (es decir, desplazamiento e intervalo) para cada escena.
En todos los casos, para el argumento --model_path , se aplica grep para tratar con comodines, de modo que no tenga que preocuparse por tener que escribir fechas. Los marcos de verdad sobre el terreno correspondientes también se procesan y almacenan en la carpeta de salida, lo que permite evaluaciones numéricas (consulte Métricas a continuación).
Si desea ignorar los controles JSON proporcionados y, en su lugar, ejecutar la evaluación de forma más libre con ángulos y límites de fotograma elegidos en 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
En ParallelDomain-4D, los seis argumentos relacionados con la pose no son aplicables, pero aún se pueden elegir los límites de los fotogramas del videoclip.
El script test.py anterior guarda archivos *_metrics.json por escena en la subcarpeta extra/ que contiene números PSNR y SSIM generales y por cuadro. También guarda todos los fotogramas de entrada, previstos y de destino individuales como imágenes para cada ejemplo procesado por el modelo. Siéntase libre de utilizar estos diversos resultados en su propio flujo de trabajo de evaluación cuantitativa si desea calcular métricas adicionales y/o agregadas.
En comparación con la sección principal de Evaluación , este script no depende de la verdad básica, que puede no existir. En comparación con la sección Inferencia (Gradio) , este script exporta más información y visualizaciones.
Prepare una ruta directa a un archivo de video o una carpeta de imágenes, o una lista de archivos de video o carpetas de imágenes (en un archivo .txt con rutas completas) y ejecute:
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
Tenga en cuenta que --frame_rate debe reflejar el FPS objetivo después del submuestreo temporal del vídeo de entrada, no antes . Si desea evaluar varios ejemplos, le recomiendo usar una lista configurando --input=/path/to/list.txt para reducir la sobrecarga de carga del modelo.
Si desea utilizar exactamente los mismos datos que en nuestros experimentos, consulte este enlace de descarga para obtener una descripción y copias de Kubric-4D y ParallelDomain-4D. El resto de esta sección se centra en si desea modificar nuestro canal y/o generar sus propios datos sintéticos.
Siga estas instrucciones para instalar la biblioteca OpenEXR. Luego, ejecute los siguientes comandos para preparar su entorno:
conda activate gcd
pip install bpy==3.4.0
pip install pybullet
pip install OpenEXR
cd data-gen/kubric/
pip install -e .
La subcarpeta data-gen/kubric es en gran medida la misma que esta confirmación del repositorio oficial de Kubric de Google Research, pero agregué una corrección de error menor para evitar condiciones de carrera al manejar mapas de profundidad.
Este es el comando que utilizamos para generar el conjunto de datos final de Kubric-4D (tenga en cuenta la línea 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
El conjunto de datos es básicamente una variación de TCOW Kubric e incluye mejoras como objetos más dinámicos y mayor realismo masivo. Consulte el suplemento de TCOW para obtener más detalles.
Para propósitos de GCD, renderizamos 16 videos sincronizados de múltiples vistas desde cámaras estáticas. Cuatro miradores están a una altura de 45 grados y los otros doce miradores están a una altura baja de 5 grados. Recomiendo inspeccionar export_kub_mv.py para obtener más información sobre sus parámetros y lógica.
Todas las escenas se generan iid, por lo que en nuestra versión de este conjunto de datos, definimos los primeros 2800 como conjunto de entrenamiento y los últimos 100 + 100 como conjunto de validación + prueba, respectivamente. El bucle for externo limpia periódicamente la carpeta /tmp/ para evitar problemas de espacio en disco.
Este conjunto de datos proviene de un servicio y no se puede regenerar. Consulte el enlace de descarga para nuestra copia.
Tenga en cuenta que algunas carpetas de escenas no existen (hay 1531 carpetas de escenas pero el índice llega a 2143) y a algunas escenas les faltan un par de cuadros, razón por la cual nuestro cargador de datos está diseñado para ser sólido para ambos problemas. Es posible que veas algunos mensajes de advertencia durante el entrenamiento, pero esto es normal. Además, a diferencia de Kubric, las escenas no están correlacionadas con respecto al índice, por lo que en pardom_datasplit.json preseleccionamos subconjuntos aleatorios para entrenamiento, validación y prueba.
Definimos los tamaños del conjunto de validación + prueba como 61 + 61 escenas respectivamente (cada una aproximadamente el 4% del conjunto de datos total).
He escrito algunas herramientas, basadas en TRI camviz, para visualizar interactivamente escenas de ejemplo de Kubric-4D y ParallelDomain-4D en su computadora local. Puede que los publique aquí más tarde, pero no dude en ponerse en contacto conmigo (Basile) mientras tanto para obtener el código fuente.
Si utiliza este código base en su trabajo (o cualquier parte importante del mismo, como los cambios necesarios para ajustar SVD), cite nuestro documento:
@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}
}
Recomiendo citar también el artículo original de 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}
}
Si utiliza uno de nuestros conjuntos de datos en su trabajo, cite también la fuente respectiva:
@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/}}
}
