vismatch – 画像マッチングモデルのための統合 Python ライブラリ

🎯 機能概要

vismatch は、50 以上の画像マッチング手法（古典的な SIFT などのキーポイント検出器から、LoFTR、SuperPoint‑LightGlue、DeDoDe、SphereGlue などの最新の深層学習マッチャーまで）をラップする、単一で使いやすい Python API（および小さな CLI）を提供します。ライブラリは以下を処理します：

モデル重みの自動ダウンロード（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）

パッケージには、インストール後に直接呼び出せる小さなヘルパースクリプトが含まれています：

# 2 つの画像をマッチング
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 は、単一の画像、ディレクトリ、または画像ペアをリストしたテキストファイルを受け入れます。

📚 モデルカタログ

ライブラリは、サポートされているメソッドを 3 つのファミリーにグループ化しています：

高密度 – 例：roma、tiny-roma、duster。
半高密度 – 例：loftr、eloftr、matchformer。
スパース – 古典的および現代的なキーポイントベースのパイプライン（例：sift-lightglue、superpoint-lightglue、disk-lightglue、dedode、sphereglue、zippypoint など）。

ランタイム、デバイスサポート、ソースリポジトリ、ライセンスの詳細を含む完全なリストは、モデル詳細 ドキュメントページにあります。

🤝 貢献 / 拡張

新しいマッチャーがある場合は、リポジトリに CONTRIBUTING ガイドが用意されています。設計は PyTorch の「パフォーマンスよりも使いやすさ」の原則に従っています。目標は、クリーンで一貫性のある API を提供することであり、最後の 1 ミリ秒を絞り出すことではありません。

📖 ドキュメントとリソース

ReadTheDocs – https://vismatch.readthedocs.io/en/latest/
Colab デモ – README からリンクされているすぐに実行できるノートブック。
Hugging Face モデルハブ – すべてのラップされた重みは vismatch 組織の下でホストされています。
ダウンロード統計 – ライブトラッカーが毎日の HF モデルダウンロード数を表示します。

📜 引用

研究で vismatch を使用する場合は、README に示されているように、付随する EarthMatch 論文（CVPR 2024 ワークショップ）を引用してください。

TL;DR

vismatch は、多数の画像マッチングアルゴリズムを単一の初心者に優しいインターフェースの背後に統合した、本格的で本番環境に対応した Python パッケージであり、最先端の視覚対応メソッドを簡単に実験、ベンチマーク、統合できるようにします。

gmberton/vismatch