VGGSfM：基于视觉几何的深度结构光流

Meta AI Research, GenAI；牛津大学，VGG

Jianyuan Wang、Nikita Karaev、Christian Rupprecht、David Novotny

[论文] [项目页面] [🤗 演示] [版本 2.0]

更新：

• [2024年9月9日] 允许导出稠密点云！

• [2024年9月5日] 增加了如何使用我们的结果训练高斯泼溅模型的说明！

• [2024年8月26日]

  • 我们引入了一个视频运行器，可以处理序列帧，例如视频中的帧。它支持超过1000个输入帧的重建。通过使用掩码过滤掉移动物体，它还可以有效地从动态视频序列中恢复相机位姿和点云。

• [2024年7月28日] 增加了使用masks过滤动态物体的支持。

• [2024年7月10日] 现在我们支持导出稠密深度图！

• 很高兴地分享，我们在CVPR24 IMC挑战赛中，在相机位姿（旋转与平移）估计方面获得了第1名 🥇。

目录

• 安装
• 重建
  • 下载预训练模型
  • 运行演示
  • 可视化选项
  • 使用您自己的数据
  • 生成更稠密的点云
  • 稠密深度预测（测试版）
  • 序列输入
  • 动态/移动物体
  • 训练高斯泼溅模型
  • 常见问题

安装

我们提供了一个简单的安装脚本，默认会设置一个包含Python 3.10、PyTorch 2.1和CUDA 12.1的conda环境。

source install.sh
python -m pip install -e .

该脚本会安装官方的pytorch3d、lightglue、pycolmap、poselib和visdom。如果您无法在您的机器上安装pytorch3d，可以跳过它，因为现在我们只将其用于visdom可视化（即cfg.viz_visualize=True）。

重建

1. 下载预训练模型

检查点将在首次运行时自动从Hugging Face下载。或者，您也可以手动从Hugging Face或Google Drive下载。如果您希望手动指定检查点路径，请将auto_download_ckpt设置为False，并在Hydra配置中将resume_ckpt更新为您指定的路径。

2. 运行演示

现在是享受您的3D重建的时候了！您可以从我们提供的示例开始：

# 使用默认设置
python demo.py SCENE_DIR=examples/kitchen 

# 指定查询方法：sp+sift（默认：aliked）
python demo.py SCENE_DIR=examples/statue query_method=sp+sift

# 将查询数量增加到4096（默认：2048）
python demo.py SCENE_DIR=examples/british_museum max_query_pts=4096 

# 假设所有帧共享一个相机模型，并且
# 使用SIMPLE_RADIAL相机模型代替默认的SIMPLE_PINHOLE
# 将查询帧数从默认的3帧增加到6帧
python demo.py shared_camera=True camera_type=SIMPLE_RADIAL query_frame_num=6

# 如果您想要快速重建而无需精细跟踪
python demo.py SCENE_DIR=examples/kitchen fine_tracking=False

所有标志的默认设置都已在cfgs/demo.yaml中指定。您可以根据需要调整这些标志，例如通过max_query_pts减少查询点的数量，或增加query_frame_num`来使用更多的帧作为查询。要强制对场景使用共享相机模型，请将shared_camera=True。要使用来自不同方法的查询点，请将query_method设置为sp、sift、aliked，或任何组合，如sp+sift。此外，fine_tracking```默认是启用的，但您可以将其设置为False，仅进行粗略匹配，这样可以大大加快推理速度。

重建结果（相机参数和3D点）将自动以COLMAP格式保存在SCENE_DIR/sparse下，分别为cameras.bin、images.bin和points3D.bin。这种格式被最近的NeRF/高斯泼溅代码库广泛支持。您可以使用COLMAP GUI或viser来查看重建结果。

这种稀疏重建模式一次最多可以处理400帧。如果需要处理更多帧（例如超过1,000帧），请参阅下面的“序列输入”部分获取指导。

3. 可视化选项

如果您希望更方便地进行可视化，我们还提供了基于 Gradio 和 Visdom 的可视化选项。

3.1 Gradio 可视化（推荐）

python demo.py gr_visualize=True ...(其他标志)

3.2 Visdom 可视化

python demo.py viz_visualize=True ...(其他标志)

3.3 其他可视化功能

