README.md

---
title: Image Matching Webui
emoji: 🤗
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 5.4.0
app_file: app.py
pinned: true
license: apache-2.0
---
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]

<p align="center">
  <h1 align="center"><br><ins>Image Matching WebUI</ins>
  <br>Matching Keypoints between two images</h1>
</p>
<div align="center">
  <a target="_blank" href="https://github.com/Vincentqyw/image-matching-webui/actions/workflows/release.yml"><img src="https://github.com/Vincentqyw/image-matching-webui/actions/workflows/release.yml/badge.svg" alt="PyPI Release"></a>
  <a target="_blank" href='https://huggingface.co/spaces/Realcat/image-matching-webui'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue'></a>
  <a target="_blank" href="https://pypi.org/project/imcui"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/imcui?style=flat&logo=pypi&label=imcui&link=https%3A%2F%2Fpypi.org%2Fproject%2Fimcui"></a>
  <a target="_blank" href="https://hub.docker.com/r/vincentqin/image-matching-webui"><img alt="Docker Image Version" src="https://img.shields.io/docker/v/vincentqin/image-matching-webui?sort=date&arch=amd64&logo=docker&label=imcui&link=https%3A%2F%2Fhub.docker.com%2Fr%2Fvincentqin%2Fimage-matching-webui"></a>
   <a target="_blank" href="https://pepy.tech/projects/imcui"><img src="https://static.pepy.tech/badge/imcui" alt="PyPI Downloads"></a>

</div>

## Description

