pytorch-superpoint

这是“SuperPoint：自监督兴趣点检测与描述”的 PyTorch 实现。作者为 Daniel DeTone、Tomasz Malisiewicz 和 Andrew Rabinovich。ArXiv 2018。 此代码部分基于 TensorFlow 实现： https://github.com/rpautrat/SuperPoint。

如果您觉得本仓库对您的研究有所帮助，请不吝给它点个赞。

本仓库是我们论文 deepFEPE（IROS 2020） 的副产品。

我们的实现与原论文的区别

• 描述子损失：我们尝试了多种描述子损失方法，包括稠密法（与论文类似但略有不同）和稀疏法。我们发现稀疏损失在性能相近的情况下收敛得更快。此处默认使用稀疏法。

HPatches 数据集上的结果

任务	单应性估计			检测器指标		描述子指标
	Epsilon = 1	3	5	可重复性	MLE	NN mAP	匹配分数
预训练模型	0.44	0.77	0.83	0.606	1.14	0.81	0.55
Sift（亚像素精度）	0.63	0.76	0.79	0.51	1.16	0.70	0.27
superpoint_coco_heat2_0_170k_hpatches_sub	0.46	0.75	0.81	0.63	1.07	0.78	0.42
superpoint_kitti_heat2_0_50k_hpatches_sub	0.44	0.71	0.77	0.56	0.95	0.78	0.41

• 预训练模型来自 SuperPointPretrainedNetwork。
• 评估是在我们的评估脚本下进行的。
• COCO 和 KITTI 的预训练模型包含在本仓库中。

安装

要求

• python == 3.6
• pytorch >= 1.1（测试版本为 1.3.1）
• torchvision >= 0.3.0（测试版本为 0.4.2）
• cuda（测试版本为 cuda10）

conda create --name py36-sp python=3.6
conda activate py36-sp
pip install -r requirements.txt
pip install -r requirements_torch.txt # 安装 pytorch

路径设置

• 数据集路径（$DATA_DIR）和日志路径在 setting.py 中设置。

数据集

数据集应下载到 $DATA_DIR 目录下。Synthetic Shapes 数据集也会在此目录下生成。文件夹结构如下：

datasets/ ($DATA_DIR)
|-- COCO
|   |-- train2014
|   |   |-- file1.jpg
|   |   `-- ...
|   `-- val2014
|       |-- file1.jpg
|       `-- ...
`-- HPatches
|   |-- i_ajuntament
|   `-- ...
`-- synthetic_shapes  # 自动创建
`-- KITTI（由原始数据累积而成的文件夹）
|   |-- 2011_09_26_drive_0020_sync
|   |   |-- image_00/
|   |   `-- ...
|   |-- ...
|   `-- 2011_09_28_drive_0001_sync
|   |   |-- image_00/
|   |   `-- ...
|   |-- ...
|   `-- 2011_09_29_drive_0004_sync
|   |   |-- image_00/
|   |   `-- ...
|   |-- ...
|   `-- 2011_09_30_drive_0016_sync
|   |   |-- image_00/
|   |   `-- ...
|   |-- ...
|   `-- 2011_10_03_drive_0027_sync
|   |   |-- image_00/
|   |   `-- ...

• MS-COCO 2014
  • MS-COCO 2014 下载链接
• HPatches
  • HPatches 下载链接
• KITTI Odometry
  • KITTI 官网
  • 下载链接

运行代码

• 注意事项：
  • 可以从任意步骤（1-4）开始，直接下载一些中间结果。
  • 在单块 NVIDIA 2080Ti 上，训练通常需要 8-10 小时。
  • 目前支持在 COCO 数据集（原论文）和 KITTI 数据集上进行训练。
• Tensorboard：
  • 日志文件保存在 'runs/<\export_task>/...' 目录下。

tensorboard --logdir=./runs/ [--host | static_ip_address] [--port | 6008]

1) 在 Synthetic Shapes 数据集上训练 MagicPoint

python train4.py train_base configs/magicpoint_shapes_pair.yaml magicpoint_synth --eval

您无需手动下载合成数据，首次运行时会自动生成。合成数据将导出到 ./datasets 目录下，您可以在 settings.py 中调整相关设置。

2) 在 MS-COCO / KITTI 数据集上导出检测结果

这是单应性适配（HA）步骤，用于导出伪真值以进行联合训练。

• 确保配置文件中的预训练模型正确。
• 确保 COCO 数据集位于 $DATA_DIR 目录下（在 setting.py 中定义）。

• 配置文件：

export_folder: <'train' | 'val'>  # 设置导出用于训练还是验证

通用命令：

python export.py <导出任务>  <配置文件>  <导出文件夹> [--outputImg | 输出图像以便可视化（占用空间较大）]

