VGGT：视觉几何基础Transformer

牛津大学视觉几何组；Meta AI

Jianyuan Wang、Minghao Chen、Nikita Karaev、Andrea Vedaldi、Christian Rupprecht、David Novotny

@inproceedings{wang2025vggt,
  title={VGGT: Visual Geometry Grounded Transformer},
  author={Wang, Jianyuan and Chen, Minghao and Karaev, Nikita and Vedaldi, Andrea and Rupprecht, Christian and Novotny, David},
  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
  year={2025}
}

更新

• [2025年7月29日] 我们已将VGGT的许可证更新为允许商业使用（军事应用除外）。本仓库中的所有代码现均采用对商业友好的许可证。然而，仅新发布的检查点VGGT-1B-Commercial获准用于商业用途——原始检查点仍为非商业用途。完整许可详情请见此处。访问该检查点需填写申请表，系统会以类似于LLaMA审批流程的方式自动处理。新检查点的性能与原模型相近。如您发现显著性能差异，请提交问题。

• [2025年7月6日] 训练代码现已在training文件夹中提供，包含一个在自定义数据集上微调VGGT的示例。

• [2025年6月13日] 荣幸荣获CVPR 2025最佳论文奖！近期回复咨询或GitHub问题可能较慢，敬请谅解。若您感兴趣，我们的口头报告可在此查看链接。另一份较长的演示文稿可在这里找到（注：以.pptx格式分享，包含动画效果——文件较大，但如有需要，可作为模板使用）。

• [2025年6月2日] 新增了一个脚本，用于运行VGGT并将预测结果保存为COLMAP格式，可选支持束调整。保存的COLMAP文件可直接与gsplat或其他NeRF/高斯泼溅库配合使用。

• [2025年5月3日] 用于在Co3D数据集上复现我们相机位姿估计结果的评估代码现已在evaluation分支中提供。

概述

视觉几何基础Transformer（VGGT，CVPR 2025）是一种前馈神经网络，能够直接从一张、几张或数百张图像中，在几秒钟内推断出场景的所有关键3D属性，包括相机外参和内参、点云图、深度图以及3D点轨迹。

快速入门

首先，将此仓库克隆到本地，并安装依赖项（torch、torchvision、numpy、Pillow和huggingface_hub）。

git clone git@github.com:facebookresearch/vggt.git 
cd vggt
pip install -r requirements.txt

或者，您也可以将VGGT作为软件包进行安装（点击此处了解详情）。

现在，只需几行代码即可尝试该模型：

import torch
from vggt.models.vggt import VGGT
from vggt.utils.load_fn import load_and_preprocess_images

device = "cuda" if torch.cuda.is_available() else "cpu"
# bfloat16在Ampere架构GPU（计算能力8.0及以上）上受支持
dtype = torch.bfloat16 if torch.cuda.get_device_capability()[0] >= 8 else torch.float16

# 初始化模型并加载预训练权重。
# 首次运行时会自动下载模型权重，可能需要一些时间。
model = VGGT.from_pretrained("facebook/VGGT-1B").to(device)

# 加载并预处理示例图像（请替换为您自己的图像路径）
image_names = ["path/to/imageA.png", "path/to/imageB.png", "path/to/imageC.png"]  
images = load_and_preprocess_images(image_names).to(device)

with torch.no_grad():
    with torch.cuda.amp.autocast(dtype=dtype):
        # 预测包括相机参数、深度图和点云图在内的各项属性。
        predictions = model(images)

模型权重将自动从Hugging Face下载。若遇到加载缓慢等问题，您可以手动从这里下载并加载，或执行以下操作：

model = VGGT()
_URL = "https://huggingface.co/facebook/VGGT-1B/resolve/main/model.pt"
model.load_state_dict(torch.hub.load_state_dict_from_url(_URL))

详细用法

from vggt.utils.pose_enc import pose_encoding_to_extri_intri
from vggt.utils.geometry import unproject_depth_map_to_point_map

