nv-tlabs/dvlt

Official implementation of Déjà View: Looping Transformers for Multi-View 3D Reconstruction

📚 프로젝트 요약

Déjà View (DVLT) – 다시점 3D 재구성을 위한 루프형 Transformer – 는 NVIDIA와 여러 대학이 공동으로 출시한 연구용 라이브러리입니다. 이 라이브러리는 순서가 없는 이미지 세트나 비디오 프레임을 입력으로 받아 다음을 출력하는 순환(recurrent) Transformer를 구현합니다.

픽셀 단위 깊이 맵
카메라 포즈(외부 및 내부 파라미터)
3D 포인트 클라우드(월드 공간 좌표)
각 광선에 대한 신뢰도 점수

이 모델은 한 번 학습하면 가변적인 수의 세분화 단계(K)로 실행할 수 있습니다. 단계를 늘리면 추가 계산 비용이 발생하지만 품질이 향상되므로, 속도와 정확도 사이의 균형을 즉석에서 조정할 수 있습니다.

🚀 저장소 구성 요소

구성 요소	제공 내용
`dvlt/model/dvlt`	핵심 순환 Transformer 구현 및 4가지 제거(ablation) 변형(바닐라, 디커플링 블록, `s_out` 토큰 없음, 깊이 스케일링 없음).
평가 래퍼	5개의 공개 베이스라인(VGGT, VGGT-Omega, Depth-Anything-3, MapAnything, Pi3)을 위한 경량 어댑터. 원본 패키지(별도 설치 필요)를 가져오므로 DVLT와 최신 기법을 비교할 수 있습니다.
학습 스택	🤗 `accelerate` + Hydra 기반 스크립트. Weights & Biases 로깅 옵션 포함. 깊이 컨볼루션 헤드를 위한 2단계 미세 조정 레시피 포함.
추론 및 데모	즉시 실행 가능한 추론 코드, Gradio 웹 UI, 후속 시각화를 위해 `.glb` / `.rrd` 파일을 작성하는 오프라인 모드.
데이터 로더	ScanNet++, DTU, ETH3D, 7Scenes, NuScenes를 위한 전처리 파이프라인 및 무거운 전처리를 건너뛰는 경량 “benchmark_lite”.
문서 및 도구	설치 가이드, 데이터셋 설정 문서, 기여 가이드, 테스트 스위트 및 CLI 스크립트를 위한 탭 자동 완성 도우미.

🛠️ 퀵 스타트 (README 참조)

# 1️⃣ 환경 생성
conda create -n dvlt python=3.12 && conda activate dvlt
conda install pytorch=2.5.1 torchvision pytorch-cuda=12.4 -c pytorch -c nvidia -c conda-forge

# 2️⃣ 패키지 설치 (모든 옵션 포함)
pip install -e .[all]

추론 예제 (Python)

import torch
from accelerate import Accelerator
from dvlt.model.dvlt.model import DVLT
from dvlt.util.preprocess import load_sequence, preprocess_images

ckpt = "nvidia/dvlt"          # 로컬 폴더, URL 또는 HF hub ID 가능
seq_path = "path/to/scene_dir" # 또는 비디오 파일

accelerator = Accelerator(mixed_precision="bf16")
model = DVLT(img_size=504)
model.load_pretrained(ckpt, strict=True)
model.setup_test(accelerator)

_, frames = load_sequence(seq_path)
batch = preprocess_images(frames, img_size=504, patch_size=14,
                           device=accelerator.device)

with torch.no_grad(), accelerator.autocast():
    preds = model.predict(batch, accelerator)

# 결과 접근
cameras = preds["cameras"][0]
extrinsics = cameras.camera_to_worlds          # (S, 3, 4)
intrinsics = cameras.get_intrinsics_matrices()# (S, 3, 3)
depths = preds["depths"][0]                   # (S, H, W)
points = preds["world_points"][0]             # (S, H, W, 3)

학습 (단일 GPU)

python -m dvlt.scripts.train --config-name dvlt-large data=scannetpp

accelerate를 사용한 멀티 GPU 학습:

