DEEP-IMAGE-MATCHING

SIFT	DISK	图像定向	密集重建与ROMA

SIFT	SUPERGLUE

用于SfM软件的多视图匹配器。支持基于深度学习和手工设计的局部特征及匹配算法，并可将关键点和匹配直接导出到COLMAP数据库或通过导入Bundler格式的重建文件导出至Agisoft Metashape。目前，它同时支持OpenMVG和MicMac。欢迎合作！

有关如何使用DIM，请查看文档（已更新至主分支）。

请注意，deep-image-matching正处于积极开发中，目前仍处于实验阶段。如果您发现任何错误，请提交问题。关于各个局部特征和匹配算法的许可信息，请参阅其原作者的项目。

主要特性：

• 多视图
• 支持大尺寸图像
• 当前最先进（SOTA）的深度学习和手工设计特征
• 支持图像旋转
• 与多种SfM软件兼容
• 支持基于深度学习局部特征的图像检索
• 基于图的聚类
• 可在DIM中直接运行SfM（pycolmap、openmvg等）

支持的特征提取器

算法	年份	论文链接	Github链接	备注
RIPE	2025	链接	链接	支持
RDD sparse	2025	链接	链接	支持
LiftFeat	2025	链接	链接	支持
XFeat	2024	链接	链接	支持
DeDoDe	2024	链接	链接	仅GPU支持
ALIKED	2023	链接	链接	支持
SRIF	2023	链接	链接	支持
DISK	2020	链接	链接	支持
KeyNet	2019	链接	链接	支持
SuperPoint	2018	链接	链接	支持
Superpoint open	2018	链接	链接	支持
HardNet	2017	链接	链接	支持
ORB	2011	链接	链接	来自OpenCV
SIFT	2004	链接	链接	来自OpenCV

支持的匹配算法

算法	年份	论文链接	Github链接	备注
LightGlue	2023	链接	链接	与SuperPoint、DISK和ALIKED配合使用
LighterGlue	2023	链接	链接	与XFeat配合使用
RoMa	2023	链接	链接	支持
SE2-LoFTR	2022	链接	链接	不支持分块处理且仅限GPU
LoFTR	2021	链接	链接	仅限GPU
SuperGlue	2020	链接	链接	与SuperPoint配合使用
最近邻	-	-	-	来自KORNIA

支持的SfM软件

| ✓ COLMAP | | ✓ OpenMVG | | ✓ MICMAC | | ✓ Agisoft Metashape | | ✓ 支持Bundler格式的软件 |

Colab 演示和笔记本

想在示例数据集上运行吗？➡️

想在自己的图像上运行吗？➡️

DIM 也可以作为库来使用，而不需要通过命令行界面执行（请参阅“使用说明”）。

快速示例请参见：

• demo.py - 简单脚本，演示基本工作流程
• demo.ipynb - 演示的交互式笔记本版本
• notebooks/sfm_pipeline.ipynb - 包含详细说明的完整 SfM 流程

本地安装

为了安装 deep-image-matching，我们推荐使用 uv 进行快速可靠的包管理：

# 如果尚未安装 uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建并激活虚拟环境
uv venv --python 3.9
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

然后，您可以使用 uv 安装 deep-image-matching：

uv pip install -e .

此命令将以可编辑模式安装该包，允许您修改源代码并立即看到更改，而无需重新安装。如果您希望将 deep-image-matching 用作不可编辑的库，也可以不带 -e 标志进行安装。

这还将安装 pycolmap 作为依赖项，这是运行 3D 重建所必需的。如果在使用 pycolmap 时遇到任何问题，您可以按照官方说明此处手动安装它。

要验证 deep-image-matching 是否正确安装，您可以在 Python shell 中尝试导入该包：

import deep_image_matching as dim

要测试大部分功能，可以运行测试以检查 deep-image-matching 是否正确安装：

uv run pytests

更多信息请参阅文档。

为什么选择 uv？

该项目已从 conda/pip 迁移到 uv 进行依赖管理。其优势包括：

• 更快的安装速度：uv 在依赖解析和安装方面明显快于 pip
• 更好的依赖解析：更可靠地解决复杂的依赖树
• 锁文件支持：uv.lock 可确保在不同环境中实现可重复的安装
• 集成工具链：内置对虚拟环境、Python 版本管理和项目构建的支持
• 跨平台一致性：更好地支持不同的操作系统和架构

