/kapture-localization

Provide mapping and localization pipelines based on kapture format

Primary LanguagePythonBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

kapture-localization: toolbox

Table of Contents

1. Overview

kapture-localization is a toolbox in which you will find implementations for various localization related algorithms. It strongly relies on the kapture format for data representation and manipulation.

The localization algorithms include:

  1. mapping,

  2. localization, and

  3. benchmarking (image retrieval for visual localization).

It works on Ubuntu, Windows, and MacOS.

2. Structure

The directories are organised as follow:

├── kapture_localization/  # package (library)
├── pipeline/              # main programs executing all steps of the localization pipelines
├── samples/               # some sample data
├── tests/                 # unit tests
└── tools/                 # sub programs involved in the pipeline

The kapture-localization toolbox is available as:

  • Python package (kapture_localization/),

  • Python executable scripts (pipeline/ & tools/).

There are 3 pipelines available:

  1. mapping,

  2. localization, and

  3. image retrieval benchmark (global sfm, local sfm, pose approximation).

3. Installation

It can be installed using docker, pip or from manually from source code. After installing python (>=3.8) and COLMAP (>=3.6), this toolbox can be installed with:

pip install kapture-localization

See doc/installation.adoc for more details.

4. Tutorial

See doc/tutorial for a short introduction and examples of the provided processing pipelines.

5. Image Retrieval Benchmark

6. Contributing

There are many ways to contribute to the kapture-localization project:

  • provide feedback and suggestion,

  • submit bug reports in the project bug tracker,

  • implement a feature or bug-fix for an outstanding issue,

  • provide scripts to create data in kapture format (e.g. local/global feature extraction),

  • propose a new feature and implement it.

If you wish to contribute, please refer to the CONTRIBUTING page.

7. License

Software license is detailed in the LICENSE file.

8. References

If you use this work for your research, please cite the respective paper(s):

Structure-based localization or kapture format
@misc{kapture2020,
      title={Robust Image Retrieval-based Visual Localization using Kapture},
      author={Martin Humenberger and Yohann Cabon and Nicolas Guerin and Julien Morat and Jérôme Revaud and Philippe Rerole and Noé Pion and Cesar de Souza and Vincent Leroy and Gabriela Csurka},
      year={2020},
      eprint={2007.13867},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}
Image retrieval benchmark
@inproceedings{benchmarking_ir3DV2020,
      title={Benchmarking Image Retrieval for Visual Localization},
      author={Noé Pion, Martin Humenberger, Gabriela Csurka, Yohann Cabon, Torsten Sattler},
      year={2020},
      booktitle={International Conference on 3D Vision}
}

@article{humenberger2022investigating,
  title={Investigating the Role of Image Retrieval for Visual Localization},
  author={Humenberger, Martin and Cabon, Yohann and Pion, No{\'e} and Weinzaepfel, Philippe and Lee, Donghwan and Gu{\'e}rin, Nicolas and Sattler, Torsten and Csurka, Gabriela},
  journal={International Journal of Computer Vision},
  year={2022},
  publisher={Springer}
}