with torch.no_grad():
    with torch.cuda.amp.autocast(dtype=dtype):
        images = images[None]  # 添加批次维度
        aggregated_tokens_list, ps_idx = model.aggregator(images)
                
    # 预测相机参数
    pose_enc = model.camera_head(aggregated_tokens_list)[-1]
    # 外参和内参矩阵，遵循 OpenCV 规范（从世界坐标系到相机坐标系）
    extrinsic, intrinsic = pose_encoding_to_extri_intri(pose_enc, images.shape[-2:])

    # 预测深度图
    depth_map, depth_conf = model.depth_head(aggregated_tokens_list, images, ps_idx)

    # 预测点云
    point_map, point_conf = model.point_head(aggregated_tokens_list, images, ps_idx)
        
    # 从深度图和相机参数构建 3D 点云
    # 通常比点云分支生成的点云更精确
    point_map_by_unprojection = unproject_depth_map_to_point_map(depth_map.squeeze(0), 
                                                                extrinsic.squeeze(0), 
                                                                intrinsic.squeeze(0))

    # 预测轨迹
    # 选择你要跟踪的点，形状为 (N, 2) 表示一个场景中的 N 个点
    query_points = torch.FloatTensor([[100.0, 200.0], 
                                        [60.72, 259.94]]).to(device)
    track_list, vis_score, conf_score = model.track_head(aggregated_tokens_list, images, ps_idx, query_points=query_points[None])

交互式演示

我们提供了多种方式来可视化你的 3D 重建结果。在使用这些可视化工具之前，请先安装所需的依赖项：

pip install -r requirements_demo.txt

交互式 3D 可视化

请注意： VGGT 通常可以在不到 1 秒钟内完成一个场景的重建。然而，由于第三方渲染的原因，3D 点云的可视化可能需要数十秒，这与 VGGT 的处理时间无关。当图像数量较多时，可视化过程会更加缓慢。

Gradio Web 界面

我们的基于 Gradio 的界面允许你上传图像或视频，运行重建，并在浏览器中交互式地探索 3D 场景。你可以在本地机器上启动该界面，也可以在 Hugging Face 上试用。

python demo_gradio.py

Viser 3D 查看器

运行以下命令可以执行重建并在 Viser 中可视化点云。请注意，此脚本需要一个包含图像的文件夹路径，并且假设该文件夹下仅包含图像文件。你可以通过设置 --use_point_map 参数来使用点云分支生成的点云，而不是基于深度图的点云。

python demo_viser.py --image_folder path/to/your/images/folder

导出为 COLMAP 格式

我们还支持将 VGGT 的预测结果直接导出为 COLMAP 格式，方法如下：

# 仅前向预测
python demo_colmap.py --scene_dir=/YOUR/SCENE_DIR/

# 带束调整
python demo_colmap.py --scene_dir=/YOUR/SCENE_DIR/ --use_ba

# 使用减少的参数运行带束调整以加快处理速度
# 将 max_query_pts 从默认的 4096 减少到 2048，将 query_frame_num 从默认的 8 减少到 5
# 代价是更快的执行速度，但在复杂场景中重建结果可能不够鲁棒（你可以考虑将 query_frame_num 设置为图像总数）
# 更多带束调整配置选项请参见 demo_colmap.py
python demo_colmap.py --scene_dir=/YOUR/SCENE_DIR/ --use_ba --max_query_pts=2048 --query_frame_num=5

请确保图像存储在 /YOUR/SCENE_DIR/images/ 目录下，该目录应仅包含图像文件。可参考 examples 文件夹中的数据结构示例。

重建结果（相机参数和 3D 点云）将自动保存到 /YOUR/SCENE_DIR/sparse/ 目录下，格式符合 COLMAP 标准，如下所示：

SCENE_DIR/
├── images/
└── sparse/
    ├── cameras.bin
    ├── images.bin
    └── points3D.bin

与 Gaussian Splatting 集成

导出的 COLMAP 文件可以直接用于 gsplat 进行 Gaussian Splatting 训练。按照其官方说明安装 gsplat（推荐使用 gsplat==1.3.0）：

训练模型的示例命令如下：

cd gsplat
python examples/simple_trainer.py  default --data_factor 1 --data_dir /YOUR/SCENE_DIR/ --result_dir /YOUR/RESULT_DIR/

零样本单视角重建

尽管我们的模型从未针对单视角任务进行过训练，但它在单视角重建方面表现出令人惊讶的好性能。该模型无需将单张图像复制成一对，而是可以直接从单张图像的特征中推断出 3D 结构。你可以通过上述演示尝试这一功能，它同样适用于单视角重建。

