Installation

Requirements

Deep-image-matching is tested on Ubuntu 22.04 and Windows 10 with Python 3.9. It is strongly recommended to have a NVIDIA GPU with at least 8GB of memory. Due to dependencies issues, it is recommended to use Python 3.9 on Windows and MacOS, while on Linux you can also use Python 3.10 (see pydegensac).

All the dependencies are listed in the pyproject.toml file.

Installation

For installing deep-image-matching, first create a conda environment:

conda create -n deep-image-matching python=3.9
conda activate deep-image-matching
pip install --upgrade pip

Clone the repository and install deep-image-matching in editable mode:

git clone https://github.com/3DOM-FBK/deep-image-matching.git
cd deep-image-matching
pip install -e .

Install pycolmap (optional):

pip install pycolmap==0.6.1

Pycolmap is optional to run reconstruction directly in DIM. If pycolmap is not available, matches will be written both in a h5 and colmap database for later processing with COLMAP GUI or API, or other processing.

Notes and troubleshooting

Pytorch

If you run into any troubles installing Pytorch (and its related packages, such as Kornia), please check the official website (https://pytorch.org/get-started/locally/) and follow the instructions for your system and CUDA architecture. Then, try to install again deep-image-matching.

Pydegensac

Deep-image-matching relies on pydegensac for the geometric verification of matches, which is only available for Python <=3.9 on Windows. If you are using Windows or MacOS, please, use Python 3.9, on Linux, you can also use Python 3.10.

Pycolmap

Deep-image-matching uses pycolmap for automatize 3D reconstruction (without the need to use COLMAP by GUI or CLI) and to export the reconstruction in Bundler format for importing into Metashape. Pycolmap is alse needed to create cameras from exif metadata in the COLMAP database. If pycolmap is not installed, deep-image-matching will still work and it will export the matches in a COLMAP SQlite databse, which can be opened by COLMAP GUI or CLI to run the 3D reconstruction.

Up to version 0.4.0, pycolmap was avalable in pypi only for Linux and MacOS, therefore it was not installed by default with deep-image-matching to avoid errors on installations on Windows.

Recently, pycolmap 0.5.0 has been released on pypi also for Windows, so we are considering to add it as a dependency of deep-image-matching and it will be installed by default, but we need to carry out some tests before doing it.

Before, if you were using Windows, you could use WSL for installing pycolmap (please refer to issue #34 in pycolmap repo). However, now you can also try installing it with pip, it should work fine.

Docker Installation

If you prefer to use Docker, first, build the image:

docker build --tag deep-image-matching .

Note that the first time you run the command, it will take a while to download the base image and install all the dependencies.

Once the image is built, you can run it with the following commands. On Linux:

docker run --name running-deep-image-matching --mount type=bind,source=/home/username/data,target=/workspace/data --gpus all -it deep-image-matching

On Windows (please, use Powershell):

docker run --name running-deep-image-matching --mount type=bind,source=D:\data,target=/workspace/data --gpus all -it deep-image-matching

Replace /home/username/data (on Linux) or D:\data (on Winows) with the desired path for mounting a shared volume between the local OS and the docker container. Make sure to use absolute paths. This folder will be used to store alll the input data (images) and outputs.

If you want to run the container in background, you can use the --detach option:

docker run --name run-deep-image-matching --mount type=bind,source=/home/username/data,target=/workspace/data --gpus all --detach deep-image-matching

You can also remove the container on exit using the --rm option:

docker run --name run-deep-image-matching --mount type=bind,source=/home/username/data,target=/workspace/data --gpus all --rm -it deep-image-matching

Once the container is running, you can then open the repo cloned inside the container directly in VSCode using ctrl+alt+O and selecting the option "attach to running container" (make sure to have the Docker extension installed in VSCode), then enjoy!

If you want to build the docker image with deep-image-matching and pycolmap from a branch different from master, you can use the following command:

docker build --tag deep-image-matching --build-arg BRANCH=dev .

Docker troubleshooting

Linux

With Linux you may face some issues when running the container with the --gpus all option.

  1. If you get the following error.

bash docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error running hook #0: error running hook: exit status 1, stdout: , stderr: Auto-detected mode as 'legacy' nvidia-container-cli: initialization error: load library failed: libnvidia-ml.so.1: cannot open shared object file: no such file or directory: unknown. ERRO[0000] error waiting for container: context canceled

You should try to use sudo for building and running the docker command

bash sudo docker build --tag deep-image-matching . sudo docker run --name running-deep-image-matching --mount type=bind,source=/home/username/data,target=/workspace/data --gpus all -it deep-image-matching

  1. If you get the following error.

bash docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]]. ERRO[0000] error waiting for container: context canceled

In order to use the --gpus all option, you need to have the NVIDIA Container Toolkit installed. Please refer to the official documentation here.