`Image Matching WebUI (IMCUI)` efficiently matches image pairs using multiple famous image matching algorithms. The tool features a Graphical User Interface (GUI) designed using [gradio](https://gradio.app/). You can effortlessly select two images and a matching algorithm and obtain a precise matching result.
**Note**: the images source can be either local images or webcam images.

Try it on
<a href='https://huggingface.co/spaces/Realcat/image-matching-webui'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue'></a>
<a target="_blank" href="https://lightning.ai/realcat/studios/image-matching-webui"><img src="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/app-2/studio-badge.svg" alt="Open In Studio"/></a>

Here is a demo of the tool:

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

The tool currently supports various popular image matching algorithms, namely:

| Algorithm        | Supported | Conference/Journal | Year | GitHub Link |
|------------------|-----------|--------------------|------|-------------|
| MINIMA         | ✅ | ARXIV   | 2024 | [Link](https://github.com/LSXI7/MINIMA) |
| XoFTR          | ✅ | CVPR    | 2024 | [Link](https://github.com/OnderT/XoFTR) |
| EfficientLoFTR | ✅ | CVPR    | 2024 | [Link](https://github.com/zju3dv/EfficientLoFTR) |
| MASt3R         | ✅ | CVPR    | 2024 | [Link](https://github.com/naver/mast3r) |
| DUSt3R         | ✅ | CVPR    | 2024 | [Link](https://github.com/naver/dust3r) |
| OmniGlue       | ✅ | CVPR    | 2024 | [Link](https://github.com/Vincentqyw/omniglue-onnx) |
| XFeat          | ✅ | CVPR    | 2024 | [Link](https://github.com/verlab/accelerated_features) |
| RoMa           | ✅ | CVPR    | 2024 | [Link](https://github.com/Vincentqyw/RoMa) |
| DeDoDe         | ✅ | 3DV     | 2024 | [Link](https://github.com/Parskatt/DeDoDe) |
| Mickey         | ❌ | CVPR    | 2024 | [Link](https://github.com/nianticlabs/mickey) |
| GIM            | ✅ | ICLR    | 2024 | [Link](https://github.com/xuelunshen/gim) |
| ALIKED         | ✅ | ICCV    | 2023 | [Link](https://github.com/Shiaoming/ALIKED) |
| LightGlue      | ✅ | ICCV    | 2023 | [Link](https://github.com/cvg/LightGlue) |
| DarkFeat       | ✅ | AAAI    | 2023 | [Link](https://github.com/THU-LYJ-Lab/DarkFeat) |
| SFD2           | ✅ | CVPR    | 2023 | [Link](https://github.com/feixue94/sfd2) |
| IMP            | ✅ | CVPR    | 2023 | [Link](https://github.com/feixue94/imp-release) |
| ASTR           | ❌ | CVPR    | 2023 | [Link](https://github.com/ASTR2023/ASTR) |
| SEM            | ❌ | CVPR    | 2023 | [Link](https://github.com/SEM2023/SEM) |
| DeepLSD        | ❌ | CVPR    | 2023 | [Link](https://github.com/cvg/DeepLSD) |
| GlueStick      | ✅ | ICCV    | 2023 | [Link](https://github.com/cvg/GlueStick) |
| ConvMatch      | ❌ | AAAI    | 2023 | [Link](https://github.com/SuhZhang/ConvMatch) |
| LoFTR          | ✅ | CVPR    | 2021 | [Link](https://github.com/zju3dv/LoFTR) |
| SOLD2          | ✅ | CVPR    | 2021 | [Link](https://github.com/cvg/SOLD2) |
| LineTR         | ❌ | RA-L    | 2021 | [Link](https://github.com/yosungho/LineTR) |
| DKM            | ✅ | CVPR    | 2023 | [Link](https://github.com/Parskatt/DKM) |
| NCMNet         | ❌ | CVPR    | 2023 | [Link](https://github.com/xinliu29/NCMNet) |
| TopicFM        | ✅ | AAAI    | 2023 | [Link](https://github.com/Vincentqyw/TopicFM) |
| AspanFormer    | ✅ | ECCV    | 2022 | [Link](https://github.com/Vincentqyw/ml-aspanformer) |
| LANet          | ✅ | ACCV    | 2022 | [Link](https://github.com/wangch-g/lanet) |
| LISRD          | ❌ | ECCV    | 2022 | [Link](https://github.com/rpautrat/LISRD) |
| REKD           | ❌ | CVPR    | 2022 | [Link](https://github.com/bluedream1121/REKD) |
| CoTR           | ✅ | ICCV    | 2021 | [Link](https://github.com/ubc-vision/COTR) |
| ALIKE          | ✅ | TMM     | 2022 | [Link](https://github.com/Shiaoming/ALIKE) |
| RoRD           | ✅ | IROS    | 2021 | [Link](https://github.com/UditSinghParihar/RoRD) |
| SGMNet         | ✅ | ICCV    | 2021 | [Link](https://github.com/vdvchen/SGMNet) |
| SuperPoint     | ✅ | CVPRW   | 2018 | [Link](https://github.com/magicleap/SuperPointPretrainedNetwork) |
| SuperGlue      | ✅ | CVPR    | 2020 | [Link](https://github.com/magicleap/SuperGluePretrainedNetwork) |
| D2Net          | ✅ | CVPR    | 2019 | [Link](https://github.com/Vincentqyw/d2-net) |
| R2D2           | ✅ | NeurIPS | 2019 | [Link](https://github.com/naver/r2d2) |
| DISK           | ✅ | NeurIPS | 2020 | [Link](https://github.com/cvlab-epfl/disk) |
| Key.Net        | ❌ | ICCV    | 2019 | [Link](https://github.com/axelBarroso/Key.Net) |
| OANet          | ❌ | ICCV    | 2019 | [Link](https://github.com/zjhthu/OANet) |
| SOSNet         | ✅ | CVPR    | 2019 | [Link](https://github.com/scape-research/SOSNet) |
| HardNet        | ✅ | NeurIPS | 2017 | [Link](https://github.com/DagnyT/hardnet) |
| SIFT           | ✅ | IJCV    | 2004 | [Link](https://docs.opencv.org/4.x/da/df5/tutorial_py_sift_intro.html) |


## How to use

### HuggingFace / Lightning AI

Just try it on <a href='https://huggingface.co/spaces/Realcat/image-matching-webui'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue'></a>
<a target="_blank" href="https://lightning.ai/realcat/studios/image-matching-webui">
  <img src="https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/app-2/studio-badge.svg" alt="Open In Studio"/>
</a>

or deploy it locally following the instructions below.

### Requirements

- [Python 3.9+](https://www.python.org/downloads/)

#### Install from pip [NEW]

Update: now support install from [pip](https://pypi.org/project/imcui), just run:

```bash
pip install imcui
```

#### Install from source

``` bash
git clone --recursive https://github.com/Vincentqyw/image-matching-webui.git
cd image-matching-webui
conda env create -f environment.yaml
conda activate imw
pip install -e .
```

or using [docker](https://hub.docker.com/r/vincentqin/image-matching-webui):

``` bash
docker pull vincentqin/image-matching-webui:latest
docker run -it -p 7860:7860 vincentqin/image-matching-webui:latest python app.py --server_name "0.0.0.0" --server_port=7860
```

### Deploy to Railway

Deploy to [Railway](https://railway.app/), setting up a `Custom Start Command` in `Deploy` section:

``` bash
python -m imcui.api.server
```

### Run demo
``` bash
python app.py --config ./config/config.yaml
```
then open http://localhost:7860 in your browser.

![](assets/gui.jpg)

### Add your own feature / matcher

I provide an example to add local feature in [imcui/hloc/extractors/example.py](imcui/hloc/extractors/example.py). Then add feature settings in `confs` in file [imcui/hloc/extract_features.py](imcui/hloc/extract_features.py). Last step is adding some settings to `matcher_zoo` in file [imcui/ui/config.yaml](imcui/ui/config.yaml).

### Upload models

IMCUI hosts all models on [Huggingface](https://huggingface.co/Realcat/imcui_checkpoints).  You can upload your model to Huggingface and add it to the [Realcat/imcui_checkpoints](https://huggingface.co/Realcat/imcui_checkpoints) repository.


## Contributions welcome!

External contributions are very much welcome. Please follow the [PEP8 style guidelines](https://www.python.org/dev/peps/pep-0008/) using a linter like flake8. This is a non-exhaustive list of features that might be valuable additions:

- [x] support pip install command
- [x] add [CPU CI](.github/workflows/ci.yml)
- [x] add webcam support
- [x] add [line feature matching](https://github.com/Vincentqyw/LineSegmentsDetection) algorithms
- [x] example to add a new feature extractor / matcher
- [x] ransac to filter outliers
- [ ] add [rotation images](https://github.com/pidahbus/deep-image-orientation-angle-detection) options before matching
- [ ] support export matches to colmap ([#issue 6](https://github.com/Vincentqyw/image-matching-webui/issues/6))
- [x] add config file to set default parameters
- [x] dynamically load models and reduce GPU overload

Adding local features / matchers as submodules is very easy. For example, to add the [GlueStick](https://github.com/cvg/GlueStick):

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

If remote submodule repositories are updated, don't forget to pull submodules with:

``` bash
git submodule update --init --recursive  # init and download
git submodule update --remote  # update
```

if you only want to update one submodule, use `git submodule update --remote imcui/third_party/GlueStick`.

To format code before committing, run:

```bash
pre-commit run -a  # Auto-checks and fixes
```

## Contributors

<a href="https://github.com/Vincentqyw/image-matching-webui/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=Vincentqyw/image-matching-webui" />
</a>

## Resources
- [Image Matching: Local Features & Beyond](https://image-matching-workshop.github.io)
- [Long-term Visual Localization](https://www.visuallocalization.net)

## Acknowledgement

This code is built based on [Hierarchical-Localization](https://github.com/cvg/Hierarchical-Localization). We express our gratitude to the authors for their valuable source code.

[contributors-shield]: https://img.shields.io/github/contributors/Vincentqyw/image-matching-webui.svg?style=for-the-badge
[contributors-url]: https://github.com/Vincentqyw/image-matching-webui/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/Vincentqyw/image-matching-webui.svg?style=for-the-badge
[forks-url]: https://github.com/Vincentqyw/image-matching-webui/network/members
[stars-shield]: https://img.shields.io/github/stars/Vincentqyw/image-matching-webui.svg?style=for-the-badge
[stars-url]: https://github.com/Vincentqyw/image-matching-webui/stargazers
[issues-shield]: https://img.shields.io/github/issues/Vincentqyw/image-matching-webui.svg?style=for-the-badge
[issues-url]: https://github.com/Vincentqyw/image-matching-webui/issues