gcd
1.0.0
Basile Van Hoorick, Rundi Wu, Ege Ozguroglu, Kyle Sargent, Ruoshi Liu, Pavel Tokmakov, Achal Dave, Changxi Zheng, Carl Vondrick
컬럼비아 대학교, 스탠포드 대학교, 도요타 연구소
ECCV 2024에 게시됨(구두)
종이 | 웹사이트 | 결과 | 데이터세트 | 모델
이 저장소에는 "Generative Camera Dolly: Extreme Monocular Dynamic Novel View Synesis" (약어로 GCD )라는 논문의 일부로 게시된 Python 코드가 포함되어 있습니다.
우리는 설정 지침, 사전 훈련된 모델, 추론 코드, 훈련 코드, 평가 코드 및 데이터 세트 생성을 제공합니다.
구조를 단순화하고 가독성과 모듈성을 높이기 위해 공개 릴리스를 위해 코드베이스를 리팩토링하고 정리했습니다. 하지만 아직 모든 것을 철저하게 조사하지는 않았으므로 문제가 발생하면 문제를 열어 알려주시기 바랍니다. , 가능한 버그 수정 사항이 있으면 언제든지 제안해 주세요.
목차:
다음과 같이 가상 환경을 설정하고 필요한 패키지를 설치하는 것이 좋습니다.
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 생성 모델 저장소를 기반으로 합니다.
다음은 테스트 세트의 PSNR 값과 함께 실험에서 훈련하고 사용한 주요 Kubric-4D 체크포인트입니다. 왼쪽 열은 수평 회전 측면에서 카메라의 최대 변위를 나타냅니다.
| 방위각 | 점진적 | 직접 |
|---|---|---|
| 최대 90도 | 링크(17.88dB) | 링크(17.23dB) |
| 최대 180도 | 링크(17.81dB) | 링크(16.65dB) |
다음은 테스트 세트의 PSNR 또는 mIoU 값과 함께 실험에서 훈련하고 사용한 주요 ParallelDomain-4D 체크포인트입니다. 왼쪽 열은 예측된 출력 양식을 나타냅니다(입력은 항상 RGB임).
| 양식 | 점진적 | 직접 |
|---|---|---|
| 색상(RGB) | 링크(23.47dB) | 링크(23.32dB) |
| 의미론적 | 링크 (39.0%) | 링크 (36.7%) |
위 체크포인트의 크기는 모두 20.3GB입니다. 해당 구성 .yaml 파일과 동일한 이름을 갖도록 pretrained/ 에 배치합니다.
이 섹션은 사용자 정의 비디오에서 모델을 자연스럽게 실행하기 위한 것입니다. 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'
다른 모델을 시험해 보려면 ParallelDomain-4D 모델의 경우 config_path , model_path 및 task_desc 변경하기만 하면 됩니다.
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 장면에서 자유롭게 날아다니면서 임의의 카메라 제어(및 궤적 보간)도 학습할 수 있기를 원하기 때문입니다.
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
여기서 /path/to/Kubric-4D/data scn00000 , scn00001 등이 포함된 폴더여야 합니다. 스크립트는 data 를 읽고 pcl/ 에 씁니다(7.0TB의 여유 공간이 있는지 확인).
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.4TB의 여유 공간이 있는지 확인).
위의 두 변환 스크립트는 주로 빠른 처리를 위해 GPU에 의존하며 프로세스 수준에서 병렬화를 적용할 수 있습니다. 예를 들어 --gpus=0,0,1,1 작업자 4개(GPU당 2개)를 생성한다는 의미입니다. 훈련 중에는 대부분의 디스크 I/O가 pcl/ 폴더에 집중되므로 빠른 로컬 SSD에 저장하는 것이 좋습니다.
자신의 데이터 세트를 훈련하는 경우 제공된 코드를 참조로 사용하여 새 데이터 로더를 생성하는 것이 좋습니다. 당사 데이터를 사용하는 경우 먼저 위의 데이터 세트 처리 섹션을 따르십시오.
먼저 사용 가능한 두 개의 안정적인 비디오 확산 체크포인트인 SVD(14프레임) 또는 SVD-XT(25프레임) 중 하나를 다운로드하여 pretrained/ 에 배치합니다(또는 아래 참조된 구성 파일에서 체크포인트 경로를 업데이트합니다). 리소스 제약으로 인해 실험에서는 14프레임 버전의 SVD에서만 작업하므로 25프레임 SVD-XT로 작업하는 경우 다른 관련 구성 값을 변경하십시오.
Kubric-4D 에서 GCD 훈련 실행을 시작하려면(점진적, 최대 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 선택합니다.
결과 모델은 모든 RGB 비디오에서 3-DoF 단안 동적 신규 뷰 합성을 수행할 수 있지만 일반적으로 Kubric 도메인 및 사람이 포함되지 않은 기타 비디오 내에서 가장 잘 수행됩니다.
ParallelDomain-4D (점진적, RGB)에서 GCD 훈련 실행을 시작하려면:
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-DoF 카메라 제어(자체-서라운드 및 서라운드-서라운드 변환)가 가능한 내부 모델이 있으며, 비록 이것이 우리 논문에서 실험의 일부는 아니지만 나중에 이곳에서 전시 및/또는 공개할 수 있습니다.
위의 모든 명령에서 GPU 인덱스 0( data.params.data_gpu )은 pcl/ 의 캐시된 병합 포인트 클라우드에서 데이터를 로드하는 동안 즉시 (입력, 지상 진실) 비디오 쌍을 구성하기 위해 예약되어 있습니다. 동일한 GPU에서 네트워크를 훈련하지 않는 것이 좋습니다. 이것이 바로 lightning.trainer.devices 분리되어 있고 대신 나머지 모든 GPU를 다루는 이유입니다.
제공된 예에서 해당 VRAM 사용량은 GPU당 약 50GB입니다. VRAM의 세 가지 가장 큰 결정 요인은 다음과 같습니다: (1) 배치 크기, (2) 공간 해상도( frame_width 및 frame_height ), (3) 프레임 수(SVD 대 SVD-XT), (4) EMA 가중치 여부 평균화가 활성화되어 있습니다. 대부분의 실험은 제한된 컴퓨팅으로 인해 EMA 없이 8x NVIDIA A100 또는 8x NVIDIA A6000 장치가 있는 단일 노드에서 수행되었습니다.
로그 및 시각화는 gcd-model/ 과 동일한 수준에 있는 logs/ 폴더 내의 날짜가 지정된 하위 폴더에 저장됩니다. 각 실행에 대해 훈련 시각화는 visuals/ 하위 폴더에 저장됩니다. 훈련이 중단되면 --resume_from_checkpoint 유효한 최신 체크포인트 파일로 지정하여 재개할 수 있습니다(예: --resume_from_checkpoint=../logs/2024-02-30T12-15-05_kb_v1/checkpoints/last.ckpt .
다음 스크립트는 시각적 검사 및 평가를 위한 다양한 유형의 출력을 생성하며 각 벤치마크에 맞게 조정되어야 합니다. 더 가벼운 작업에 대해서는 위의 추론 섹션을 참조하세요. 당사 데이터를 사용하는 경우 먼저 위의 데이터 세트 처리 섹션을 따랐는지 확인하세요. 실제 사용자 정의 데이터 세트를 평가하는 경우 새 데이터 로더를 만들고 아래 테스트 스크립트를 수정하는 것이 좋습니다.
Kubric-4D 에서 GCD 미세 조정 모델을 평가하려면 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 (장면당 다른 컨트롤)를 변경하여 여러 샘플을 평가할 수 있습니다.
ParallelDomain-4D 에서 GCD 미세 조정 모델을 평가하려면 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에서는 포즈 관련 인수 6개를 적용할 수 없지만 비디오 클립 프레임 경계는 계속 선택할 수 있습니다.
위의 test.py 스크립트는 전체 및 프레임별 PSNR 및 SSIM 번호를 포함하는 extra/ 하위 폴더 아래에 장면별 *_metrics.json 파일을 저장합니다. 또한 모든 개별 입력, 예측 및 대상 프레임을 모델에서 처리된 각 예에 대한 이미지로 저장합니다. 추가 측정항목 및/또는 집계 측정항목을 계산하려는 경우 자체 정량적 평가 워크플로에서 이러한 다양한 출력을 자유롭게 사용하세요.
기본 평가 섹션과 비교할 때 이 스크립트는 존재하지 않을 수도 있는 실제 정보에 의존하지 않습니다. 추론(Gradio) 섹션과 비교하여 이 스크립트는 더 많은 정보와 시각화를 내보냅니다.
비디오 파일이나 이미지 폴더 또는 비디오 파일이나 이미지 폴더 목록(전체 경로가 포함된 .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개의 동기화된 다중 뷰 비디오를 렌더링합니다. 4개의 관측점은 45도의 높은 고도에 있고, 나머지 12개의 관측점은 5도의 낮은 고도에 있습니다. 매개변수와 로직에 대한 더 많은 통찰력을 얻으려면 export_kub_mv.py 검사하는 것이 좋습니다.
모든 장면은 iid로 생성되므로 이 데이터 세트 버전에서는 처음 2800을 훈련 세트로 정의하고 마지막 100 + 100을 각각 검증 + 테스트 세트로 정의합니다. 외부 for 루프는 디스크 공간 문제를 방지하기 위해 정기적으로 /tmp/ 폴더를 지웁니다.
이 데이터 세트는 서비스에서 제공되며 다시 생성할 수 없습니다. 사본에 대한 다운로드 링크를 참조하십시오.
일부 장면 폴더는 존재하지 않으며(1531개의 장면 폴더가 있지만 인덱스는 최대 2143까지임) 일부 장면에는 누락된 프레임이 몇 개 있습니다. 이것이 바로 우리의 데이터로더가 두 문제에 강력하게 설계되어 있는 이유입니다. 훈련 중에 몇 가지 경고 메시지가 나타날 수 있지만 이는 정상적인 현상입니다. 또한 Kubric과 달리 장면은 인덱스와 관련하여 역상관되지 않으므로 pardom_datasplit.json 에서 훈련, 검증 및 테스트를 위해 무작위 하위 집합을 미리 선택했습니다.
검증 + 테스트 세트 크기를 각각 61 + 61 장면(각각 전체 데이터 세트의 약 4%)으로 정의합니다.
저는 TRI camviz를 기반으로 로컬 컴퓨터에서 Kubric-4D 및 ParallelDomain-4D의 예제 장면을 대화형으로 시각화하기 위한 몇 가지 도구를 작성했습니다. 나중에 여기에 공개할 수도 있지만 소스 코드를 얻기 위해 그동안 나(Basile)에게 연락 주시기 바랍니다.
작업(또는 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/}}
}