导出 COCO 数据——在训练集上执行

python export.py export_detector_homoAdapt configs/magicpoint_coco_export.yaml magicpoint_synth_homoAdapt_coco

导出 COCO 数据——在验证集上执行

• 将 magicpoint_coco_export.yaml 中的 export_folder 改为 'val'。

python export.py export_detector_homoAdapt configs/magicpoint_coco_export.yaml magicpoint_synth_homoAdapt_coco

导出 KITTI 数据

• 配置：
  • 检查配置文件中的 'root' 路径。
  • 训练/验证分割文件包含在 datasets/kitti_split/ 目录下。

python export.py export_detector_homoAdapt configs/magicpoint_kitti_export.yaml magicpoint_base_homoAdapt_kitti

3) 在 MS-COCO/KITTI 数据集上训练 Superpoint

训练检测器需要伪真值标签。这些标签可以从步骤 2) 中导出，也可以从 链接 下载。然后，像往常一样，在训练之前需要设置配置文件。

• 配置文件
  • root：指定你的标签根目录
  • root_split_txt：放置 train.txt/val.txt 划分文件的位置（COCO 不需要，KITTI 需要）
  • labels：通过单应性变换适配后导出的标签
  • pretrained：指定预训练模型（也可以从头开始训练）
• 'eval'：在训练过程中开启评估

通用命令

python train4.py <训练任务> <配置文件> <导出文件夹> --eval

COCO

python train4.py train_joint configs/superpoint_coco_train_heatmap.yaml superpoint_coco --eval --debug

KITTI

python train4.py train_joint configs/superpoint_kitti_train_heatmap.yaml superpoint_kitti --eval --debug

• 设置你的批量大小（默认为 1）
• 参考：'train_tutorial.md'

4) 在 HPatches 上导出并评估指标

• 使用预训练模型，或在配置文件中指定你的模型
• ./run_export.sh 将会先运行导出，再进行评估。

导出

• 下载 HPatches 数据集（见上方链接），并将其放入 $DATA_DIR 目录中。

python export.py <导出任务> <配置文件> <导出文件夹>

• 导出关键点、描述子和匹配结果

python export.py export_descriptor configs/magicpoint_repeatability_heatmap.yaml superpoint_hpatches_test

评估

python evaluation.py <npz 文件路径> [-r, --repeatibility | -o, --outputImg | -homo, --homography ]

• 评估单应性估计、可重复性、匹配分数等...

python evaluation.py logs/superpoint_hpatches_test/predictions --repeatibility --outputImg --homography --plotMatching

5) 在 SIFT 上导出并评估可重复性

• 参考另一个项目：使用多分辨率滤波器进行特征保留的图像去噪

# 导出检测、描述和匹配
python export_classical.py export_descriptor configs/classical_descriptors.yaml sift_test --correspondence

# 评估（使用 'sift' 标志）
python evaluation.py logs/sift_test/predictions --sift --repeatibility --homography 

• 指定预训练模型

预训练模型

当前最佳模型

• COCO 数据集

logs/superpoint_coco_heat2_0/checkpoints/superPointNet_170000_checkpoint.pth.tar

• KITTI 数据集

logs/superpoint_kitti_heat2_0/checkpoints/superPointNet_50000_checkpoint.pth.tar

来自 MagicLeap 的模型

pretrained/superpoint_v1.pth

Jupyter Notebook

# 显示保存在文件夹中的图片
jupyter notebook
notebooks/visualize_hpatches.ipynb 

更新记录（年.月.日）

• 2020.08.05：
  • 更新了 PyTorch NMS（来自 https://github.com/eric-yyjau/pytorch-superpoint/pull/19）
  • 更新并测试了 KITTI 数据加载器及 Google Drive 上的标签（应该能够适应 KITTI 原始格式）
  • 更新并测试了第 5 步中的 SIFT 评估。

已知问题

• 测试第 5 步：在 SIFT 上进行评估
• COCO 数据集以低分辨率（240x320）导出，而非高分辨率（480x640）。
• 由于第 1 步是在很久以前完成的，我们仍在与第 2-4 步一起重新测试。请参考我们的预训练模型或导出的标签。或者告诉我们整个流程是如何运作的。
• TensorBoard 中出现警告信息。

进展中工作

• 发布带有单元测试的笔记本。
• 数据集：ApolloScape/TUM。

引用

请引用原始论文。

@inproceedings{detone2018superpoint,
  title={Superpoint: Self-supervised interest point detection and description},
  author={DeTone, Daniel and Malisiewicz, Tomasz and Rabinovich, Andrew},
  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition Workshops},
  pages={224--236},
  year={2018}
}

同时请引用我们的 DeepFEPE 论文。