Conda/pip 安装

如果您在使用 uv 时遇到问题、更倾向于全局安装 DIM，或者在安装过程中遇到其他问题，可以使用 conda/manba 创建环境，并使用 pip 从源代码安装 DIM：

git clone https://github.com/3DOM-FBK/deep-image-matching.git
cd deep-image-matching

conda create -n deep-image-matching python=3.9
conda activate deep-image-matching
pip install -e .

Docker 安装

有关 Docker 安装的信息，请参阅文档中的Docker 安装部分。

使用说明

快速入门演示

要快速入门，请查看 demo.py 脚本或 demo.ipynb 笔记本，它们使用示例数据集演示了基本用法：

python demo.py --dir assets/example_cyprus --pipeline superpoint+lightglue

该演示使用提供的示例数据集运行从特征提取到 3D 重建的完整流程。 类似的演示示例也以笔记本形式提供在 demo.ipynb 中。

命令行界面

使用以下命令可查看 CLI 的所有可用选项：

python -m deep_image_matching --help

例如，要在 example_cyprus 数据集上使用 SuperPoint 和 LightGlue 运行匹配：

python -m deep_image_matching --dir assets/example_cyprus --pipeline superpoint+lightglue

--dir 参数定义了处理目录，所有结果都将保存在此目录中。该目录必须包含一个名为 images 的子文件夹，其中存放所有待处理的图像。

库的使用

Deep-image-matching 也可以作为 Python 库使用。有关展示完整 SfM 流程的综合示例，请参阅 notebooks/sfm_pipeline.ipynb。

详细的使用说明和配置请参阅文档。

高级用法

有关高级用法，请参阅文档和/或查看 scripts 目录。

合并具有不同局部特征的数据库

要使用不同的局部特征和/或匹配器进行匹配，并将结果合并在一起，可以使用 ./scripts 目录中的脚本合并 COLMAP 数据库。

python ./join_databases.py --help
python ./join_databases.py --input path/to/dir/with/databases --output path/to/output/dir

将解决方案导出到 Metashape

建议的解决方案：

• 现在可以直接在 Metashape 中运行 SfM，使用在 DIM 中提取的 2D 观测值。您可以使用 scripts 文件夹中的 export_to_bundler.py 脚本，它会创建一个假的 Bundler 文件。然后在 Metashape 中导入所需的所有图像，使用 Bundler 文件导入相机姿态，选择所有图像并重置对齐。最后右键点击，对齐选定的相机（参见问题)。

其他解决方案：

• 若要将解决方案导出到 Metashape，可以将 COLMAP 数据库导出为 Bundler 格式，然后再导入 Metashape。这可以通过 Metashape 的图形界面完成：首先导入图像，然后使用“导入相机”功能（文件 -> 导入 -> 导入相机），选择 Bundler 文件（例如 bundler.out）和图像列表文件（例如 bundler_list.txt）。

• 或者，您也可以使用 export_to_metashape.py 脚本，自动从以 Bundler 格式保存的重建结果中创建 Metashape 项目。该脚本以 Bundler 格式的解决方案和图像作为输入，将其导出到 Metashape。它需要在您的环境中安装 Metashape 作为 Python 模块，并持有有效许可证。请参阅https://github.com/franioli/metashape上的说明。

如何贡献

欢迎对本仓库的任何贡献！ 如果您想为项目做出贡献，请查看贡献指南。

待办事项列表

有关未来计划的功能和改进，请参阅待办事项列表。

参考文献

如果您觉得本仓库对您的工作有所帮助，请引用以下论文：

@article{morelli2024_deep_image_matching,
  AUTHOR = {Morelli, L. and Ioli, F. and Maiwald, F. and Mazzacca, G. and Menna, F. and Remondino, F.},
  TITLE = {DEEP-IMAGE-MATCHING: 复杂场景多视图影像匹配工具箱},
  JOURNAL = {国际摄影测量、遥感与空间信息科学档案},
  VOLUME = {XLVIII-2/W4-2024},
  YEAR = {2024},
  PAGES = {309--316},
  DOI = {10.5194/isprs-archives-XLVIII-2-W4-2024-309-2024}
}

@article{morelli2022photogrammetry,
  title={摄影测量：过去与现在——从手工制作到深度学习连接点},
  author={Morelli, Luca and Bellavia, Fabio and Menna, Fabio and Remondino, Fabio},
  journal={国际摄影测量、遥感与空间信息科学档案},
  volume={48},
  pages={163--170},
  year={2022},
  publisher={Copernicus GmbH}
}

