Think Match

ThinkMatch 由 ThinkLab（上海交通大学）开发和维护。 本仓库主要实现以下目标：

• 提供模块 开发深度图匹配算法以促进未来研究
• 实现 最新的深度图匹配方法
• 基准测试 不同数据集和实验设置下的现有深度图匹配算法，实现公平比较

官方文档：https://thinkmatch.readthedocs.io

源代码：https://github.com/Thinklab-SJTU/ThinkMatch

图匹配简介

图匹配（Graph Matching, GM）是计算机视觉、模式识别和数据挖掘领域中基础且具有挑战性的问题。图匹配旨在通过求解一个称为二次分配问题（Quadratic Assignment Problem, QAP）的NP难组合优化问题，来寻找多个图之间的节点对应关系。近年来，基于深度学习的图匹配方法研究逐渐兴起。

图匹配技术已应用于以下场景：

• 连接电影与摘要

  

• 图像对应

  

• 分子匹配

  

• 以及其他应用场景...

本仓库主要聚焦于图像关键点匹配，因为这是现有图匹配方法常用的测试基准。

更多技术细节请参考以下综述文献：

• 詹俊驰, 尹旭晨, 林伟尧, 邓成, 查红渊, 杨小康. "图匹配研究进展综述." ICMR 2016.

深度图匹配算法

ThinkMatch 目前包含以下深度图匹配方法的 PyTorch 源代码：

• GMN
  • Andrei Zanfir 和 Cristian Sminchisescu. "图匹配的深度学习." CVPR 2018. [论文]
• PCA-GM & IPCA-GM
  • Runzhong Wang, Junchi Yan 和 Xiaokang Yang. "基于嵌入的鲁棒深度图匹配组合学习方法." TPAMI 2020. [论文], [项目页面]
  • Runzhong Wang, Junchi Yan 和 Xiaokang Yang. "深度图匹配的组合嵌入网络学习." ICCV 2019. [论文]
• NGM & NGM-v2
  • Runzhong Wang, Junchi Yan, Xiaokang Yang. "神经图匹配网络：学习Lawler二次分配问题及其扩展到超图和多图匹配." TPAMI 2021. [论文], [项目页面]
• CIE-H
  • Tianshu Yu, Runzhong Wang, Junchi Yan, Baoxin Li. "基于通道独立嵌入和匈牙利注意力的深度图匹配学习." ICLR 2020. [论文]
• GANN
  • Runzhong Wang, Junchi Yan 和 Xiaokang Yang. "联合多图匹配与聚类的渐进分配方法及其在无监督图匹配网络学习中的应用." NeurIPS 2020. [论文]
  • Runzhong Wang, Junchi Yan 和 Xiaokang Yang. "通过差异最小化学习混合模式的无监督图匹配." TPAMI 2023. [论文], [项目页面]
• BBGM
  • Michal Rolínek, Paul Swoboda, Dominik Zietlow, Anselm Paulus, Vít Musil, Georg Martius. "通过组合求解器的黑盒微分实现深度图匹配." ECCV 2020. [论文]
• GCAN
  • Zheheng Jiang, Hossein Rahmani, Plamen Angelov, Sue Black, Bryan M. Williams. "用于尺寸可变深度图匹配的图上下文注意力网络." CVPR 2022. [论文]
• AFAT
  • Runzhong Wang, Ziao Guo, Shaofei Jiang, Xiaokang Yang, Junchi Yan. "通过可微Top-K实现的深度部分图匹配学习." CVPR 2023. [论文]
• LinSAT
  • Runzhong Wang, Yunhao Zhang, Ziao Guo, Tianyi Chen, Xiaokang Yang, Junchi Yan. "LinSATNet：正线性可满足性神经网络." ICML 2023. [论文]
• COMMON & COMMON+
  • Yijie Lin, Mouxing Yang, Jun Yu, Peng Hu, Changqing Zhang, Xi Peng. "双层噪声对应下的图匹配." ICCV 2023. [论文], [项目页面]
  • Yijie Lin, Mouxing Yang, Peng Hu, Jiancheng Lv, Hao Chen, Xi Peng. "图匹配中部分和噪声对应的联合学习". TPAMI, 2026. [论文]