@misc{2020_jau_zhu_deepFEPE,
Author = {You-Yi Jau and Rui Zhu and Hao Su and Manmohan Chandraker},
Title = {Deep Keypoint-Based Camera Pose Estimation with Geometric Constraints},
Year = {2020},
Eprint = {arXiv:2007.15122},
}

致谢

本实现由 You-Yi Jau 和 Rui Zhu 开发。如有任何问题，请联系 You-Yi。 此外，该工作基于 Rémi Pautrat 和 Paul-Edouard Sarlin 的 TensorFlow 实现，以及官方的 SuperPointPretrainedNetwork。 感谢 Daniel DeTone 在实现过程中的帮助。

文章

我从深度学习论文的实现中学到了什么？

pytorch-superpoint 快速上手指南

本指南基于 pytorch-superpoint 项目，帮助开发者快速在 PyTorch 环境中复现 SuperPoint 特征点检测与描述算法。

环境准备

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

• 操作系统: Linux (推荐) 或 macOS
• Python: 3.6
• PyTorch: >= 1.1 (测试版本 1.3.1)
• TorchVision: >= 0.3.0 (测试版本 0.4.2)
• GPU: 支持 CUDA (测试环境 CUDA 10)，推荐使用 NVIDIA 2080Ti 或更高版本进行训练
• 其他依赖: TensorBoard (用于可视化日志)

提示：国内用户建议使用清华源或阿里源加速 pip 和 conda 包的下载。

安装步骤

1. 创建虚拟环境

使用 Conda 创建名为 py36-sp 的 Python 3.6 环境：

conda create --name py36-sp python=3.6
conda activate py36-sp

2. 安装依赖

安装项目所需的通用依赖和 PyTorch 相关依赖。国内用户可添加 -i 参数指定镜像源：

# 安装通用依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 PyTorch 和 TorchVision (根据官方 requirements_torch.txt 或手动指定版本)
# 示例：安装测试通过的版本
pip install torch==1.3.1 torchvision==0.4.2 -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或者直接使用项目提供的文件
pip install -r requirements_torch.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置路径

编辑根目录下的 setting.py 文件，设置数据集存放路径 ($DATA_DIR) 和日志保存路径。

4. 准备数据集

将下载的数据集放置在 $DATA_DIR 目录下。项目支持以下数据集：

• MS-COCO 2014: 用于训练。
• HPatches: 用于评估。
• KITTI: 用于训练和评估。
• Synthetic Shapes: 首次运行训练时会自动生成，无需手动下载。

目录结构应如下所示：

datasets/ ($DATA_DIR)
|-- COCO
|   |-- train2014
|   `-- val2014
|-- HPatches
|-- synthetic_shapes  # 自动生成
`-- KITTI
    |-- 2011_09_26_drive_0020_sync
    `-- ...

基本使用

本项目流程分为四个主要阶段：基础检测器训练、伪标签导出、联合训练、评估。以下是基于预训练模型进行快速验证和使用的最简流程。

1. 启动 TensorBoard (可选)

用于监控训练过程或查看导出结果：

tensorboard --logdir=./runs --port 6008

2. 使用预训练模型导出特征 (以 HPatches 为例)

如果您只想测试效果或使用特征，可以直接使用提供的预训练模型导出关键点、描述子和匹配结果。

确保已下载 HPatches 数据集并配置好路径，然后运行：

python export.py export_descriptor configs/magicpoint_repeatability_heatmap.yaml superpoint_hpatches_test

3. 评估指标

对导出的结果进行评估（包括单应性估计、重复率、匹配分数等）：

python evaluation.py logs/superpoint_hpatches_test/predictions --repeatibility --outputImg --homography --plotMatching

4. 完整训练流程 (进阶)

若需从头训练，请按顺序执行以下步骤：

步骤 A: 训练 MagicPoint (合成数据) 自动生成合成数据并训练基础检测器：

python train4.py train_base configs/magicpoint_shapes_pair.yaml magicpoint_synth --eval

步骤 B: 导出伪标签 (同应性自适应) 在 COCO 或 KITTI 数据集上导出伪真值标签：

# 以 COCO 训练集为例
python export.py export_detector_homoAdapt configs/magicpoint_coco_export.yaml magicpoint_synth_homoAdapt_coco

步骤 C: 训练 SuperPoint (联合训练) 使用导出的标签进行联合训练：

# 以 COCO 为例
python train4.py train_joint configs/superpoint_coco_train_heatmap.yaml superpoint_coco --eval --debug

注意：完整训练在单张 NVIDIA 2080Ti 上通常需要 8-10 小时。建议初学者直接使用仓库中提供的预训练模型 (logs/superpoint_coco_heat2_0/checkpoints/...) 进行测试。