Magic Leap 的研究（CVPR 2020，口头报告）

SuperGlue 推理与评估演示脚本

简介

SuperGlue 是 Magic Leap 在 CVPR 2020 上发表的一项研究项目。SuperGlue 网络是一种结合了最优匹配层的图神经网络，经过训练后能够在两组稀疏图像特征之间执行匹配任务。本仓库包含 PyTorch 代码及预训练权重，用于在 SuperPoint 关键点和描述子的基础上运行 SuperGlue 匹配网络。给定一对图像，您可以通过本仓库提取这对图像之间的匹配特征。

SuperGlue 作为一个“中间层”，在一个端到端的架构中同时完成上下文聚合、匹配和过滤。更多详情请参阅：

• 论文全文 PDF：SuperGlue: 使用图神经网络学习特征匹配。

• 作者：Paul-Edouard Sarlin、Daniel DeTone、Tomasz Malisiewicz、Andrew Rabinovich

• 官网：psarlin.com/superglue，提供视频、幻灯片、最新更新以及更多可视化内容。

• hloc：一个基于 SuperGlue 的视觉定位与 SfM 新工具箱，可在 cvg/Hierarchical-Localization 获取。该工具箱曾荣获 CVPR 2020 中关于定位和图像匹配的三项竞赛冠军！

我们提供了两个预训练权重文件：一个是在 ScanNet 数据上训练的室内模型，另一个是在 MegaDepth 数据上训练的室外模型。这两个模型都位于 weights 目录 中。默认情况下，演示将运行 室内 模型。

依赖项

• Python 3 >= 3.5
• PyTorch >= 1.1
• OpenCV >= 3.4（推荐使用 4.1.2.30 以获得最佳 GUI 键盘交互体验，详见此 注释）
• Matplotlib >= 3.1
• NumPy >= 1.18

只需运行以下命令：pip3 install numpy opencv-python torch matplotlib

内容

本仓库包含两个主要的顶层脚本：

1. demo_superglue.py：可在网络摄像头、IP 摄像头、图像目录或影片文件上运行实时演示。
2. match_pairs.py：从文件中读取图像对，并将匹配结果转储到磁盘上（如果提供了真值相对位姿，则还会进行评估）。

实时匹配演示脚本 (demo_superglue.py)

该演示会在锚定图像和实时图像上运行 SuperPoint + SuperGlue 特征匹配。您可以通过按下 n 键来更新锚定图像。演示可以从 USB 或 IP 摄像头、包含图像的目录或视频文件中读取图像流。所有这些输入都可以通过 --input 标志传递。

在实时网络摄像头上运行演示

在默认的 USB 网络摄像头上运行演示（ID #0），如果有 CUDA GPU 则会使用 GPU 运行：

./demo_superglue.py

键盘控制：

• n：将当前帧设为锚定帧。
• e/r：分别提高/降低关键点置信度阈值。
• d/f：分别提高/降低匹配过滤阈值。
• k：切换关键点的可视化显示。
• q：退出。

在 CPU 上以 320x240 分辨率运行演示：

./demo_superglue.py --resize 320 240 --force_cpu

--resize 标志可用于三种方式调整输入图像大小：

1. --resize width height：将图像调整为精确的 width x height 尺寸。
2. --resize max_dimension：将输入图像的最大边调整为 max_dimension。
3. --resize -1：不进行缩放（即使用原始图像尺寸）。

默认情况下，图像会被调整为 640x480。

在图像目录上运行演示

--input 标志也可以接受目录路径。我们提供了一个包含序列样本图像的目录。要在无显示器的服务器上对 freiburg_sequence/ 目录中的图像运行演示，并将输出可视化图像保存到 dump_demo_sequence/：

./demo_superglue.py --input assets/freiburg_sequence/ --output_dir dump_demo_sequence --resize 320 240 --no_display

您应该会在 Freiburg-TUM RGBD 示例序列中看到如下输出：

匹配结果按其预测置信度用喷射色图着色（红色表示置信度高，蓝色表示置信度低）。

