nv-tlabs/dvlt

📚 项目摘要

Déjà View (DVLT) – 用于多视角 3D 重建的循环 Transformer – 是由 NVIDIA 与多所大学共同发布的研究级库。它实现了一种循环 Transformer，可以接收无序的图像集或视频帧并输出：

• 像素级深度图
• 相机位姿（外参与内参）
• 3D 点云（世界空间坐标）
• 每个射线的置信度分数

该模型训练一次后，可以执行可变数量的细化步骤 (K)。更多的步骤能以额外的计算成本换取更高的质量，让您能即时权衡速度与准确度。

---

🚀 仓库包含什么？

组件	提供内容
dvlt/model/dvlt	核心循环 Transformer 实现及四种消融变体（原生、解耦块、无 s_out token、无深度缩放）。
评估封装器	针对五个公开基准（VGGT, VGGT-Omega, Depth-Anything-3, MapAnything, Pi3）的轻量级适配器。它们导入原始包（需另外安装），以便您将 DVLT 与最先进的方法进行比较。
训练堆栈	基于 🤗 accelerate + Hydra 构建的脚本，可选配 Weights & Biases 记录。包含用于深度卷积头的第二阶段微调配方。
推理与演示	即开即用的推理代码、Gradio 网页 UI，以及用于后续可视化的离线模式（写入 .glb / .rrd 文件）。
数据加载器	针对 ScanNet++, DTU, ETH3D, 7Scenes, NuScenes 的预处理管线，以及跳过繁重预处理的轻量级 “benchmark_lite”。
文档与工具	安装指南、数据集设置文档、贡献指南、测试套件，以及用于 CLI 脚本的 Tab 键自动补全辅助工具。

---

🛠️ 快速入门（来自 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
# 离线模式 – 写入 .glb/.rrd 文件而非启动 UI
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 – 仅推理别名，加载发布的第二阶段检查点。
• 基准封装器（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