使用 ThinkMatch 的场景

ThinkMatch 被设计为深度图匹配的研究协议。当您有以下需求时推荐使用：

• 开发新算法并发表新的图匹配论文；
• 理解深度图匹配模型的细节；
• 调试超参数和网络结构；
• 对深度图匹配网络进行基准测试。

不推荐使用 ThinkMatch 的场景

您可能会发现 ThinkMatch 的环境配置较复杂，且图匹配细节难以理解。 pygmtools 提供了用户友好的 API，推荐在以下场景使用：

• 如果您希望将图匹配作为流程步骤集成（无论是学习型或非学习型， 支持 numpy/pytorch/jittor/paddle/mindspore/tensorflow）。
• 如果您需要快速对 pygmtools 中的图匹配求解器进行基准测试和性能分析。
• 如果您不想深入研究算法细节且无需修改算法。

您可以通过以下命令安装用户友好包：

$ pip install pygmtools

官方文档：https://pygmtools.readthedocs.io

源代码：https://github.com/Thinklab-SJTU/pygmtools

深度图匹配基准测试

PascalVOC - 2GM

模型(model)	年份(year)	飞机(aero)	自行车(bike)	鸟类(bird)	船舶(boat)	饮料瓶(bottle)	公交车(bus)	汽车(car)	猫(cat)	椅子(chair)	奶牛(cow)	餐桌(table)	狗(dog)	马(horse)	摩托车(mbkie)	人物(person)	植物(plant)	羊(sheep)	沙发(sofa)	电视(tv)	平均值(mean)
GMN	2018	0.4163	0.5964	0.6027	0.4795	0.7918	0.7020	0.6735	0.6488	0.3924	0.6128	0.6693	0.5976	0.6106	0.5975	0.3721	0.7818	0.6800	0.4993	0.8421	0.9141
PCA-GM	2019	0.4979	0.6193	0.6531	0.5715	0.7882	0.7556	0.6466	0.6969	0.4164	0.6339	0.5073	0.6705	0.6671	0.6164	0.4447	0.8116	0.6782	0.5922	0.7845	0.9042
NGM	2019	0.5010	0.6350	0.5790	0.5340	0.7980	0.7710	0.7360	0.6820	0.4110	0.6640	0.4080	0.6030	0.6190	0.6350	0.4560	0.7710	0.6930	0.6550	0.7920	0.8820
NHGM	2019	0.5240	0.6220	0.5830	0.5570	0.7870	0.7770	0.7440	0.7070	0.4200	0.6460	0.5380	0.6100	0.6190	0.6080	0.4680	0.7910	0.6680	0.5510	0.8090	0.8870
IPCA-GM	2020	0.5378	0.6622	0.6714	0.6120	0.8039	0.7527	0.7255	0.7252	0.4455	0.6524	0.5430	0.6724	0.6790	0.6421	0.4793	0.8435	0.7079	0.6398	0.8380	0.9083
CIE-H	2020	0.5250	0.6858	0.7015	0.5706	0.8207	0.7700	0.7073	0.7313	0.4383	0.6994	0.6237	0.7018	0.7031	0.6641	0.4763	0.8525	0.7172	0.6400	0.8385	0.9168
BBGM	2020	0.6187	0.7106	0.7969	0.7896	0.8740	0.9401	0.8947	0.8022	0.5676	0.7914	0.6458	0.7892	0.7615	0.7512	0.6519	0.9818	0.7729	0.7701	0.9494	0.9393
NGM-v2	2021	0.6184	0.7118	0.7762	0.7875	0.8733	0.9363	0.8770	0.7977	0.5535	0.7781	0.8952	0.7880	0.8011	0.7923	0.6258	0.9771	0.7769	0.7574	0.9665	0.9323
NHGM-v2	2021	0.5995	0.7154	0.7724	0.7902	0.8773	0.9457	0.8903	0.8181	0.5995	0.8129	0.8695	0.7811	0.7645	0.7750	0.6440	0.9872	0.7778	0.7538	0.9787	0.9280
COMMON	2023	0.6560	0.7520	0.8080	0.7950	0.8930	0.9230	0.9010	0.8180	0.6160	0.8070	0.9500	0.8200	0.8160	0.7950	0.6660	0.9890	0.7890	0.8090	0.9930	0.9380
COMMON+	2026	0.6880	0.7550	0.8260	0.7740	0.9000	0.9220	0.8950	0.8070	0.6180	0.8240	0.9530	0.8050	0.8210	0.8160	0.6770	0.9880	0.7990	0.8100	0.9850	0.9540

