RealCat

· 7 min read

项目：Image Matching WebUI，一站式图像匹配工具箱

做局部特征与图像匹配研究的同学大概都有过这样的经历：想对比 SuperGlue、LoFTR 和 RoMa 在同一对图像上的表现，于是克隆三个仓库、配三套环境、下载三份权重、再各写一段可视化脚本。等到都跑通，一个下午已经过去了。

Image Matching WebUI（简称 IMCUI）就是为了消灭这个下午而写的。它把几十种匹配算法封装在统一的接口之后，配上一个 Gradio 网页界面：上传或拍摄两张图片，从下拉框里选一个算法，点击 Run，关键点、匹配线、RANSAC 之后的内点和估计出的单应矩阵（或基础矩阵）就都呈现在眼前。

IMCUI 界面

项目从 2023 年 6 月开始维护，目前已有 1300 余个 star，并被打包发布到 PyPI、Docker Hub 和 Hugging Face Spaces。

先试一下

最省事的方式是打开 Hugging Face Space，不需要安装任何东西。下面是一段演示：

界面分两栏：左侧依次是算法选择、输入图像和匹配参数（关键点数量、匹配阈值、RANSAC 方法与重投影阈值、几何模型），右侧是结果面板，包括原始匹配、几何验证后的匹配，以及按估计的单应变换把图 A 扭到图 B 坐标系下的叠加图。

支持的算法

IMCUI 的核心价值在于「全」。截至写作时已经集成了近 50 种方法，覆盖从 2004 年的 SIFT 到 2026 年的 LoMa、RaCo：

类别代表方法
传统特征SIFT
学习型局部特征（检测 + 描述）SuperPoint、D2-Net、R2D2、DISK、ALIKE、ALIKED、DeDoDe、XFeat、DarkFeat、RIPE、RDD、LiftFeat、DaD
学习型描述子HardNet、SOSNet
稀疏匹配器SuperGlue、LightGlue、SGMNet、IMP、OmniGlue、SphereGlue
稠密（detector-free）匹配LoFTR、EfficientLoFTR、XoFTR、AspanFormer、TopicFM、CoTR、DKM、RoMa、GIM、MINIMA、LoMa、RaCo
双目基础模型DUSt3R、MASt3R
线特征SOLD2、GlueStick

每种算法的会议来源、论文和代码链接都写在配置文件里，界面的「support algos」表格由配置自动生成。不同方法的运行开销差别很大，配置里用 efficiency: low / medium / high 做了标注，方便在 CPU 环境下避开最重的模型。

模型权重统一托管在 Realcat/imcui_checkpoints，首次使用某个算法时按需下载并缓存，所以不会一启动就把几十 GB 的权重全部拉下来。

安装与运行

要求 Python 3.10 以上。三种安装方式任选其一。

pip，最简单：

pip install imcui
imcui            # 默认监听 0.0.0.0:7860

源码，适合要改代码或者加新算法的情况：

git clone --recursive https://github.com/Vincentqyw/image-matching-webui.git
cd image-matching-webui
conda env create -f environment.yaml
conda activate imcui
pip install -e .
python app.py

Docker，适合部署到服务器：

docker pull vincentqin/image-matching-webui:latest
docker-compose up -d webui

启动后浏览器打开 http://localhost:7860 即可。命令行支持 -p 指定端口、-s 指定监听地址、-c 指定配置文件、-d 指定示例数据目录，imcui --help 可以看到完整列表。

配置文件按以下优先级查找：--config 指定的路径、当前目录的 config.yaml、当前目录的 config/config.yaml，最后才是包内置的 imcui/config/app.yaml。把默认配置复制一份出来改，就能调整默认阈值、关掉用不到的模型。

作为服务调用

除了网页，IMCUI 还带一个基于 FastAPI 的 HTTP 服务，方便把匹配能力嵌进自己的流程里：

python -m imcui.api.server     # 默认 8001 端口

提供三个接口：

  • GET /version：返回版本号。
  • POST /v1/extract：对一批 base64 编码的图像提取关键点、描述子与分数，可指定最大关键点数、缩放和旋转。
  • POST /v1/match：上传两张图片，返回两图关键点与匹配索引。

仓库中的 imcui/api/client.py 是一个完整的客户端示例。部署到 Railway 这类平台时，把启动命令设为上面那一行就行。

接入自己的匹配器

IMCUI 建立在 Hierarchical-Localization（hloc）的代码结构之上，所以加一个新方法的流程和在 hloc 里加 extractor 或 matcher 是一样的：

  1. 以 imcui/hloc/extractors/example.py 为模板实现特征提取（或匹配）类。
  2. 在 imcui/hloc/extract_features.py 的 confs 里登记默认参数。
  3. 在配置文件的 matcher_zoo 下加一个条目，填上显示名称、来源、论文与代码链接。

第三方代码通常以 git submodule 的形式放在 imcui/third_party/ 下，例如：

git submodule add https://github.com/cvg/GlueStick.git imcui/third_party/GlueStick

仓库里的 CLAUDE.md 和 .claude/skills/integrate-matcher/ 写了一份逐步指南，用 Claude Code 之类的工具可以半自动完成集成。

几点设计上的取舍

  • 按需加载模型：几十个模型不可能同时常驻显存，imcui/ui/modelcache.py 维护一个模型缓存，只在选中时加载，用不到的模型会被释放。
  • RANSAC 作为后处理：所有匹配结果都可以经过 OpenCV 的 USAC_MAGSAC 等方法做几何验证，默认估计单应矩阵，也可以切换成基础矩阵。这样不同算法的对比是在同一套几何约束下进行的。
  • CPU CI：GitHub Actions 在仅有 CPU 的环境里把未标记 skip_ci 的算法各跑一遍，保证集成的方法不会悄悄坏掉。

后续计划

还没做完的事情包括：匹配前自动估计图像旋转、把匹配结果导出为 COLMAP 数据库格式（issue #6）。欢迎提 PR。相关资料可以参考 Image Matching Workshop 与 Long-term Visual Localization 两个基准站点。