Hierarchical-Localization: 让视觉定位变得简单易用的工具箱

Hierarchical-Localization (hloc) 是一个用于大规模6自由度视觉定位的模块化工具箱。它实现了分层定位算法,利用图像检索和特征匹配,具有快速、准确和可扩展的特点。该代码库整合了多年来图像匹配和运动结构重建(Structure-from-Motion)方面的研究成果,使其易于使用。

主要功能

使用 hloc,您可以:

在多个室内和室外视觉定位基准上复现最先进的结果
使用 SuperPoint+SuperGlue 运行运动结构重建(SfM),定位您自己的数据集
评估您自己的局部特征或图像检索用于视觉定位
实现新的定位管道并轻松调试 🔥

分层定位示意图 分层定位同时利用图像检索和特征匹配

快速开始

您现在可以在 Google Colab 中免费使用 GPU 运行 hloc 和 COLMAP 了! notebook demo.ipynb 展示了如何仅需几个步骤就可以运行 SfM 和定位。试试用您自己的数据,我们很想听听您的反馈!

安装

hloc 需要 Python >=3.7 和 PyTorch >=1.1。在本地安装软件包会拉取其他依赖项:

git clone --recursive https://github.com/cvg/Hierarchical-Localization/
cd Hierarchical-Localization/
python -m pip install -e .

所有依赖项都列在 requirements.txt 中。从 hloc-v1.3 开始,不再需要安装 COLMAP。 该存储库包含外部局部特征作为 git 子模块 - 别忘了用 git submodule update --init --recursive 拉取子模块。

我们还提供了一个 Docker 镜像:

docker build -t hloc:latest .
docker run -it --rm -p 8888:8888 hloc:latest  # 对于 GPU 支持,添加 `--runtime=nvidia`
jupyter notebook --ip 0.0.0.0 --port 8888 --no-browser --allow-root

通用管道

该工具箱由脚本组成,大致执行以下步骤:

为所有数据库和查询图像提取局部特征,如 SuperPoint 或 DISK
构建参考 3D SfM 模型
1. 使用检索或先前的 SfM 模型找到可见的数据库图像
2. 使用 SuperGlue 或更快的 LightGlue 匹配这些数据库对
3. 使用 COLMAP 三角测量新的 SfM 模型
使用检索找到与每个查询相关的数据库图像
匹配查询图像
运行定位
可视化和调试

然后可以在 visuallocalization.net 上评估支持的数据集的定位。当有 3D LiDAR 扫描可用时,例如对于室内数据集 InLoc,可以跳过步骤 2。

工具箱的结构:

