gcd
1.0.0
Бэзил Ван Хурик, Рунди Ву, Эге Озгуроглу, Кайл Сарджент, Руоши Лю, Павел Токмаков, Ачал Дэйв, Чанси Чжэн, Карл Вондрик
Колумбийский университет, Стэнфордский университет, Научно-исследовательский институт Тойота
Опубликовано в ECCV 2024 (устно)
Бумага | Веб-сайт | Результаты | Наборы данных | Модели
Этот репозиторий содержит код Python, опубликованный как часть нашей статьи «Генеративная камера Dolly: синтез экстремального монокулярного динамического нового вида» (сокращенно GCD ).
Мы предоставляем инструкции по настройке, предварительно обученные модели, код вывода, код обучения, код оценки и генерацию набора данных.
Обратите внимание, что я провел рефакторинг и очистку кодовой базы для публичного выпуска, в основном для упрощения структуры, а также улучшения читаемости и модульности, но я еще не все тщательно проверил, поэтому, если у вас возникнут какие-либо проблемы, сообщите нам об этом, открыв проблему. и не стесняйтесь предлагать возможные исправления ошибок, если они у вас есть.
Оглавление:
Я рекомендую настроить виртуальную среду и установить необходимые пакеты следующим образом:
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 ГБ. Поместите их в каталог pretrained/ так, чтобы они имели то же имя, что и соответствующие файлы конфигурации .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-сцене и позволять также изучать произвольные элементы управления камерой (и интерполировать траектории).
Для Кубрик-4Д :
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 ТБ свободного места).
Для 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 ТБ свободного места).
Оба приведенных выше сценария преобразования в основном полагаются на графические процессоры для быстрой обработки и могут применять распараллеливание на уровне процесса. Например, --gpus=0,0,1,1 означает создание 4 рабочих процессов (по 2 на каждый графический процессор). Во время обучения большая часть дискового ввода-вывода будет сосредоточена в папке pcl/ , поэтому я рекомендую хранить ее на быстром локальном SSD.
Если вы обучаетесь на собственном наборе данных, я рекомендую создать новый загрузчик данных, используя предоставленный код в качестве образца. Если вы используете наши данные, сначала следуйте разделу «Обработка набора данных» выше.
Сначала загрузите одну из двух доступных контрольных точек Stable Video Diffusion: SVD (14 кадров) или SVD-XT (25 кадров) и поместите ее в pretrained/ (или обновите путь контрольной точки в файлах конфигурации, указанных ниже). В наших экспериментах мы работаем исключительно с 14-кадровой версией SVD из-за ограниченности ресурсов, поэтому измените другие соответствующие значения конфигурации, если вы работаете с 25-кадровой версией SVD-XT.
Чтобы начать тренировочный прогон GCD на Kubric-4D (постепенный, максимум 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 .
Полученная модель сможет выполнять синтез монокулярного динамического нового вида с 3 степенями свободы на любом видео RGB, но, как правило, лучше всего работает в домене Кубрика и других видео, которые не содержат людей.
Чтобы начать обучение GCD на ParallelDomain-4D (постепенный, 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 степенями свободы (эго-объем, а также преобразования объемного звука) в этом наборе данных, и хотя они не являются частью экспериментов в нашей статье, я мог бы продемонстрировать и/или опубликовать их здесь в будущем.
Обратите внимание, что во всех приведенных выше командах индекс графического процессора 0 ( data.params.data_gpu ) зарезервирован для создания пар видео (вход, достоверность) «на лету» во время загрузки данных из кэшированных объединенных облаков точек в pcl/ . Я рекомендую не обучать сеть на одном и том же графическом процессоре, поэтому lightning.trainer.devices не пересекается и вместо этого охватывает все оставшиеся графические процессоры.
В приведенных примерах использование VRAM для них составит около 50 ГБ на графический процессор. Тремя крупнейшими определяющими факторами для 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 .
Следующий сценарий генерирует множество типов выходных данных для визуального контроля и оценки, и его необходимо адаптировать для каждого теста. Более простые операции см. в разделе «Вывод» выше. Если вы используете наши данные, сначала убедитесь, что вы следовали разделу «Обработка набора данных» выше. Если вы оцениваете свой собственный набор данных с достоверностью, я рекомендую создать новый загрузчик данных и изменить приведенный ниже тестовый сценарий.
Чтобы оценить настроенную модель GCD на Kubric-4D , обновите пути в 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 (разные элементы управления для каждой сцены).
Чтобы оценить настроенную модель GCD в ParallelDomain-4D , обновите пути в 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), а в некоторых сценах отсутствует пара кадров, поэтому наш загрузчик данных разработан так, чтобы быть устойчивым к обеим проблемам. Во время тренировки вы можете увидеть несколько предупреждающих сообщений, но это нормально. Кроме того, в отличие от Кубрика, сцены не декоррелированы по индексу, поэтому в pardom_datasplit.json мы заранее выбрали случайные подмножества для обучения, проверки и тестирования.
Мы определяем размеры набора для проверки и тестирования как 61 + 61 сцена соответственно (каждая примерно 4% от общего набора данных).
Я написал несколько инструментов на основе TRI camviz для интерактивной визуализации примеров сцен из Kubric-4D и ParallelDomain-4D на вашем локальном компьютере. Возможно, я опубликую их здесь позже, но тем временем не стесняйтесь обращаться ко мне (Базилю) за исходным кодом.
Если вы используете эту кодовую базу в своей работе (или любую ее значительную часть, например, изменения, необходимые для точной настройки 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/}}
}