Willow 物体类别 - 2GM & 多图匹配(MGM)

模型(model)	年份(year)	备注(remark)	汽车(Car)	鸭子(Duck)	人脸(Face)	摩托车(Motorbike)	酒瓶(Winebottle)	平均值(mean)
GMN	2018	-	0.6790	0.7670	0.9980	0.6920	0.8310	0.7934
PCA-GM	2019	-	0.8760	0.8360	1.0000	0.7760	0.8840	0.8744
NGM	2019	-	0.8420	0.7760	0.9940	0.7680	0.8830	0.8530
NHGM	2019	-	0.8650	0.7220	0.9990	0.7930	0.8940	0.8550
NMGM	2019	-	0.7850	0.9210	1.0000	0.7870	0.9480	0.8880
IPCA-GM	2020	-	0.9040	0.8860	1.0000	0.8300	0.8830	0.9006
CIE-H	2020	-	0.8581	0.8206	0.9994	0.8836	0.8871	0.8898
BBGM	2020	-	0.9680	0.8990	1.0000	0.9980	0.9940	0.9718
GANN-MGM	2020	自监督(self-supervised)	0.9600	0.9642	1.0000	1.0000	0.9879	0.9906
NGM-v2	2021	-	0.9740	0.9340	1.0000	0.9860	0.9830	0.9754
NHGM-v2	2021	-	0.9740	0.9390	1.0000	0.9860	0.9890	0.9780
NMGM-v2	2021	-	0.9760	0.9447	1.0000	1.0000	0.9902	0.9822
COMMON	2023	-	0.9760	0.9820	1.0000	1.0000	0.9960	0.9910
COMMON+	2026	-	0.9830	0.9820	1.0000	1.0000	1.0000	0.9930

SPair-71k - 2GM

模型	年份	飞机	自行车	鸟类	船舶	瓶子	巴士	汽车	猫	椅子	奶牛	狗	马匹	山地车	人物	植物	绵羊	火车	电视	平均值
GMN	2018	0.5991	0.5099	0.7428	0.4672	0.6328	0.7552	0.6950	0.6462	0.5751	0.7302	0.5866	0.5914	0.6320	0.5116	0.8687	0.5787	0.6998	0.9238	0.6526
PCA-GM	2019	0.6467	0.4571	0.7811	0.5128	0.6381	0.7272	0.6122	0.6278	0.6255	0.6822	0.5906	0.6115	0.6486	0.5773	0.8742	0.6042	0.7246	0.9283	0.6595
NGM	2019	0.6644	0.5262	0.7696	0.4960	0.6766	0.7878	0.6764	0.6827	0.5917	0.7364	0.6391	0.6066	0.7074	0.6089	0.8754	0.6387	0.7979	0.9150	0.6887
IPCA-GM	2020	0.6901	0.5286	0.8037	0.5425	0.6653	0.8001	0.6847	0.7136	0.6136	0.7479	0.6631	0.6514	0.6956	0.6391	0.9112	0.6540	0.8291	0.9750	0.7116
CIE-H	2020	0.7146	0.5710	0.8168	0.5672	0.6794	0.8246	0.7339	0.7449	0.6259	0.7804	0.6872	0.6626	0.7374	0.6604	0.9246	0.6717	0.8228	0.9751	0.7334
BBGM	2020	0.7250	0.6455	0.8780	0.7581	0.6927	0.9395	0.8859	0.7992	0.7456	0.8315	0.7878	0.7710	0.7650	0.7634	0.9820	0.8554	0.9678	0.9931	0.8215
NGM-v2	2021	0.6877	0.6331	0.8677	0.7013	0.6971	0.9467	0.8740	0.7737	0.7205	0.8067	0.7426	0.7253	0.7946	0.7340	0.9888	0.8123	0.9426	0.9867	0.8020
NHGM-v2	2021	0.6202	0.5781	0.8642	0.6846	0.6872	0.9335	0.8081	0.7656	0.6919	0.7987	0.6623	0.7171	0.7812	0.6953	0.9824	0.8444	0.9316	0.9926	0.7799
COMMON	2023	0.7730	0.6820	0.9200	0.7950	0.7040	0.9750	0.9160	0.8250	0.7220	0.8800	0.8000	0.7410	0.8340	0.8280	0.9990	0.8440	0.9820	0.9980	0.8450
COMMON+	2026	0.7980	0.7230	0.9170	0.7870	0.7080	0.9800	0.9180	0.8190	0.7280	0.8820	0.8330	0.7640	0.8340	0.8390	0.9990	0.8610	0.9920	0.9990	0.8550

