Tarekbouamer / imm

ImMatch (IMM) is a user-friendly library for extracting and matching image features, ideal for applications like visual localization, augmented reality, and 3D reconstruction.

ImMatch (IMM) 🖼️

ImMatch (IMM) is a versatile library for image matching and feature extraction in computer vision applications. It provides algorithms to detect, describe, and match keypoints between images, as well as estimate geometric relationships, making it ideal for tasks such as visual localization, augmented reality, and 3D reconstruction.

Table of Contents 📑

• Prerequisites
• Installation 🖥️
• Running with Docker 🐳
• Supported Algorithms
  • Extractors
  • Matchers
  • Estimators
• Usage
  • Feature Extraction
  • Feature Matching
  • Geometric Estimation

Prerequisites

Before installing ImMatch, ensure you have the following:

• Python 3.8 or later
• Conda
• CUDA Toolkit

Installation 🖥️

1. Clone the Repository

git clone https://github.com/Tarekbouamer/imm.git
cd imm

2. Set Up a Conda Environment

conda create -n imm python=3.8 -y
conda activate imm

3. Install Dependencies

python -m pip install --upgrade pip
pip install torch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 --index-url https://download.pytorch.org/whl/cu118

4. Install ImMatch

pip install .[optional]

Running with Docker 🐳

For those who prefer using Docker, we provide a Dockerfile to set up ImMatch in a containerized environment.

1. Build the Docker image:

docker build -t imm:latest .

2. Run the Docker container:

docker run -it --gpus all imm:latest

Supported Algorithms

ImMatch supports a wide range of feature extractors, matchers, and geometric estimators. Here's an overview:

Supported Extractors

Extractor Name	Type	Description
SuperPoint
D2-Net
R2D2
DISK

Supported Matchers

Matcher Name	Type	Description
SuperGlue
LoFTR

Supported Estimators

Estimator Name	Description
Fundamental Matrix
Essential Matrix
Homography
PnP

Usage

ImMatch provides command-line tools for feature extraction, matching, and geometric estimation. Here are the main commands:

Feature Extraction

Use the imm-extract script to extract features from an image:

imm-extract --model MODEL_NAME --img_path PATH_TO_IMAGE --max_keypoints MAX_KEYPOINTS

Example:

imm-extract --model superpoint --img_path /path/to/your/image.jpg --max_keypoints 1200

Feature Matching

Use the imm-match script to match features between two images:

imm-match IMG0_PATH IMG1_PATH [OPTIONS]

Options:

• --matcher: Matcher name (default: "superglue_outdoor")
• --extractor: Extractor name (default: "superpoint")
• --max_size: Max image size (optional)
• --output_dir: Output directory for logs and visualization (default: "output")
• --threshold: Matching score threshold (default: 0.1)
• --visualize/--no-visualize: Enable or disable visualization (default: True)
• --use_gpu/--no-gpu: Use GPU if available (default: True)

Example:

imm-match path/to/image1.jpg path/to/image2.jpg --matcher superglue_outdoor --extractor superpoint --max_size 1000 --output_dir my_results --threshold 0.2 --visualize --use_gpu