@article{ioli2024,
  title={基于深度学习的低成本摄影测量技术在冰川四维短期动态监测中的应用},
  author={Ioli, Francesco and Dematteis, Nicolò and Giordan, Daniele and Nex, Francesco and Pinto Livio},
  journal={PFG——摄影测量、遥感与地理信息科学期刊},
  year={2024},
  DOI = {10.1007/s41064-023-00272-w}
}

根据所使用的具体选项，还请参考以下相关工作的引用：

• KORNIA
• HLOC
• COLMAP
• OpenMVG
• MICMAC
• 所使用的局部特征和匹配算法

deep-image-matching 快速上手指南

deep-image-matching (DIM) 是一个用于运动恢复结构（SfM）软件的多视图特征匹配工具。它支持基于深度学习和手工设计的局部特征及匹配器，可直接将关键点和匹配结果导出到 COLMAP 数据库、OpenMVG、MicMac 或 Agisoft Metashape。

1. 环境准备

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

• 操作系统: Linux, macOS 或 Windows
• Python 版本: 推荐 Python 3.9 (部分新特性依赖此版本)
• 硬件加速: 若使用深度学习模型（如 DeDoDe, LoFTR, SuperGlue 等），强烈建议配备 NVIDIA GPU 并安装对应的 CUDA 驱动。
• 前置依赖:
  • Git (用于克隆代码)
  • 构建工具 (如 build-essential on Linux, Xcode Command Line Tools on macOS)

注意：本项目推荐使用 uv 进行包管理，以获得更快的安装速度和更可靠的依赖解析。

2. 安装步骤

方法一：使用 uv 安装（推荐）

uv 是一个极速的 Python 包管理器。

1. 安装 uv (如果尚未安装):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 创建并激活虚拟环境:

   uv venv --python 3.9
   source .venv/bin/activate  # Windows 用户请使用: .venv\Scripts\activate
   

3. 安装 deep-image-matching: 克隆仓库并进入目录（如果尚未克隆）：

   git clone https://github.com/3DOM-FBK/deep-image-matching.git
   cd deep-image-matching
   

   执行安装命令（-e 表示可编辑模式，方便修改源码）：

   uv pip install -e .
   

   该命令会自动安装 pycolmap 等必要依赖以支持 3D 重建。

4. 验证安装: 在 Python 中尝试导入：

   import deep_image_matching as dim
   

   或运行测试套件：

   uv run pytests
   

方法二：使用 Conda/Pip 安装（备选）

如果您习惯使用 Conda 或遇到 uv 兼容性问题：

git clone https://github.com/3DOM-FBK/deep-image-matching.git
cd deep-image-matching

conda create -n deep-image-matching python=3.9
conda activate deep-image-matching
pip install -e .

3. 基本使用

准备工作

确保你的工作目录下有一个名为 images 的子文件夹，并将所有待处理图片放入其中。例如：

my_project/
└── images/
    ├── img1.jpg
    ├── img2.jpg
    └── ...

命令行快速启动 (CLI)

最简单的用法是运行内置的演示脚本或直接调用模块。以下示例使用 SuperPoint 提取特征并结合 LightGlue 进行匹配，对示例数据集进行处理：

python demo.py --dir assets/example_cyprus --pipeline superpoint+lightglue

若要处理你自己的图片目录（假设目录名为 my_project）：

python -m deep_image_matching --dir my_project --pipeline superpoint+lightglue

参数说明：

• --dir: 指定处理目录（必须包含 images 子文件夹）。
• --pipeline: 指定“特征提取器 + 匹配器”组合。常用组合包括：
  • superpoint+lightglue (经典高效)
  • disk+lightglue
  • xfeat+lighterglue
  • sift+nearest_neighbor (传统算法)

作为 Python 库使用

你也可以在 Python 脚本或 Jupyter Notebook 中直接调用 DIM 作为库。完整的 SfM 流程示例请参考项目中的 notebooks/sfm_pipeline.ipynb。

基础导入方式：

import deep_image_matching as dim

# 具体 API 调用请参考官方文档或 notebooks 示例

---

提示：更多高级用法（如合并不同特征的数据库、自定义配置）请参阅项目的 官方文档。