gtsfm

替代文本

平台	构建状态
Ubuntu 20.04.3

佐治亚理工运动恢复结构(GTSfM)是一个基于GTSAM的端到端SfM流程。GTSfM从零开始设计，原生支持使用Dask进行并行计算。

更多详情，请参阅我们的arXiv预印本。

许可证

我们的大部分代码受MIT许可证管理，适合商业使用。然而，我们仓库中的某些实现（如SuperPoint、SuperGlue）受非商业许可证管理，不可用于商业目的。

安装

GTSfM无需编译，因为GTSAM提供了Python轮子。本仓库包含作为Git子模块的外部仓库 -- 别忘了使用git submodule update --init --recursive拉取子模块，或使用git clone --recursive https://github.com/borglab/gtsfm.git克隆。

要运行GTSfM，首先需要创建一个包含所需依赖项的conda环境。

在Linux上，支持CUDA，运行：

conda env create -f environment_linux.yml
conda activate gtsfm-v1 # 根据您的bash和conda设置，可能需要使用"source activate gtsfm-v1"

在macOS上，不支持CUDA，所以运行：

conda env create -f environment_mac.yml
conda activate gtsfm-v1

现在，将gtsfm作为模块安装：

pip install -e .

确保您可以在Python中运行python -c "import gtsfm; import gtsam; print('hello world')"，那么就一切就绪了！

使用指南（运行3D重建）

在运行重建之前，如果您打算使用带有预训练权重的模块，如SuperPoint、SuperGlue或PatchmatchNet，请先运行：

./download_model_weights.sh

要对只有图像目录和EXIF数据的数据集运行SfM，图像文件名以"jpg"结尾，请创建以下文件结构：

└── {数据集名称}
       ├── images
               ├── image1.jpg
               ├── image2.jpg
               ├── image3.jpg

然后运行

python gtsfm/runner/run_scene_optimizer_olssonloader.py --config_name {配置名称} --dataset_root {数据集根目录} --num_workers {工作进程数}

例如，如果您有4个可用核心，并想在"door"数据集上使用深度前端（推荐），您应该运行：

python gtsfm/runner/run_scene_optimizer_olssonloader.py --dataset_root tests/data/set1_lund_door --config_name deep_front_end.yaml --num_workers 4

（或您想要的任何工作进程数）。

您可以使用Dask仪表板查看/监控分布式计算。

目前我们需要EXIF数据嵌入到您的图像中（或者您可以按Olsson数据集的预期格式提供真实内参，或COLMAP导出的文本数据等）

如果您想比较GTSfM输出和COLMAP输出，请运行：

python gtsfm/runner/run_scene_optimizer_colmaploader.py --config_name {配置名称} --images_dir {图像目录} --colmap_files_dirpath {COLMAP文件目录路径} --num_workers {工作进程数} --max_frame_lookahead {最大帧预览数}

其中 COLMAP_FILES_DIRPATH 是保存了 cameras.txt、images.txt 等 .txt 文件的目录。

要使用 Open3D 可视化结果，请运行：

python gtsfm/visualization/view_scene.py

对于需要重复处理同一数据集的用户，我们提供了缓存 GTSfM 前端结果的功能，以便后续进行非常快速的推理。更多信息请参考 gtsfm/frontend/cacher/README.md。

对于想要在多台机器组成的集群上运行 GTSfM 的用户，我们在这里提供了设置说明：CLUSTER.md

结果将存储在 --output_root 中，默认为仓库根目录下的 results 文件夹。姿态和 3D 轨迹以 COLMAP 格式存储在 --output_root 的 ba_output 子目录中。这些也可以使用 COLMAP GUI 进行可视化。

Nerfstudio

我们提供了一个预处理脚本，用于将 GTSfM 估计的相机姿态转换为 nerfstudio 格式：

python scripts/prepare_nerfstudio.py --results_path {RESULTS_DIR} --images_dir {IMAGES_DIR}

结果存储在 {RESULTS_DIR} 内的 nerfstudio_input 子目录中，如果已安装 nerfstudio，可以直接使用：

ns-train nerfacto --data {RESULTS_DIR}/nerfstudio_input

仓库结构

GTSfM 采用了高度模块化的设计。只要实现了模块的抽象基类 API，每个模块都可以替换为新的模块。代码组织如下：

gtsfm：源代码，组织如下：
- averaging
  - rotation：旋转平均实现（Shonan、Chordal 等）
  - translation：平移平均实现（1d-SFM 等）
- bundle：捆绑调整实现
- common：GTSFM 中使用的基本类，如 Keypoints、Image、SfmTrack2d 等
- data_association：3D 点三角测量（DLT），有或无 RANSAC，基于 2D 点轨迹
- densify
- frontend：SfM 前端代码，包括：
  - detector：关键点检测器实现（DoG 等）
  - descriptor：特征描述符实现（SIFT、SuperPoint 等）
  - matcher：描述符匹配实现（Superglue 等）
  - verifier：2D 对应验证器实现（Degensac、OA-Net 等）
  - cacher：前端不同阶段的缓存实现
- loader：图像数据加载器
- utils：实用函数，如序列化例程和姿态比较等
tests：每个函数和模块的单元测试

贡献

我们随时欢迎贡献！请注意本项目的贡献指南。

引用本工作

如果您使用 GTSfM，请引用我们的论文：

@misc{baid2023distributed,
      title={Distributed Global Structure-from-Motion with a Deep Front-End}, 
      author={Ayush Baid and John Lambert and Travis Driver and Akshay Krishnan and Hayk Stepanyan and Frank Dellaert},
      year={2023},
      eprint={2311.18801},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}

引用开源 Python 实现：

@misc{GTSFM,
    author = {Ayush Baid and Travis Driver and Fan Jiang and Akshay Krishnan and John Lambert
       and Ren Liu and Aditya Singh and Neha Upadhyay and Aishwarya Venkataramanan
       and Sushmita Warrier and Jon Womack and Jing Wu and Xiaolong Wu and Frank Dellaert},
    title = { {GTSFM}: Georgia Tech Structure from Motion},
    howpublished={\url{https://github.com/borglab/gtsfm}},
    year = {2021}
}

注：作者按姓氏字母顺序排列。