我们并未对单目深度估计性能进行定量测试，但 @kabouzeid 慷慨地提供了 VGGT 与近期方法的对比结果 此处。结果显示，VGGT 在与 DepthAnything v2 或 MoGe 等最先进的单目方法相比时，表现具有竞争力甚至更优，尽管它从未专门针对单视角任务进行过训练。

运行时间和 GPU 内存

我们在单块 NVIDIA H100 GPU 上对 VGGT 的聚合器模块进行了不同输入规模下的运行时间和 GPU 内存占用基准测试。

请注意，这些结果是在使用 Flash Attention 3 的情况下获得的，它比默认的 Flash Attention 2 实现更快，同时几乎保持相同的内存占用。你可以自行编译 Flash Attention 3 以获得更好的性能。

研究进展

我们的工作建立在一系列先前研究项目的基础上。如果您有兴趣了解我们的研究是如何演进的，请查看我们之前的工作：

致谢

感谢以下优秀的开源项目：PoseDiffusion、VGGSfM、CoTracker、DINOv2、Dust3r、Moge、PyTorch3D、Sky Segmentation、Depth Anything V2、Metric3D，以及社区中许多其他令人启发的工作。

待办事项

• 发布训练代码
• 发布 VGGT-500M 和 VGGT-200M

许可证

有关本代码所采用许可证的详细信息，请参阅 LICENSE 文件。

请注意，只有此 模型检查点 允许商业使用。该新检查点达到了与原始检查点相同的性能水平（甚至可能略优），例如，在 Co3D 数据集上的 AUC@30 分别为 90.37 和 89.98。

VGGT 快速上手指南

VGGT (Visual Geometry Grounded Transformer) 是一个前馈神经网络，能够从单张、几张或数百张图像中，在数秒内直接推断场景的关键 3D 属性（包括相机内外参、深度图、点云图和 3D 点轨迹）。

环境准备

• 操作系统: Linux (推荐), macOS, Windows
• Python: 3.8+
• GPU: 支持 CUDA 的 NVIDIA 显卡
  • 推荐使用 Ampere 架构及以上 (Compute Capability 8.0+) 以启用 bfloat16 加速。
  • 旧款显卡将自动使用 float16。
• 显存: 根据输入图像数量而定，处理多视图重建建议显存充足。

安装步骤

1. 克隆仓库

   git clone git@github.com:facebookresearch/vggt.git 
   cd vggt
   

2. 安装依赖 使用 pip 安装核心依赖（包含 torch, torchvision, numpy, Pillow, huggingface_hub 等）：

   pip install -r requirements.txt
   

   提示: 如果下载速度慢，可添加国内镜像源加速，例如： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的推理示例，加载预训练模型并预测相机参数、深度图和点云。

import torch
from vggt.models.vggt import VGGT
from vggt.utils.load_fn import load_and_preprocess_images

# 设置设备
device = "cuda" if torch.cuda.is_available() else "cpu"
# 根据 GPU 能力选择精度：Ampere (8.0+) 支持 bfloat16，否则使用 float16
dtype = torch.bfloat16 if torch.cuda.get_device_capability()[0] >= 8 else torch.float16

# 初始化模型并加载预训练权重
# 首次运行会自动从 Hugging Face 下载权重 (facebook/VGGT-1B)
model = VGGT.from_pretrained("facebook/VGGT-1B").to(device)

# 加载并预处理图像 (请替换为你的实际图片路径)
image_names = ["path/to/imageA.png", "path/to/imageB.png", "path/to/imageC.png"]  
images = load_and_preprocess_images(image_names).to(device)

# 执行推理
with torch.no_grad():
    with torch.cuda.amp.autocast(dtype=dtype):
        # 预测相机、深度图、点云图等属性
        predictions = model(images)

# predictions 字典中包含 'cameras', 'depth_map', 'point_map' 等结果

手动加载权重（可选）

如果自动下载失败，可手动下载 model.pt 后加载：

model = VGGT()
_URL = "https://huggingface.co/facebook/VGGT-1B/resolve/main/model.pt"
model.load_state_dict(torch.hub.load_state_dict_from_url(_URL))
model.to(device)