ThinkMatch 包含以下基准数据集：

• PascalVOC-Keypoint
• Willow-Object-Class
• CUB2011
• SPair-71k
• IMC-PT-SparseGM

待办事项 我们计划未来包含以下数据集：

• 合成数据

ThinkMatch 支持以下图匹配设置：

• 2GM（双图匹配），每次仅匹配两个图
• MGM（多图匹配），可联合匹配多个图
• MGM3（混合模式多图匹配），在联合匹配多个图的同时支持不同类别的图混合匹配

快速开始

Docker（推荐）

获取推荐镜像：

docker pull runzhongwang/thinkmatch:torch1.6.0-cuda10.1-cudnn7-pygmtools0.5.1

其他PyTorch/CUDA组合版本也已提供。查看可用镜像：docker hub

详细说明见 ThinkMatch-runtime

手动配置（Ubuntu）

本项目基于Ubuntu 16.04、Python 3.7、Pytorch 1.6、cuda10.1、cudnn7和torch-geometric 1.6.3开发测试

1. 安装配置支持GPU的Pytorch 1.6

2. 安装ninja构建工具：apt-get install ninja-build

3. 安装Python依赖包：

   pip install tensorboardX scipy easydict pyyaml xlrd xlwt pynvml pygmtools
   

4. 安装LPMP构建工具：

   apt-get install -y findutils libhdf5-serial-dev git wget libssl-dev
   
   wget https://github.com/Kitware/CMake/releases/download/v3.19.1/cmake-3.19.1.tar.gz && tar zxvf cmake-3.19.1.tar.gz
   cd cmake-3.19.1 && ./bootstrap && make && make install
   

5. 安装构建LPMP：

   python -m pip install git+https://git@github.com/rogerwwww/lpmp.git
   

   需要安装gcc-9支持构建。示例安装配置：

   apt-get update
   apt-get install -y software-properties-common
   add-apt-repository ppa:ubuntu-toolchain-r/test
   
   apt-get install -y gcc-9 g++-9
   update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 60 --slave /usr/bin/g++ g++ /usr/bin/g++-9
   

6. 安装torch-geometric：

   export CUDA=cu101
   export TORCH=1.6.0
   /opt/conda/bin/pip install torch-scatter==2.0.5 -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
   /opt/conda/bin/pip install torch-sparse==0.6.8 -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
   /opt/conda/bin/pip install torch-cluster==1.5.8 -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
   /opt/conda/bin/pip install torch-spline-conv==1.2.0 -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
   /opt/conda/bin/pip install torch-geometric==1.6.3
   

7. 完成LPMP构建后，建议切换回gcc-7（项目基于gcc-7）：

   update-alternatives --remove gcc /usr/bin/gcc-9
   update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 --slave /usr/bin/g++ g++ /usr/bin/g++-7
   

