vismatch – 图像匹配模型的统一 Python 库

🎯 功能简介

vismatch 提供了一个单一、易于使用的 Python API（以及一个小型 CLI），封装了 50 多种图像匹配方法——从经典的 SIFT 等关键点检测器到现代的深度学习匹配器，如 LoFTR、SuperPoint‑LightGlue、DeDoDe、SphereGlue 等。该库处理：

自动下载模型权重（通过 Hugging Face 或作者发布）。
加载和预处理图像（可选调整大小）。
运行匹配（生成关键点对应关系、单应矩阵、内点数量、置信度分数）。
提取原始关键点和描述符。
可视化结果，使用现成的 plot_matches 和 plot_keypoints 辅助函数。

所有这些都通过一个函数 get_matcher(name, device=…) 暴露，因此您可以用一行代码切换模型。

🛠️ 快速开始

# 推荐：uv（快速安装器）——pip 也可以
pip install uv               # 如果没有 uv，请先安装
uv venv                      # 创建虚拟环境
source .venv/bin/activate    # 激活虚拟环境
uv pip install vismatch       # 安装库

可选：为需要额外依赖的模型安装额外依赖（例如 torch‑geometric、tensorflow）：

uv pip install "[all]"   # 或 pip install .[all]

💻 快速代码示例

from vismatch import get_matcher
from vismatch.viz import plot_matches

# 选择任意 50 多种匹配器——这里使用 GPU 上的 SuperPoint‑LightGlue
matcher = get_matcher("superpoint-lightglue", device="cuda")

# 加载图像，可选调整大小
img0 = matcher.load_image("vismatch/assets/example_pairs/outdoor/montmartre_close.jpg", resize=512)
img1 = matcher.load_image("vismatch/assets/example_pairs/outdoor/montmartre_far.jpg",   resize=512)

# 运行匹配
result = matcher(img0, img1)
# result 包含键，如：num_inliers, H, all_kpts0, all_kpts1, matched_kpts0, …

# 可视化匹配结果
plot_matches(img0, img1, result, save_path="plot_matches.png")

相同的工作流程也适用于通过 matcher.extract(img) 和 plot_keypoints 进行关键点提取。

📦 命令行界面（CLI）

该包附带小型辅助脚本，安装后可直接调用：

# 匹配两张图像
vismatch-match \
    --matcher superpoint-lightglue \
    --out-dir outputs/sp-lg \
    --input img0.jpg img1.jpg

# 从文件夹提取关键点
vismatch-extract \
    --matcher superpoint-lightglue \
    --out-dir outputs/sp-lg \
    --input path/to/images/

CLI 接受单个图像、目录或列出图像对的文件。

📚 模型目录

该库将支持的方法分为三个系列：

密集 – 例如 roma、tiny-roma、duster。
半密集 – 例如 loftr、eloftr、matchformer。
稀疏 – 经典和现代基于关键点的流水线，如 sift-lightglue、superpoint-lightglue、disk-lightglue、dedode、sphereglue、zippypoint 等。

包含运行时、设备支持、源代码仓库和许可证详细信息的完整列表位于 模型详情 文档页面。

🤝 贡献 / 扩展

如果您有新的匹配器，仓库提供了 CONTRIBUTING 指南。设计遵循 PyTorch 的“可用性优先于性能”原则：目标是提供干净、一致的 API，而不是榨取每一毫秒。

📖 文档与资源

ReadTheDocs – https://vismatch.readthedocs.io/en/latest/
Colab 演示 – README 中链接的即用笔记本。
Hugging Face 模型中心 – 所有封装的权重都托管在 vismatch 组织下。
下载统计 – 实时跟踪器显示每日 HF 模型下载量。

📜 引用

如果您在研究中使用 vismatch，请按照 README 中的说明引用随附的 EarthMatch 论文（CVPR 2024 研讨会）。

TL;DR

vismatch 是一个真实的、生产就绪的 Python 包，它将大量图像匹配算法统一到单一、对初学者友好的界面后面，使得实验、基准测试或集成最先进的视觉对应方法变得轻而易举。

gmberton/vismatch