# kapture-localization

**Repository Path**: mirrors_naver/kapture-localization

## Basic Information

- **Project Name**: kapture-localization
- **Description**: Provide mapping and localization pipelines based on kapture format
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-10-15
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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