可用数据集

注意：以下所有数据集均可通过pygmtools自动下载解压，若下载失败也可手动下载。

1. PascalVOC-关键点（Keypoint）

   1. 下载 VOC2011数据集 并确保路径为 data/PascalVOC/TrainVal/VOCdevkit/VOC2011

   2. 从 Berkeley服务器 或 google drive 下载关键点标注文件，并确保路径为 data/PascalVOC/annotations

   3. 训练/测试划分文件位于 data/PascalVOC/voc2011_pairs.npz。此文件需手动添加

   如使用PascalVOC-关键点数据集，请引用以下论文：

   @article{EveringhamIJCV10,
     title={The pascal visual object classes (voc) challenge},
     author={Everingham, Mark and Van Gool, Luc and Williams, Christopher KI and Winn, John and Zisserman, Andrew},
     journal={International Journal of Computer Vision},
     volume={88},
     pages={303–338},
     year={2010}
   }
   
   @inproceedings{BourdevICCV09,
     title={Poselets: Body part detectors trained using 3d human pose annotations},
     author={Bourdev, L. and Malik, J.},
     booktitle={International Conference on Computer Vision},
     pages={1365--1372},
     year={2009},
     organization={IEEE}
   }
   

2. Willow-Object-Class

   1. 从官网 或 hugging face 下载Willow-ObjectClass数据集

   2. 解压后确保路径为 data/WillowObject/WILLOW-ObjectClass

   如使用Willow-Object-Class数据集，请引用以下论文：

   @inproceedings{ChoICCV13,
     author={Cho, Minsu and Alahari, Karteek and Ponce, Jean},
     title = {Learning Graphs to Match},
     booktitle = {International Conference on Computer Vision},
     pages={25--32},
     year={2013}
   }
   

3. CUB2011

   1. 下载 CUB-200-2011数据集

   2. 解压后确保路径为 data/CUB_200_2011/CUB_200_2011

   如使用CUB2011数据集，请引用以下报告：

   @techreport{CUB2011,
     Title = {{The Caltech-UCSD Birds-200-2011 Dataset}},
     Author = {Wah, C. and Branson, S. and Welinder, P. and Perona, P. and Belongie, S.},
     Year = {2011},
     Institution = {California Institute of Technology},
     Number = {CNS-TR-2011-001}
   }
   

4. IMC-PT-SparseGM

   1. 从 google drive、百度网盘 (提取码: g2cj) 或 hugging face 下载IMC-PT-SparseGM数据集

   2. 解压后确保50个锚点（anchor points）路径为 data/IMC-PT-SparseGM/annotations，100个锚点路径为 data/IMC-PT-SparseGM/annotations_100

   如使用IMC-PT-SparseGM数据集，请引用以下论文：

   @article{JinIJCV21,
     title={Image Matching across Wide Baselines: From Paper to Practice},
     author={Jin, Yuhe and Mishkin, Dmytro and Mishchuk, Anastasiia and Matas, Jiri and Fua, Pascal and Yi, Kwang Moo and Trulls, Eduard},
     journal={International Journal of Computer Vision},
     pages={517--547},
     year={2021}
   }
   
   
   @InProceedings{WangCVPR23,
       author    = {Wang, Runzhong and Guo, Ziao and Jiang, Shaofei and Yang, Xiaokang and Yan, Junchi},
       title     = {Deep Learning of Partial Graph Matching via Differentiable Top-K},
       booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
       month     = {June},
       year      = {2023}
   }
   

5. SPair-71k

   1. 下载 SPair-71k数据集

   2. 解压后确保路径为 data/SPair-71k

   如使用SPair-71k数据集，请引用以下论文：

   @article{min2019spair,
      title={SPair-71k: A Large-scale Benchmark for Semantic Correspondence},
      author={Juhong Min and Jongmin Lee and Jean Ponce and Minsu Cho},
      journal={arXiv prepreint arXiv:1908.10543},
      year={2019}
   }
   
   @InProceedings{min2019hyperpixel, 
      title={Hyperpixel Flow: Semantic Correspondence with Multi-layer Neural Features},
      author={Juhong Min and Jongmin Lee and Jean Ponce and Minsu Cho},
      booktitle={ICCV},
      year={2019}
   }
   