其他有用的命令行参数

• 使用 --image_glob 可更改图像文件扩展名（默认：*.png、*.jpg、*.jpeg）。
• 使用 --skip 可跳过中间帧（默认：1）。
• 使用 --max_length 可限制处理的总帧数（默认：1000000）。
• 使用 --show_keypoints 可可视化检测到的关键点（默认：False）。

运行匹配与评估 (match_pairs.py)

本仓库还包含一个脚本 match_pairs.py，用于从一组图像对中运行匹配。借助此脚本，您可以：

• 对一组图像对运行匹配器（无需真值）。
• 根据置信度可视化关键点和匹配结果。
• 如果提供了真值相对位姿和内参，则可以评估并可视化匹配的正确性。
• 将关键点、匹配结果和评估结果保存下来以便进一步处理。
• 整合多对图像的评估结果并生成结果表格。

仅匹配模式

该脚本最简单的用法是处理给定文本文件中列出的图像对，并将关键点和匹配结果转储为压缩的 numpy npz 文件。我们在 assets/example_indoor_pairs/ 中提供了主论文中具有挑战性的 ScanNet 图像对。运行以下命令将在每对图像上运行 SuperPoint + SuperGlue，并将结果转储到 dump_match_pairs/：

./match_pairs.py

生成的 .npz 文件可以用 Python 读取如下：

>>> import numpy as np
>>> path = 'dump_match_pairs/scene0711_00_frame-001680_scene0711_00_frame-001995_matches.npz'
>>> npz = np.load(path)
>>> npz.files
['keypoints0', 'keypoints1', 'matches', 'match_confidence']
>>> npz['keypoints0'].shape
(382, 2)
>>> npz['keypoints1'].shape
(391, 2)
>>> npz['matches'].shape
(382,)
>>> np.sum(npz['matches']>-1)
115
>>> npz['match_confidence'].shape
(382,)

对于 keypoints0 中的每个关键点，matches 数组会指示其在 keypoints1 中的匹配关键点索引，若未匹配则为 -1。

可视化模式

您可以添加 --viz 标志来转储包含匹配结果的图像输出：

./match_pairs.py --viz

您应该会在 dump_match_pairs/ 目录中看到类似这样的图像（或非常接近的版本，详见此 注释)：

匹配结果按其预测置信度用喷射色图着色（红色表示置信度高，蓝色表示置信度低）。

评估模式

你还可以使用 RANSAC + 基本矩阵分解来估计位姿，并在输入的 .txt 文件中提供了真值相对位姿和内参的情况下对其进行评估。每个 .txt 文件包含三个关键的真值矩阵：图像0的 3×3 内参矩阵 K0、图像1的 3×3 内参矩阵 K1，以及相对位姿外参的 4×4 矩阵 T_0to1。

要在示例图像集上运行评估（默认读取 assets/scannet_sample_pairs_with_gt.txt），可以运行以下命令：

./match_pairs.py --eval

由于启用了 --eval 参数，你应该会在终端看到汇总的结果打印出来。对于提供的示例图像，你应该会得到以下数值（或非常接近这些数值，详见 注释）：

评估结果（15对的平均值）：
AUC@5    AUC@10  AUC@20  精度    MScore
26.99    48.40   64.47   73.52   19.60

此时，dump_match_pairs/ 中生成的 .npz 文件将包含与评估相关的标量值，这些值是基于提供的示例图像计算得出的。以下是其中一个生成的评估文件中应包含的内容：

>>> import numpy as np
>>> path = 'dump_match_pairs/scene0711_00_frame-001680_scene0711_00_frame-001995_evaluation.npz'
>>> npz = np.load(path)
>>> print(npz.files)
['error_t', 'error_R', 'precision', 'matching_score', 'num_correct', 'epipolar_errors']

你还可以通过运行以下命令来可视化评估指标：

./match_pairs.py --eval --viz

现在，你也应该会在 dump_match_pairs/ 中看到额外的图像，这些图像展示了评估数值（或非常接近这些数值，详见 注释）：

