= kapture-localization: toolbox :sectnums: :sectnumlevels: 1 :toc: macro :toclevels: 2

toc::[]

== Overview

kapture-localization is a toolbox in which you will find implementations for various localization related algorithms. It strongly relies on the https://github.com/naver/kapture[kapture] format for data representation and manipulation.

The localization algorithms include:

. mapping, . localization, and . benchmarking (image retrieval for visual localization).

It works on Ubuntu, Windows, and MacOS.

== 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:

. mapping, . localization, and . image retrieval benchmark (global sfm, local sfm, pose approximation).

== 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:

[source,bash]

pip install kapture-localization

See link:doc/installation.adoc[] for more details.

== Tutorial

See link:doc/tutorial.adoc[doc/tutorial] for a short introduction and examples of the provided processing pipelines.

== Image Retrieval Benchmark

link:doc/benchmark.adoc[Benchmark pipeline]

link:doc/benchmark_results.adoc[Benchmark results]

== 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.

// TODO individual page for kapture-localization ? If you wish to contribute, please refer to the link:https://github.com/naver/kapture/blob/main/CONTRIBUTING.adoc[CONTRIBUTING] page.

== License Software license is detailed in the link:LICENSE[LICENSE] file.

== 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} }