• 可视化 2D 重投影：

  • 要可视化重建的 3D 点的 2D 重投影，请将 make_reproj_video 标志设置为 True。这将在 SCENE_DIR/visuals 目录下生成名为 reproj.mp4 的视频。例如：

  

• 可视化轨迹预测：

  点击展开

  • 若要可视化我们轨迹预测器的原始预测结果，启用 visual_tracks=True 将生成 track.mp4。在该视频中，透明点表示可见性或置信度较低。

4. 使用您自己的数据

您只需指定数据的路径即可。例如，建议从以下命令开始：

python demo.py SCENE_DIR=/YOUR_FOLDER camera_type=SIMPLE_RADIAL gr_visualize=True make_reproj_video=True

请确保图像存储在 YOUR_FOLDER/images 中。该文件夹应仅包含图像。您可以参考 examples 文件夹中的数据结构示例。

5. 生成更密集的点云

要生成更密集的点云，可以通过设置 extra_pt_pixel_interval 参数来三角测量额外的 3D 点。对于每一帧，都会以 extra_pt_pixel_interval 定义的像素间隔采样一个 2D 网格，该网格用作查询点来估计轨迹，然后将其三角测量为 3D 点。去除噪声点后，这些点会被添加到现有点云中。由于这些额外的 3D 点未在光束法平差过程中优化，因此该方法速度较快，同时仍能保持合理的质量。通常可以从 python demo.py extra_pt_pixel_interval=10 concat_extra_points=True 开始。如果 concat_extra_points=True，额外的点将与现有点合并，从而可以直接用于高斯溅射。这些额外点的详细信息会保存在 additional/additional_points_dict.pt 中。您还可以设置 extra_by_neighbor 来控制每个额外点所考虑的相邻帧数量，以便在处理大量帧时实现高效的推理。

6. 密集深度预测（测试版）

pip install scikit-learn
git clone git@github.com:DepthAnything/Depth-Anything-V2.git dependency/depth_any_v2
python -m pip install -e .

7. 顺序输入

对于有序帧输入（如视频），我们支持以滑动窗口方式执行重建，从而可以处理超过 1,000 帧的数据。

其启动脚本 video_demo.py 与上述 demo.py 采用相同的约定。您需要将图像按顺序命名为 0000.png、0001.png、0002.png 等，放置在 YOUR_VIDEO_FOLDER/images 目录下。然后，只需运行以下命令：

python video_demo.py SCENE_DIR=/YOUR_VIDEO_FOLDER

请注意，video_demo.py 的配置已在 cfgs/video_demo.yaml 中初始化。您可以调整 init_window_size 和 window_size 来控制每个窗口的帧数。joint_BA_interval 标志用于控制在整个序列中联合光束法平差的频率。其他标志，如有关输出保存或可视化的内容，与 demo.py 完全相同。

8. 动态/移动物体

有时，输入帧中可能包含动态或移动物体。当动态物体相对较小的时候，我们的方法通常能够很好地处理。然而，如果动态物体占据了帧的很大一部分，尤其是在相机运动很小的情况下，我们建议过滤掉这些动态像素。

该代码库支持使用掩码来过滤掉动态像素。掩码应放置在 cfg.SCENE_DIR 下的 masks 文件夹中，文件名需与对应的图像匹配（如 images/0000.png 和 masks/0000.png）。这些掩码应为二值图像，其中 1 表示需要过滤掉的像素（即动态像素），0 表示保留的像素。您可以参考 DAVIS 数据集中的掩码作为示例。

掩码可以通过目标检测、视频分割或手动标注来生成。这里提供一份关于如何使用 SAM 和 Track-Anything 构建此类掩码的说明。SAM2 也是生成这些掩码的一个不错的选择。

9. 训练高斯溅射模型

如果您已使用上述命令成功重建场景，则应在您的 SCENE_DIR 下生成一个名为 sparse 的文件夹，其结构如下：

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

现在您可以使用 gsplat 来训练您自己的高斯溅射模型。请按照其官方说明安装 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/

10. 常见问题解答

python demo.py SCENE_DIR=a_scene_with_8_frames query_frame_num=8 max_query_pts=4096 query_method=aliked

测试

我们仍在准备 VGGSfM v2 的测试脚本。不过，您可以使用我们的 VGGSfM v1.1 代码来复现论文中的基准测试结果。请参考分支 v1.1。