图像的左上角显示了位姿误差和内点数量，而线条则根据其与真值相对位姿计算出的极线误差进行着色：红色表示误差较大，绿色表示误差较小。

在示例室外图像对上运行

[点击展开]

在这个仓库中，我们还提供了一些具有挑战性的 Phototourism 图像对，以便你可以重现论文中的部分图表。运行以下脚本以对提供的图像对执行匹配和可视化操作（未提供真值，详见 注释）：

./match_pairs.py --resize 1600 --superglue outdoor --max_keypoints 2048 --nms_radius 3  --resize_float --input_dir assets/phototourism_sample_images/ --input_pairs assets/phototourism_sample_pairs.txt --output_dir dump_match_pairs_outdoor --viz

现在，你应该会在 dump_match_pairs_outdoor/ 中看到类似这样的图像对（或非常接近这些图像，详见 注释）：

室内/室外推荐设置

./match_pairs.py --resize 640 --superglue indoor --max_keypoints 1024 --nms_radius 4

./match_pairs.py --resize 1600 --superglue outdoor --max_keypoints 2048 --nms_radius 3 --resize_float

测试集图像对文件格式说明

path_image_A path_image_B exif_rotationA exif_rotationB [KA_0 ... KA_8] [KB_0 ... KB_8] [T_AB_0 ... T_AB_15]

在 ScanNet 上重现室内评估

./match_pairs.py --input_dir ~/data/scannet --input_pairs assets/scannet_test_pairs_with_gt.txt --output_dir dump_scannet_test_results --eval

评估结果（1500 对的平均值）：
AUC@5    AUC@10  AUC@20  精度    MScore
16.12    33.76   51.79   84.37   31.14

在 YFCC 数据集上复现户外评估

git clone https://github.com/zjhthu/OANet
cd OANet
bash download_data.sh raw_data raw_data_yfcc.tar.gz 0 8
tar -xvf raw_data_yfcc.tar.gz
mv raw_data/yfcc100m ~/data

./match_pairs.py --input_dir ~/data/yfcc100m --input_pairs assets/yfcc_test_pairs_with_gt.txt --output_dir dump_yfcc_test_results --eval --resize 1600 --superglue outdoor --max_keypoints 2048 --nms_radius 3 --resize_float

评估结果（4000对的平均值）：
AUC@5    AUC@10  AUC@20  Prec    MScore
39.02    59.51   75.72   98.72   23.61  

在 Phototourism 数据集上复现户外评估

修正 YFCC 和 Phototourism 数据中的 EXIF 旋转信息

MegaDepth 数据集的户外训练/验证场景划分

关于可复现性的说明

创建高质量 PDF 可视化图及使用 --fast_viz 提高可视化速度

./match_pairs.py --viz --viz_extension pdf

./match_pairs.py --viz --fast_viz

./match_pairs.py --viz --fast_viz --opencv_display

BibTeX 引用

如果您使用了本文中的任何观点或此仓库中的代码，请考虑引用以下文献：