更多详情请访问 pygmtools。

运行实验

执行训练和评估：

python train_eval.py --cfg path/to/your/yaml

将 path/to/your/yaml 替换为配置文件路径，例如：

python train_eval.py --cfg experiments/vgg16_pca_voc.yaml

默认配置文件存储在 experiments/ 目录，欢迎尝试自定义配置。如发现更优配置，请提交Issue或PR告知，我们将更新基准！

预训练模型

ThinkMatch 提供预训练模型。权重文件可通过 google drive 获取。

使用预训练模型时，请先下载权重文件，然后在yaml配置文件中添加：

PRETRAINED_PATH: path/to/your/pretrained/weights

社区交流

如有问题或遇到异常，请在GitHub提交Issue。

我们还提供以下交流渠道：

• Discord (英文用户)：

  

• QQ群(中文用户)：696401889

  

引用 ThinkMatch

如果您在研究中使用了任何模型，请引用相应的论文（每个模型的 BibTeX 引用（参考文献引用）可在 models/ 目录中找到）。

如果您喜欢该框架，也可以引用其底层库 pygmtools（在训练和测试期间调用的库）：

@article{wang2024pygm,
  author  = {Runzhong Wang and Ziao Guo and Wenzheng Pan and Jiale Ma and Yikai Zhang and Nan Yang and Qi Liu and Longxuan Wei and Hanxue Zhang and Chang Liu and Zetian Jiang and Xiaokang Yang and Junchi Yan},
  title   = {Pygmtools: A Python Graph Matching Toolkit},
  journal = {Journal of Machine Learning Research},
  year    = {2024},
  volume  = {25},
  number  = {33},
  pages   = {1-7},
  url     = {https://jmlr.org/papers/v25/23-0572.html},
}

ThinkMatch 快速上手指南

---

环境准备

系统要求

• 操作系统：Linux/macOS（推荐Ubuntu 18.04+）
• Python：3.7-3.10
• PyTorch：1.8.0+
• 硬件：GPU（推荐NVIDIA显卡，CUDA 11.1+）

前置依赖

# 安装基础依赖（推荐使用国内镜像加速）
pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install pygmtools numpy scipy matplotlib -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装编译依赖（Ubuntu）
sudo apt-get install build-essential cmake g++

---

安装步骤

方式一：Docker（推荐）

# 拉取镜像（使用阿里云加速器）
docker pull registry.cn-hangzhou.aliyuncs.com/runzhongwang/thinkmatch:latest

# 创建容器
docker run --gpus all -it --name thinkmatch_container registry.cn-hangzhou.aliyuncs.com/runzhongwang/thinkmatch:latest /bin/bash

方式二：源码安装

# 克隆仓库（使用国内镜像加速）
git clone https://hub.fastgit.org/Thinklab-SJTU/ThinkMatch.git
cd ThinkMatch

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

# 编译扩展（可选）
python setup.py build_ext --inplace

---

基本使用

运行预训练模型（以GMN为例）

# 下载预训练模型（需在容器内或源码目录执行）
mkdir -p pretrained && cd pretrained
wget https://thinkmatch.readthedocs.io/en/latest/_downloads/gmn_model.pth

# 运行推理示例
cd ../examples
python gmn_inference.py \
  --model_path ../pretrained/gmn_model.pth \
  --image1 ../data/test_images/airplane1.jpg \
  --image2 ../data/test_images/airplane2.jpg

输出结果

程序会输出匹配的节点对应关系，并生成可视化结果图matching_result.png。

---

验证安装

# 运行单元测试（可选）
cd ThinkMatch
python -m pytest tests/test_gm.py -v

注意：完整数据集和训练流程请参考官方文档