accelerate launch --num-processes 4 -m dvlt.scripts.train \
    --config-name dvlt-large data=scannetpp

학습 재개:

python -m dvlt.scripts.train \
    --config-dir=outputs/<run> --config-name=config.yaml \
    trainer.resume_from_checkpoint=latest

평가

# 전체 벤치마크 (DTU, ETH3D, 7Scenes, ScanNet++, NuScenes)
python -m dvlt.scripts.test --config-name dvlt data=benchmark

# 경량 벤치마크 (무거운 전처리 없음)
python -m dvlt.scripts.test --config-name dvlt data=benchmark_lite

인터랙티브 데모 (Gradio)

python -m dvlt.scripts.gradio_demo          # http://localhost:7860 열기
# 오프라인 모드 – UI 실행 대신 .glb/.rrd 파일 작성
python -m dvlt.scripts.gradio_demo --offline \
    --input /path/to/scene_dir --models dvlt

📊 보고된 성능 (전체 벤치마크)

데이터셋	Pose AUC@3	Pose AUC@30	Depth inlier@3%	Depth AbsRel
DTU	0.8319	0.9880	0.9706	0.0093
ETH3D	0.6604	0.9536	0.7717	0.0267
7Scenes	0.1393	0.8172	0.7437	0.0349
ScanNet++	0.7941	0.9803	0.9239	0.0167
NuScenes	0.4340	0.8534	0.5853	0.0673

⚙️ 구성 시스템

이 프로젝트는 Hydra를 사용합니다. 실험 구성은 src/dvlt/config/experiments/에 있습니다.

dvlt-large – 메인 학습 레시피(대형 모델, 전체 스케줄).
dvlt-large-ablation* – 명령줄 오버라이드를 통해 특정 아키텍처 변경 사항 전환.
dvlt-large-depthconv-stage2 – 깊이 컨볼루션 헤드 미세 조정(릴리스된 체크포인트와 일치).
dvlt – 릴리스된 2단계 체크포인트를 로드하는 추론 전용 별칭.
베이스라인 래퍼(vggt, da3-large, pi3x 등)도 평가를 위해 여기에 정의되어 있습니다.

사용자별 경로(예: 데이터셋 저장 위치)는 `src/dvlt/config/experiments/user/default.yaml`에서 설정합니다. 이를 `local.yaml`로 복사하고 `data_root`를 편집한 다음, 명령줄에서 `user=local`을 선택하여 사용하세요.

📄 라이선스

코드 – Apache 2.0 (LICENSE 참조).
모델 가중치 – NVIDIA 라이선스(연구 및 평가용, 비상업적 용도만).
타사 구성 요소는 원본 라이선스를 유지합니다(THIRD_PARTY_LICENSES.md에 나열됨).

📚 인용 방법

@article{burzio2026dejaview,
  title   = {D\'ej\'a View: Looping Transformers for Multi-View 3D Reconstruction},
  author  = {Burzio, Alessandro and Fischer, Tobias and Elflein, Sven and Zhou, Qunjie and de Lutio, Riccardo and Ren, Jiawei and Huang, Jiahui and Huang, Shengyu and Pollefeys, Marc and Leal-Taix\'e, Laura and Gojcic, Zan and Turki, Haithem},
  journal = {arXiv preprint arXiv:2605.30215},
  year    = {2026}
}

🎯 대상 사용자

신경망 3D 재구성을 탐구하는 연구자(특히 순환 또는 루프형 Transformer 아키텍처에 관심이 있는 분).
일상적인 사진/비디오 캡처에서 빠르고 반복적인 깊이 및 포즈 추정이 필요한 AR/VR 파이프라인 구축 엔지니어.
단일 코드베이스에서 최근 베이스라인(VGGT, Depth-Anything-3, MapAnything, Pi3)과 공정한 비교를 원하는 분.

🔗 링크

프로젝트 페이지: https://research.nvidia.com/labs/dvl/projects/dvlt/
arXiv 논문: https://arxiv.org/abs/2605.30215
Hugging Face 모델: https://huggingface.co/nvidia/dvlt