gcd
1.0.0
Basile Van Hoorick, Rundi Wu, Ege Ozguroglu, Kyle Sargent, Ruoshi Liu, Pavel Tokmakov, Achal Dave, Changxi Zheng, Carl Vondrick
Universidade de Columbia, Universidade de Stanford, Instituto de Pesquisa Toyota
Publicado em ECCV 2024 (Oral)
Papel | Site | Resultados | Conjuntos de dados | Modelos
Este repositório contém o código Python publicado como parte de nosso artigo "Generative Camera Dolly: Extreme Monocular Dynamic Novel View Synthesis" (abreviado GCD ).
Fornecemos instruções de configuração, modelos pré-treinados, código de inferência, código de treinamento, código de avaliação e geração de conjunto de dados.
Observe que refatorei e limpei a base de código para lançamento público, principalmente para simplificar a estrutura, bem como melhorar a legibilidade e a modularidade, mas ainda não verifiquei tudo completamente, portanto, se você encontrar algum problema, informe-nos abrindo um problema e fique à vontade para sugerir possíveis correções de bugs, se houver alguma.
Índice:
Recomendo configurar um ambiente virtual e instalar os pacotes necessários da seguinte forma:
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
O projeto foi desenvolvido principalmente com PyTorch versão 2.0.1, porém, deve funcionar também com versões posteriores. Em particular, não tive problemas até agora com o PyTorch 2.3.1, que é a versão mais recente no momento em que este artigo foi escrito.
Observe que o arquivo de requisitos não especifica versões de pacotes, já que sou um fã de flexibilidade (adicionar restrições de versão tornaria mais complicada a adoção de bases de código existentes em seus novos projetos). No entanto, se você tiver algum problema, informe-nos abrindo um problema. Também forneci as versões exatas em requirements_versions.txt para sua referência.
A subpasta gcd-model é originalmente baseada no repositório oficial de modelos generativos Stability AI.
Abaixo estão os principais pontos de verificação do Kubric-4D que treinamos e usamos em nossos experimentos, junto com os valores PSNR no conjunto de teste. A coluna da esquerda indica o deslocamento máximo da câmera em termos de rotação horizontal.
| Azimute | Gradual | Direto |
|---|---|---|
| Máx. 90 graus | Ligação (17,88dB) | Ligação (17,23dB) |
| Máx. 180 graus | Ligação (17,81dB) | Ligação (16,65dB) |
Abaixo estão os principais pontos de verificação do ParallelDomain-4D que treinamos e usamos em nossos experimentos, junto com os valores PSNR ou mIoU no conjunto de teste. A coluna da esquerda indica a modalidade de saída prevista (a entrada é sempre RGB).
| Modalidade | Gradual | Direto |
|---|---|---|
| Cor (RGB) | Ligação (23,47dB) | Ligação (23,32dB) |
| Semântica | Ligação (39,0%) | Ligação (36,7%) |
Todos os pontos de verificação acima têm 20,3 GB de tamanho. Coloque-os em pretrained/ de modo que tenham o mesmo nome dos arquivos .yaml de configuração correspondentes.
Esta seção é para executar casualmente nosso modelo em vídeos personalizados. Para uma avaliação quantitativa completa em Kubric-4D ou ParallelDomain-4D, ou qualquer inferência de linha de comando fora desses dois conjuntos de dados que salva resultados e visualizações em seu disco, consulte a seção Avaliação abaixo.
Para um modelo Kubric-4D , execute:
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 experimentar outros modelos, basta alterar config_path , model_path e task_desc , por exemplo, para um 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 treinamento e avaliação em Kubric-4D e/ou ParallelDomain-4D, você precisa pré-processar os conjuntos de dados e armazenar nuvens de pontos mescladas. Isso ocorre porque os próprios conjuntos de dados fornecem apenas vídeos RGB-D de determinados pontos de vista, mas desejamos voar livremente na cena 4D e permitir o aprendizado de controles arbitrários de câmera (e interpolação de trajetórias) também.
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
Aqui, /path/to/Kubric-4D/data deve ser a pasta que contém scn00000 , scn00001 e assim por diante. O script lerá os data e gravará em pcl/ (certifique-se de ter 7,0 TB de espaço livre).
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
Aqui, /path/to/ParallelDomain-4D/data deve ser a pasta que contém scene_000000 , scene_000001 e assim por diante. O script irá ler data/ e gravar em pcl/ (certifique-se de ter 4,4 TB de espaço livre).
Ambos os scripts de conversão acima dependem principalmente de GPUs para processamento rápido e podem aplicar paralelização no nível do processo. Por exemplo, --gpus=0,0,1,1 significa gerar 4 trabalhadores (2 por GPU). Durante o treinamento, a maior parte da E/S do disco estará concentrada na pasta pcl/ , portanto, recomendo armazená-la em um SSD local rápido.
Se você estiver treinando em seu próprio conjunto de dados, recomendo criar um novo carregador de dados usando o código fornecido como referência. Se você estiver usando nossos dados, siga primeiro a seção Processamento de conjunto de dados acima.
Primeiro, baixe um dos dois seguintes pontos de verificação de difusão de vídeo estável disponíveis: SVD (14 quadros) ou SVD-XT (25 quadros) e coloque-o em pretrained/ (ou atualize o caminho do ponto de verificação nos arquivos de configuração mencionados abaixo). Trabalhamos exclusivamente com a versão de 14 quadros do SVD em nossos experimentos devido a restrições de recursos, portanto, altere os outros valores de configuração relevantes se estiver trabalhando com o SVD-XT de 25 quadros.
Para iniciar um treinamento GCD no Kubric-4D (gradual, máximo 90 graus):
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 mudar para um modelo de síntese de visualização direta (sem interpolação), ajuste este valor: data.params.move_time=0 . Para aumentar o ângulo máximo de rotação horizontal (azimute), selecione o outro arquivo de configuração: train_kubric_max180.yaml .
O modelo resultante será capaz de realizar síntese de nova visão dinâmica monocular 3-DoF em qualquer vídeo RGB, mas normalmente terá melhor desempenho no domínio Kubric e outros vídeos que não contêm humanos.
Para iniciar um treinamento GCD, execute em 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 mudar para um modelo de síntese de visualização direta (sem interpolação), ajuste este valor: data.params.move_time=0 . Para alterar a modalidade de saída para categorias semânticas, selecione o outro arquivo de configuração: train_pardom_semantic.yaml .
O modelo resultante será capaz de realizar uma nova síntese de visão dinâmica monocular ascendente em qualquer vídeo RGB, mas normalmente terá melhor desempenho em cenas de direção (sintéticas e reais) gravadas voltadas para a frente no nível da rua. Eu também tenho modelos internos que são capazes de controles de câmera 3-DoF (transformações ego-para-surround e surround-para-surround) neste conjunto de dados e, embora não façam parte dos experimentos em nosso artigo, eu poderia mostre e/ou divulgue-os aqui no futuro.
Observe que em todos os comandos acima, o índice GPU 0 ( data.params.data_gpu ) é reservado para a construção de pares de vídeos (entrada, verdade) em tempo real durante o carregamento de dados das nuvens de pontos mescladas em cache em pcl/ . Eu recomendo não treinar a rede na mesma GPU, e é por isso que lightning.trainer.devices é desarticulado e cobre todas as GPUs restantes.
O uso de VRAM para eles será de cerca de 50 GB por GPU nos exemplos fornecidos. Os três maiores fatores determinantes para VRAM são: (1) o tamanho do lote, (2) a resolução espacial ( frame_width e frame_height ), (3) o número de quadros (SVD versus SVD-XT) e (4) se o peso do EMA a média está ativa. A maioria de nossos experimentos foi realizada em nós únicos com 8 dispositivos NVIDIA A100 ou 8 dispositivos NVIDIA A6000, todos sem EMA devido à computação limitada.
Os registros e visualizações serão armazenados em uma subpasta datada dentro da pasta logs/ , que reside no mesmo nível que gcd-model/ . Para cada execução, as visualizações de treinamento são armazenadas na subpasta visuals/ . Se o treinamento for interrompido, você pode continuar apontando --resume_from_checkpoint para o último arquivo de checkpoint válido, por exemplo --resume_from_checkpoint=../logs/2024-02-30T12-15-05_kb_v1/checkpoints/last.ckpt .
O script a seguir gera muitos tipos de resultados para inspeção e avaliação visual e deve ser adaptado para cada benchmark. Para operações mais leves, consulte a seção Inferência acima. Se você estiver usando nossos dados, certifique-se de seguir primeiro a seção Processamento de conjunto de dados acima. Se você estiver avaliando seu próprio conjunto de dados personalizado com base na verdade, recomendo criar um novo carregador de dados e modificar o script de teste abaixo.
Para avaliar um modelo ajustado de GCD em Kubric-4D , atualize os caminhos em kubric_test20.txt e execute:
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 consistência e justiça, este comando aplica um conjunto determinístico de ângulos de câmera e limites de quadro associados a cada cena, descrito em kubric_valtest_controls_gradual.json . Esses números foram gerados aleatoriamente apenas uma vez e posteriormente mantidos fixos, mas de forma que a perspectiva de entrada (ou seja, spherical_src ) esteja alinhada com o índice de visualização 4 no conjunto de dados. Altere para kubric_valtest_controls_direct.json se estiver avaliando um modelo de síntese de visualização direta. Além disso, você pode avaliar várias amostras aumentando --num_samples (mesmos controles) ou variando --control_idx (diferentes controles por cena).
Para avaliar um modelo ajustado GCD em ParallelDomain-4D , atualize os caminhos em pardom_test20.txt e execute:
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
Da mesma forma que antes, novamente para consistência e justiça, os sinais de controle pardom_valtest_controls.json contêm apenas limites de quadro (ou seja, deslocamento e intervalo) para cada cena.
Em todos os casos, para o argumento --model_path , grep é aplicado para lidar com curingas de forma que você não precise se preocupar em escrever datas. Os quadros de verdade correspondentes também são renderizados e armazenados na pasta de saída, permitindo avaliações numéricas (consulte Métricas abaixo).
Se você deseja ignorar os controles JSON fornecidos e, em vez disso, executar a avaliação de maneira mais livre com ângulos e limites de quadro escolhidos no 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
No ParallelDomain-4D, os seis argumentos relacionados à pose não são aplicáveis, mas os limites do quadro do videoclipe ainda podem ser escolhidos.
O script test.py acima salva arquivos *_metrics.json por cena na subpasta extra/ que contém números PSNR e SSIM gerais e por quadro. Ele também salva todos os quadros de entrada, previstos e de destino individuais como imagens para cada exemplo processado pelo modelo. Sinta-se à vontade para usar esses vários resultados em seu próprio fluxo de trabalho de avaliação quantitativa se desejar calcular métricas adicionais e/ou agregadas.
Comparado com a seção principal de Avaliação , este roteiro não depende de informações básicas, que podem não existir. Comparado à seção Inferência (Gradio) , este script exporta mais informações e visualizações.
Prepare um caminho direto para um arquivo de vídeo ou pasta de imagem, ou uma lista de arquivos de vídeo ou pastas de imagem (em um arquivo .txt com caminhos completos) e execute:
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
Observe que --frame_rate deve refletir o FPS alvo após a subamostragem temporal do vídeo de entrada, não antes . Se você quiser avaliar vários exemplos, recomendo usar uma lista definindo --input=/path/to/list.txt para reduzir a sobrecarga de carregamento do modelo.
Se você quiser usar exatamente os mesmos dados de nossos experimentos, consulte este link de download para obter uma descrição e cópias de Kubric-4D e ParallelDomain-4D. O restante desta seção se concentra em saber se você deseja ajustar nosso pipeline e/ou gerar seus próprios dados sintéticos.
Siga estas instruções para instalar a biblioteca OpenEXR. Em seguida, execute os seguintes comandos para preparar seu ambiente:
conda activate gcd
pip install bpy==3.4.0
pip install pybullet
pip install OpenEXR
cd data-gen/kubric/
pip install -e .
A subpasta data-gen/kubric é basicamente a mesma deste commit do repositório oficial do Google Research Kubric, mas adicionei uma pequena correção de bug para evitar condições de corrida ao lidar com mapas de profundidade.
Este é o comando que usamos para gerar o conjunto de dados final do Kubric-4D (observe a linha 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
O conjunto de dados é basicamente uma variação do TCOW Kubric e inclui melhorias como objetos mais dinâmicos e maior realismo de massa. Consulte o suplemento do TCOW para obter detalhes.
Para fins de GCD, renderizamos 16 vídeos multivisualização sincronizados de câmeras estáticas. Quatro pontos de vista estão a uma altitude elevada de 45 graus, e os outros doze pontos de vista estão a uma elevação baixa de 5 graus. Eu recomendo inspecionar export_kub_mv.py para obter mais informações sobre seus parâmetros e lógica.
Todas as cenas são geradas iid, portanto, em nossa versão deste conjunto de dados, definimos os primeiros 2.800 como o conjunto de treinamento e os últimos 100 + 100 como validação + conjunto de teste, respectivamente. O loop for externo limpa regularmente a pasta /tmp/ para evitar problemas de espaço em disco.
Este conjunto de dados vem de um serviço e não pode ser regenerado. Por favor, veja o link para download de nossa cópia.
Observe que algumas pastas de cenas não existem (existem 1.531 pastas de cenas, mas o índice sobe para 2.143), e algumas cenas têm alguns quadros faltando, e é por isso que nosso dataloader foi projetado para ser robusto para ambos os problemas. Você poderá ver algumas mensagens de aviso durante o treinamento, mas isso é normal. Além disso, ao contrário do Kubric, as cenas não são descorrelacionadas em relação ao índice, portanto, em pardom_datasplit.json pré-selecionamos subconjuntos aleatórios para treinamento, validação e teste.
Definimos os tamanhos do conjunto de validação + teste como 61 + 61 cenas, respectivamente (cada um aproximadamente 4% do conjunto de dados total).
Eu escrevi algumas ferramentas, baseadas no TRI camviz, para visualizar interativamente cenas de exemplo do Kubric-4D e ParallelDomain-4D em seu computador local. Posso divulgá-los aqui mais tarde, mas sinta-se à vontade para entrar em contato comigo (Basile) enquanto isso para obter o código-fonte.
Se você usar esta base de código em seu trabalho (ou qualquer parte significativa dela, como as alterações necessárias para ajustar o SVD), cite nosso artigo:
@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}
}
Recomendo também citar o artigo 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}
}
Se você usar um de nossos conjuntos de dados em seu trabalho, cite também a respectiva fonte:
@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/}}
}