致谢

我们深受 colmap、pycolmap、posediffusion、cotracker 和 kornia 的启发。

许可证

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

引用 VGGSfM

如果您觉得我们的仓库很有用，请考虑给它点赞 ⭐，并在您的工作中引用我们的论文：

@inproceedings{wang2024vggsfm,
  title={VGGSfM: 视觉几何驱动的深度结构光运动},
  author={Wang, Jianyuan and Karaev, Nikita and Rupprecht, Christian and Novotny, David},
  booktitle={IEEE/CVF 计算机视觉与模式识别会议论文集},
  pages={21686--21697},
  year={2024}
}

VGGSfM 快速上手指南

VGGSfM (Visual Geometry Grounded Deep Structure From Motion) 是由 Meta AI 和牛津大学 VGG 组联合推出的深度学习运动恢复结构（SfM）工具。它擅长从图像序列中高精度地恢复相机姿态和稀疏点云，支持处理动态物体、长视频序列，并可导出稠密点云及深度图，完美适配 NeRF 和 Gaussian Splatting 工作流。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu)
• GPU: 支持 CUDA 的 NVIDIA 显卡
• 基础环境:
  • Python 3.10
  • PyTorch 2.1
  • CUDA 12.1
• 依赖库: 项目脚本将自动安装 pytorch3d, lightglue, pycolmap, poselib, visdom 等核心依赖。
  • 注: 若 pytorch3d 安装失败可跳过，仅会影响 Visdom 可视化功能，不影响核心重建。

国内加速建议： 由于模型权重托管在 Hugging Face，国内用户下载可能较慢。建议配置镜像源或使用代理。 手动下载权重备用地址：Google Drive 或 Hugging Face。

安装步骤

项目提供了自动化安装脚本，推荐使用 Conda 进行环境隔离。

1. 克隆仓库并进入目录

   git clone https://github.com/vggsfm/vggsfm.git
   cd vggsfm
   

2. 运行安装脚本 该脚本会自动创建 Conda 环境并安装所有必要依赖。

   source install.sh
   

3. 安装本地包

   python -m pip install -e .
   

基本使用

1. 准备数据

将您的图片放入一个文件夹中，结构如下：

YOUR_SCENE_DIR/
└── images/
    ├── 0000.png
    ├── 0001.png
    └── ...

注意：该文件夹下应仅包含图片文件。

2. 运行重建

首次运行时，程序会自动从 Hugging Face 下载预训练模型（vggsfm_v2_0_0.bin）。

最简单的运行命令（使用示例数据）：

python demo.py SCENE_DIR=examples/kitchen

使用自定义数据：

python demo.py SCENE_DIR=/YOUR_FOLDER camera_type=SIMPLE_RADIAL gr_visualize=True

• SCENE_DIR: 指向包含 images 子文件夹的根目录。
• camera_type: 推荐设置为 SIMPLE_RADIAL 以适应大多数镜头。
• gr_visualize=True: 启用 Gradio 网页可视化，生成链接后可在浏览器查看结果（特别适合远程服务器）。

3. 查看结果

重建完成后，结果会自动保存在 SCENE_DIR/sparse 目录下，格式为 COLMAP 标准格式：

• cameras.bin: 相机参数
• images.bin: 图像姿态
• points3D.bin: 稀疏点云

您可以使用以下工具查看：

• COLMAP GUI: 传统的 SfM 查看器。
• Viser: 现代化的神经渲染查看器 (pip install viser)。
• Web 浏览器: 如果运行了 gr_visualize=True，直接点击终端输出的链接即可。

进阶提示

• 处理视频/长序列 (>1000 帧): 请使用 video_demo.py 替代 demo.py，它采用滑动窗口机制处理有序帧。

  python video_demo.py SCENE_DIR=/YOUR_VIDEO_FOLDER
  

• 过滤动态物体: 若场景中有移动物体，可在 SCENE_DIR/masks 放置与图片同名的二值掩码（1 为动态区域，0 为静态），程序会自动忽略动态像素。
• 生成稠密点云: 添加参数 extra_pt_pixel_interval=10 concat_extra_points=True 可快速三角化更多点，便于后续 Gaussian Splatting 训练。