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)

패키지에는 설치 후 직접 호출할 수 있는 작은 헬퍼 스크립트가 포함되어 있습니다:

# 두 이미지 매칭
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