hloc - 分层定位工具箱

这是 hloc，一个用于最先进的6自由度视觉定位的模块化工具箱。它实现了分层定位，利用图像检索和特征匹配，具有快速、准确和可扩展的特点。这个代码库结合并轻松实现了多年来在图像匹配和运动结构重建方面的研究成果。

使用 hloc，你可以：

在多个室内和室外视觉定位基准测试中复现最先进的结果
使用SuperPoint+SuperGlue进行运动结构重建，以便用你自己的数据集进行定位
评估你自己的局部特征或图像检索用于视觉定位
实现新的定位流程并轻松调试 🔥

<a href="https://arxiv.org/abs/1812.03506"><img src="https://yellow-cdn.veclightyear.com/0a4dffa0/c343dd98-60db-4d0a-896b-9c03f13612c4.png" width="60%"/></a> 分层定位同时使用图像检索和特征匹配

快速开始 ➡️

直接在你的浏览器中使用运动结构重建构建3D地图，并定位任何互联网图像！你现在可以在Google Colab中免费使用GPU运行hloc和COLMAP。 笔记本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激光雷达扫描可用时，如室内数据集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进行定位的分步指南。尝试可视化，试用新的局部特征或匹配器，玩得开心！不喜欢笔记本？你也可以从命令行运行所有脚本。

InLoc - 室内定位

笔记本pipeline_InLoc.ipynb展示了使用InLoc进行定位的步骤。由于不需要3D SfM模型，这个过程要简单得多。

从头开始的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进行检索，我们获得了以下最佳结果：

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

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

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

支持的数据集

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

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 模型的某些属性，如关键点的可见性、轨迹长度或估计的稀疏深度（如下所示）。

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

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

如果您的代码基于 TensorFlow：您需要修改 hloc/extract_features.py 和 hloc/match_features.py，或者自行将特征和匹配导出为 HDF5 文件，如下所述。

在特征文件中，每个键对应于相对于数据集根目录的图像相对路径（例如，Aachen 的 db/1.jpg），并且每个预测有一个数据集（例如，形状为 Nx2 和 DxN 的 keypoints 和 descriptors）。

在匹配文件中，每个键对应于字符串 path0.replace('/', '-')+'_'+path1.replace('/', '-')，并有一个形状为 N 的数据集 matches0。它表示第一张图像中每个关键点在第二张图像中匹配关键点的索引，如果关键点未匹配则为 -1。

</details>

使用您自己的图像检索

hloc 还通过 hloc/extract_features.py 提供了图像检索的接口。如前所述，只需在 hloc/extractors/ 中添加一个新接口。或者，您需要将全局描述符导出到 HDF5 文件中，其中每个键对应于相对于数据集根目录的图像相对路径，并包含大小为 D 的数据集 global_descriptor。然后，您可以使用 hloc/pairs_from_retrieval.py 导出图像对。

</details>

已知相机参数的重建

如果已知相机的校准参数，例如来自外部校准系统，您可以告诉 hloc 使用这些参数，而不是从 EXIF 估算它们。相机模型的名称及其参数由 COLMAP 定义。Python API：

opts = dict(camera_model='SIMPLE_RADIAL', camera_params=','.join(map(str, (f, cx, cy, k))))
model = reconstruction.main(..., image_options=opts)

命令行接口：

python -m hloc.reconstruction [...] --image_options camera_model='"SIMPLE_RADIAL"' camera_params='"256,256,256,0"'

默认情况下，hloc 在重建过程中会优化相机参数。要防止这种情况，请添加：

reconstruction.main(..., mapper_options=dict(ba_refine_focal_length=False, ba_refine_extra_params=False))

python -m hloc.reconstruction [...] --mapper_options ba_refine_focal_length=False ba_refine_extra_params=False

</details>

版本

<details> <summary>v1.4（2023年7月）</summary> - 新前端 - 全局特征：OpenIBL、CosPlace - 图像块描述符：SOSNet、HardNet - 检测器和描述符：DISK - 稀疏匹配：AdaLAM、LightGlue - 密集匹配：LoFTR - 三角测量：使用已知相机姿态进行双视图几何验证 - 控制COLMAP导入和重建选项 - 性能 - 更可靠地跳过匹配文件中的现有对 - 更快的HDF5写入 - match_features中的并行读写 - 为LaMAR添加标量检测不确定性 - 文档 - 更新的依赖要求：tqdm>=4.36.0，pycolmap>=0.3.0，kornia>=0.6.11

v1.3（2022年1月）

Google Colab上的演示笔记本
使用新的pycolmap重建对象和流程API
- 不再需要安装COLMAP - 只需pycolmap即可
- 更快的模型读写
- 通过camera_mode参数对相机共享进行精细控制
- 未知或不准确焦距的定位
模块化定位API，可控制所有估计器参数
使用plotly进行相机视锥和点的3D可视化
在hloc命名空间中进行包特定日志记录
默认将提取的特征存储为fp16而不是fp32
可选修复SuperPoint描述符采样中的长期存在的bug
添加脚本以计算用于重建或定位的详尽配对
要求pycolmap>=0.1.0和Python>=3.7

v1.2（2021年12月）

错误修复和可用性改进。
支持PIL后端进行图像调整大小。
添加__version__属性以检查未来版本。

v1.1（2021年7月）

重大变更：改进SfM文件夹结构（三角测量和重建）
支持图像检索（NetVLAD、DIR）和更多局部特征（SIFT、R2D2）
支持更多数据集：Aachen v1.1、Extended CMU Seasons、RobotCar Seasons、Cambridge Landmarks、7-Scenes
简化的流程和API
空间匹配器

v1.0（2020年7月）

初始公开版本。

欢迎贡献！

非常欢迎外部贡献。请遵循PEP8样式指南，使用flake8等代码检查工具。以下是可能有价值的添加功能的非详尽列表：