hloc - 分层定位工具箱

这是 hloc，一个用于最先进的6自由度视觉定位的模块化工具箱。它实现了分层定位，利用图像检索和特征匹配技术，具有速度快、精度高、可扩展性强的特点。该代码库整合并简化了多年来在图像匹配和运动恢复结构（SfM）领域的研究成果。

使用 hloc，你可以：

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

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

快速入门 ➡️

通过运动恢复结构（SfM）构建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

总体流程

该工具箱由一系列脚本组成，大致执行以下步骤：

1. 对所有数据库图像和查询图像提取局部特征，例如 SuperPoint 或 DISK
2. 构建参考的 3D SfM 模型
   1. 通过检索或先验的 SfM 模型找到共视的数据库图像
   2. 使用 SuperGlue 或更快速的 LightGlue 匹配这些数据库图像对
   3. 使用 COLMAP 三角测量生成新的 SfM 模型
3. 利用检索技术找出与每个查询图像相关的数据库图像
4. 匹配查询图像
5. 执行定位
6. 可视化并调试

随后，可以将定位结果在 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 和 MegaLoc。

使用 NetVLAD 进行检索时，我们获得了以下最佳结果：

更多详细信息和基准数据，请访问 visuallocalization.net/benchmark。

支持的数据集

我们在 hloc/pipelines/ 中提供了脚本，用于在以下数据集上运行重建和定位任务：亚琛昼夜（v1.0 和 v1.1）、InLoc、扩展版 CMU 四季、RobotCar 四季、4Seasons、剑桥地标和 7-Scenes。例如，在按照此处提供的说明下载数据集后，我们可以使用以下命令运行亚琛昼夜数据集的 SuperPoint+SuperGlue 流程：

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

BibTex 引用

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

@inproceedings{sarlin2019coarse,
  title     = {从粗到细：大规模下的鲁棒分层定位},
  author    = {Paul-Edouard Sarlin、Cesar Cadena、Roland Siegwart 和 Marcin Dymczyk},
  booktitle = {CVPR},
  year      = {2019}
}

@inproceedings{sarlin2020superglue,
  title     = {{SuperGlue}：利用图神经网络学习特征匹配},
  author    = {Paul-Edouard Sarlin、Daniel DeTone、Tomasz Malisiewicz 和 Andrew Rabinovich},
  booktitle = {CVPR},
  year      = {2020},
}

更进一步

调试与可视化

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

使用您自己的图像检索方法

使用已知相机参数进行重建

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"'

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

版本说明

欢迎贡献！

非常欢迎外部贡献。请遵循 PEP8 编码规范，并使用 flake8 等代码检查工具。以下是一些可能有价值的新增功能列表：

• 支持 GPS（从 EXIF 提取 + 引导式检索）
• InLoc 的共视聚类
• 原始预测结果（特征和匹配）的可视化
• 其他局部特征或图像检索方法

由 Paul-Edouard Sarlin 在众多贡献者的帮助下创建并维护。

Hierarchical-Localization (hloc) 快速上手指南

hloc 是一个模块化的工具箱，用于实现最先进的 6-DoF 视觉定位。它结合了图像检索和特征匹配技术（如 SuperPoint + SuperGlue），能够快速、准确地构建 3D 地图并定位查询图像。

1. 环境准备

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

• 操作系统: Linux (推荐) 或 macOS
• Python: >= 3.7
• PyTorch: >= 1.1 (建议安装支持 CUDA 的版本以加速推理)
• Git: 用于克隆仓库及子模块
• 硬件: 推荐使用 NVIDIA GPU 以获得最佳性能（特别是运行 SuperGlue/LightGlue 时）

注意：从 hloc-v1.3 版本开始，不再需要预先手动安装 COLMAP，工具会自动处理相关依赖。

2. 安装步骤

方法一：本地源码安装（推荐）

通过 pip 进行可编辑安装，方便开发调试。

# 1. 克隆仓库（务必加上 --recursive 参数以拉取子模块）
git clone --recursive https://github.com/cvg/Hierarchical-Localization/
cd Hierarchical-Localization/

# 2. 安装依赖包
python -m pip install -e .

如果下载子模块速度较慢，可尝试配置 Git 代理或使用国内镜像源加速 pip 安装：

python -m pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

方法二：Docker 安装

如果您希望避免环境配置冲突，可以使用提供的 Docker 镜像。

# 构建镜像
docker build -t hloc:latest .

# 运行容器（GPU 支持需添加 --runtime=nvidia）
docker run -it --rm -p 8888:8888 --runtime=nvidia hloc:latest

# 在容器内启动 Jupyter Notebook
jupyter notebook --ip 0.0.0.0 --port 8888 --no-browser --allow-root

启动后，在浏览器访问 http://localhost:8888 即可使用。

方法三：Google Colab (无需本地环境)

如果您想立即体验而不想配置本地环境，可以直接在浏览器中运行官方提供的 Demo：

• Colab 链接: Open In Colab
• 该 Notebook 演示了如何使用免费 GPU 运行 SfM 重建和定位流程。

3. 基本使用

hloc 的核心工作流程通常分为：特征提取 -> 图像检索 -> 特征匹配 -> 定位。以下以最经典的 Aachen Day-Night 数据集为例，展示如何通过命令行运行完整流程。

步骤 1: 准备数据

请下载 Aachen Day-Night 数据集并按照官方脚本整理目录结构（具体下载指令参考 hloc/pipelines/Aachen 目录下的说明）。假设数据已准备好。

步骤 2: 运行定位流水线

hloc 为常用数据集提供了预设的流水线脚本。运行以下命令即可自动执行特征提取、建图和定位：

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

该命令将依次执行：

1. 使用 SuperPoint 提取数据库和查询图像的特征。
2. 使用 NetVLAD 进行图像检索，筛选候选图像对。
3. 使用 SuperGlue 进行特征匹配。
4. 调用 COLMAP 进行三角测量构建稀疏 3D 模型。
5. 执行 PnP 算法计算查询图像的 6-DoF 位姿。

步骤 3: 查看结果

运行完成后，定位结果（位姿文件）将保存在 ./outputs/aachen 目录下。您可以使用 hloc/visualization.py 中的工具可视化 3D 点云、关键点轨迹或重投影误差，以评估定位效果。

自定义使用 (Jupyter Notebook)

对于更灵活的控制（如更换特征提取器为 DISK，或 matcher 为 LightGlue），建议参考项目根目录下的 Notebook 教程：

• 户外场景: pipeline_Aachen.ipynb
• 室内场景: pipeline_InLoc.ipynb (无需 SfM 建图，直接使用激光雷达扫描作为参考)
• 自建地图: pipeline_SfM.ipynb (从零开始构建自己的 3D 地图)

您可以在 Notebook 中逐步运行代码块，实时观察每一步的输出和可视化结果。