Image Matching WebUI
两幅图像间的关键点匹配

简介

Image Matching WebUI (IMCUI) 是一款高效的图像匹配工具，集成了多种著名的图像匹配算法（Image Matching Algorithms）。该工具采用 gradio 设计了图形用户界面（Graphical User Interface, GUI）。您可以轻松选择两幅图像和一个匹配算法，即可获得精确的匹配结果。 注意：图像来源可以是本地图像或摄像头实时采集的图像。

在线体验：

工具演示视频：

https://github.com/Vincentqyw/image-matching-webui/assets/18531182/263534692-c3484d1b-cc00-4fdc-9b31-e5b7af07ecd9

该工具目前支持多种主流的图像匹配算法，具体如下：

使用方法

HuggingFace / Lightning AI

直接在 上试用

或按照以下说明在本地部署。

环境要求

• Python 3.10+

通过 pip 安装 [新增]

更新：现在支持从 pip 安装，只需运行：

pip install imcui

从源码安装

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 .

或使用 docker：

docker pull vincentqin/image-matching-webui:latest

# 启动 WebUI 服务
docker-compose up webui

# 或在后台运行
docker-compose up -d webui

# 构建并启动 WebUI 服务
docker-compose up --build webui

# 检查 WebUI 服务状态
docker-compose ps webui

# 查看 WebUI 服务日志
docker-compose logs webui
docker-compose logs -f webui  # 实时跟踪日志

# 停止 WebUI 服务
docker-compose stop webui

# 重启 WebUI 服务
docker-compose restart webui

# 删除 WebUI 服务容器
docker-compose rm webui

# 删除所有容器
docker-compose down

部署到 Railway

部署到 Railway，在 Deploy 部分设置 Custom Start Command：

python -m imcui.api.server

运行演示

# 使用包命令行界面（推荐）
imcui

# 或直接运行脚本
python app.py

然后在浏览器中打开 http://localhost:7860。

命令行界面

imcui 包提供了强大的命令行界面，包含多种选项：

基本用法

# 安装包
pip install imcui

# 使用默认设置运行
imcui

# 使用详细输出运行
imcui --verbose

# 在指定端口运行
imcui -p 7860

# 在指定主机运行
imcui -s 127.0.0.1

# 帮助
imcui --help

命令行选项

添加你自己的特征（feature）/匹配器（matcher）

我提供了一个在 imcui/hloc/extractors/example.py 中添加局部特征（local feature）的示例。然后在文件 imcui/hloc/extract_features.py 中的 confs 添加特征设置。最后一步是在你的配置文件中向 matcher_zoo 添加一些设置。

配置文件位置（按优先级排序）：

1. 使用 --config 参数指定的自定义配置文件
2. 当前目录下的 config.yaml
3. 当前目录下 config/config.yaml
4. 包默认配置（imcui/config/app.yaml）

上传模型

IMCUI 将所有模型托管在 Huggingface 上。你可以将模型上传到 Huggingface 并添加到 Realcat/imcui_checkpoints 仓库。

欢迎贡献！

非常欢迎外部贡献。请使用 flake8 等 linter 遵循 PEP8 风格指南。以下是可能有价值的功能添加的非详尽列表：

• 支持 pip 安装命令
• 添加 CPU CI
• 添加摄像头支持
• 添加 线段特征匹配 算法
• 添加新特征提取器/匹配器的示例
• 使用 RANSAC（Random Sample Consensus，随机抽样一致性）过滤异常值
• 在匹配前添加 旋转图像 选项
• 支持将匹配结果导出到 COLMAP（#issue 6）
• 添加配置文件以设置默认参数
• 动态加载模型并减少 GPU 负载

将局部特征/匹配器作为子模块（submodule）添加非常容易。例如，要添加 GlueStick：

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

如果远程子模块仓库有更新，别忘了使用以下命令拉取子模块：

git submodule update --init --recursive  # 初始化和下载
git submodule update --remote  # 更新

如果你只想更新一个子模块，使用 git submodule update --remote imcui/third_party/GlueStick。

要删除子模块，请按照以下步骤操作：

git submodule deinit -f imcui/third_party/GlueStick
git rm -f imcui/third_party/GlueStick
rm -rf .git/modules/imcui/third_party/GlueStick
git add .gitmodules && \
git commit -m "Remove submodule imcui/third_party/dust3r"

在提交前格式化代码，运行：

pre-commit run -a  # 自动检查和修复

贡献者

资源

• Image Matching: Local Features & Beyond
• Long-term Visual Localization

致谢

本代码基于 Hierarchical-Localization 构建。我们向原作者致以诚挚的感谢，感谢他们提供的宝贵源代码。

Image Matching WebUI 快速上手指南

环境准备

系统要求

• Python: 3.10 或更高版本
• 操作系统: Linux / macOS / Windows（推荐 Linux）
• GPU: 可选，支持 CUDA 加速

前置依赖

• conda 或 miniconda（推荐）
• Docker（可选，用于容器化部署）
• Git

安装步骤

方式一：pip 安装（推荐，最简单）

# 使用清华镜像源加速（国内推荐）
pip install imcui -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用官方源
pip install imcui

方式二：源码安装

# 克隆仓库（包含子模块）
git clone --recursive https://github.com/Vincentqyw/image-matching-webui.git
cd image-matching-webui

# 创建 conda 环境
conda env create -f environment.yaml
conda activate imcui

# 安装包
pip install -e .

方式三：Docker 安装

# 拉取镜像（国内可使用 DaoCloud 等镜像加速）
docker pull vincentqin/image-matching-webui:latest

# 启动服务
docker-compose up webui

# 后台运行
docker-compose up -d webui

基本使用

启动 WebUI

# 方式 1：使用 CLI 命令（推荐）
imcui

# 方式 2：直接运行脚本
python app.py

服务启动后，在浏览器中打开：http://localhost:7860

常用启动参数

# 指定端口
imcui -p 8080

# 指定主机地址
imcui -s 127.0.0.1

# 启用详细日志
imcui --verbose

# 查看帮助
imcui --help

快速体验（无需本地安装）

直接访问在线演示：

• 🤗 Hugging Face Spaces
• ⚡ Lightning AI Studio

使用流程

1. 上传图片：选择两张待匹配的图像（支持本地上传或摄像头拍摄）
2. 选择算法：从下拉菜单中选择特征提取器和匹配算法
3. 运行匹配：点击匹配按钮，查看关键点对应结果
4. 导出结果：支持可视化结果导出

支持的算法

完整算法列表见项目 README。