hloc/*.py: 顶层脚本
hloc/extractors/: 特征提取器接口
hloc/matchers/: 特征匹配器接口
hloc/pipelines/: 多个数据集的完整管道

hloc 可以作为外部包导入 import hloc,也可以从命令行调用:

python -m hloc.name_of_script --arg1 --arg2

任务

我们提供了使用 Aachen、InLoc 定位以及使用 SfM 为您自己的数据生成参考姿态的分步指南。只需下载数据集,您就可以开始了!

Aachen - 室外定位

查看 pipeline_Aachen.ipynb 获取使用 Aachen 定位的分步指南。使用可视化工具,尝试新的局部特征或匹配器,享受其中的乐趣!不喜欢笔记本?您也可以从命令行运行所有脚本。

Aachen定位结果

InLoc - 室内定位

notebook pipeline_InLoc.ipynb 展示了使用 InLoc 定位的步骤。这要简单得多,因为不需要 3D SfM 模型。

InLoc定位结果

从头开始进行 SfM 重建

我们在 pipeline_SfM.ipynb 中展示了如何为无序图像集运行 3D 重建。这会生成参考姿态,以及适合使用与 Aachen 相同管道进行定位的良好稀疏 3D 模型。

结果

支持的局部特征提取器: SuperPoint、DISK、D2-Net、SIFT 和 R2D2。
支持的特征匹配器: SuperGlue、其更快的后续版本 LightGlue,以及具有比率测试、距离测试和/或相互检查的最近邻搜索。hloc 还支持使用 LoFTR 进行密集匹配。
支持的图像检索: NetVLAD、AP-GeM/DIR、OpenIBL、CosPlace 和 EigenPlaces。

使用 NetVLAD 进行检索,我们获得了以下最佳结果:

方法	Aachen 白天	Aachen 夜晚	检索
SuperPoint + SuperGlue	89.6 / 95.4 / 98.8	86.7 / 93.9 / 100	NetVLAD top 50
SuperPoint + NN	85.4 / 93.3 / 97.2	75.5 / 86.7 / 92.9	NetVLAD top 30
D2Net (SS) + NN	84.6 / 91.4 / 97.1	83.7 / 90.8 / 100	NetVLAD top 30

方法	InLoc DUC1	InLoc DUC2	检索
SuperPoint + SuperGlue	46.5 / 65.7 / 78.3	52.7 / 72.5 / 79.4	NetVLAD top 40
SuperPoint + SuperGlue (temporal)	49.0 / 68.7 / 80.8	53.4 / 77.1 / 82.4	NetVLAD top 40
SuperPoint + NN	39.9 / 55.6 / 67.2	37.4 / 57.3 / 70.2	NetVLAD top 20
D2Net (SS) + NN	39.9 / 57.6 / 67.2	36.6 / 53.4 / 61.8	NetVLAD top 20

查看 visuallocalization.net/benchmark 获取更多详细信息和其他基准。

支持的数据集

我们在 hloc/pipelines/ 中提供了脚本,用于在以下数据集上运行重建和定位:Aachen Day-Night (v1.0 和 v1.1)、InLoc、Extended CMU Seasons、RobotCar Seasons、4Seasons、Cambridge Landmarks 和 7-Scenes。例如,在按照这里给出的说明下载数据集后,我们可以使用以下命令运行使用 SuperPoint+SuperGlue 的 Aachen Day-Night 管道:

python -m hloc.pipelines.Aachen.pipeline [--outputs ./outputs/aachen]

BibTex 引用

如果您在出版物中报告上述任何结果,或使用此处提供的任何工具,请考虑同时引用 Hierarchical Localization 和 SuperGlue 论文:

@inproceedings{sarlin2019coarse,
  title     = {From Coarse to Fine: Robust Hierarchical Localization at Large Scale},
  author    = {Paul-Edouard Sarlin and
               Cesar Cadena and
               Roland Siegwart and
               Marcin Dymczyk},
  booktitle = {CVPR},
  year      = {2019}
}

@inproceedings{sarlin2020superglue,
  title     = {{SuperGlue}: Learning Feature Matching with Graph Neural Networks},
  author    = {Paul-Edouard Sarlin and
               Daniel DeTone and
               Tomasz Malisiewicz and
               Andrew Rabinovich},
  booktitle = {CVPR},
  year      = {2020},
}

进一步探索

调试和可视化

每次定位运行都会生成一个 pickle 日志文件。对于每个查询,它包含选定的数据库图像、它们的匹配以及来自姿态求解器的信息,例如 RANSAC 内点。因此,可以解析它以收集统计数据并分析失败模式或困难场景。

我们还在 hloc/visualization.py 中提供了一些可视化工具,用于可视化 3D SfM 模型的一些属性,例如关键点的可见性、它们的跟踪长度或估计的稀疏深度(如下所示)。

Aachen深度可视化

使用您自己的局部特征或匹配器

如果您的代码基于 PyTorch:只需在 hloc/extractors/ 或 hloc/matchers/ 中添加一个新接口。它需要继承自 hloc.utils.base_model.BaseModel,将数据字典作为输入,并输出预测字典。参考 hloc/extractors/superpoint.py 获取示例。您还可以在 hloc/extract_features.py 或 hloc/match_features.py 中定义标准配置 - 然后可以直接