@inproceedings{sarlin20superglue,
  author    = {Paul-Edouard Sarlin and
               Daniel DeTone and
               Tomasz Malisiewicz and
               Andrew Rabinovich},
  title     = {{SuperGlue}: 使用图神经网络学习特征匹配},
  booktitle = {CVPR},
  year      = {2020},
  url       = {https://arxiv.org/abs/1911.11763}
}

其他说明

• 在演示过程中，我们发现键盘交互在 OpenCV 4.1.2.30 版本下表现良好。较旧的版本响应较慢，而最新版本则存在一个 Mac 上的 OpenCV bug。
• 我们通常不建议将 SuperPoint+SuperGlue 的输入分辨率设置低于 160x120（QQVGA）或高于 2000x1500。
• 我们无意公开 SuperGlue 的训练代码。
• 我们无意公开基于 SIFT 或单应矩阵的 SuperGlue 模型。

法律声明

Magic Leap 很荣幸能在 Github 上分享其最新的样本、工具包和研究项目，以促进开发并收集空间计算社区的反馈。使用本仓库中的资源需遵守 (a) 此处包含的许可协议，或 (b) 如果未包含许可协议，则需遵守 Magic Leap 的 开发者协议，该协议可在我们的 开发者门户 上找到。 如果您需要更多帮助，欢迎前往 论坛! 我们很高兴能成为数百万充满善意、友好且热情的社区的一员。

SuperGluePretrainedNetwork 快速上手指南

SuperGlue 是一个基于图神经网络（GNN）的特征匹配工具，常与 SuperPoint 结合使用，用于在两幅图像间进行高精度的稀疏特征点匹配。本项目提供了预训练模型（室内/室外场景）及推理脚本。

环境准备

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

• 操作系统: Linux, macOS 或 Windows
• Python: 版本 >= 3.5 (推荐 3.8+)
• 硬件: 推荐使用 NVIDIA GPU (CUDA) 以获得最佳性能，CPU 亦可运行但速度较慢。

前置依赖

主要依赖以下 Python 库：

• PyTorch >= 1.1
• OpenCV >= 3.4 (推荐 4.1.2.30 以获得更好的 GUI 交互体验)
• Matplotlib >= 3.1
• NumPy >= 1.18

安装步骤

1. 克隆项目

首先从 GitHub 克隆代码仓库：

git clone https://github.com/magicleap/SuperGluePretrainedNetwork.git
cd SuperGluePretrainedNetwork

2. 安装 Python 依赖

您可以直接使用 pip 安装所需依赖。为了加快下载速度，国内用户建议使用清华或阿里镜像源：

使用默认源：

pip3 install numpy opencv-python torch matplotlib

使用国内镜像源（推荐）：

pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy opencv-python torch matplotlib

注意：如果您的环境需要特定版本的 PyTorch（例如带 CUDA 支持），请访问 PyTorch 官网 获取对应的安装命令。

基本使用

本项目提供两个核心脚本：demo_superglue.py（实时演示）和 match_pairs.py（批量匹配与评估）。以下是两种最常用的快速启动方式。

场景一：实时摄像头演示 (Live Demo)

此脚本会调用默认 USB 摄像头，实时提取特征并进行匹配。您可以按 n 键将当前帧设为锚点图像。

运行命令：

./demo_superglue.py

常用参数：

• --force_cpu: 强制使用 CPU 运行（若无 GPU）。
• --resize 320 240: 调整输入图像分辨率以加速处理。
• --input <path>: 指定输入源（可以是摄像头 ID、图片文件夹路径或视频文件）。

键盘控制：

• n: 选择当前帧作为锚点 (Anchor)
• e / r: 增加/减少关键点置信度阈值
• d / f: 增加/减少匹配过滤阈值
• k: 切换关键点可视化
• q: 退出程序

场景二：批量图片对匹配 (Batch Matching)

此脚本用于处理静态图片对，提取匹配点并保存结果。默认会使用提供的室内场景示例数据。

运行命令（仅匹配）：

./match_pairs.py

执行后，匹配结果（关键点和匹配索引）将保存在 dump_match_pairs/ 目录下的 .npz 文件中。

运行命令（匹配 + 可视化）： 若需生成带有匹配连线可视化的图片：

./match_pairs.py --viz

运行命令（匹配 + 评估）： 如果输入文件包含真值位姿（Ground Truth），可添加 --eval 进行精度评估：

./match_pairs.py --eval

针对不同场景的推荐配置

根据图片内容选择合适的预训练模型和参数可获得更好效果：

室内场景 (Indoor - 默认):

./match_pairs.py --resize 640 --superglue indoor --max_keypoints 1024 --nms_radius 4

室外场景 (Outdoor):

./match_pairs.py --resize 1600 --superglue outdoor --max_keypoints 2048 --nms_radius 3 --resize_float

提示：匹配结果中的连线颜色代表预测置信度（红色表示高置信度，蓝色表示低置信度）。