https://github.com/naver/kapture-localization

Provide mapping and localization pipelines based on kapture format
https://github.com/naver/kapture-localization

colmap image-retrieval localization r2d2 sfm structure-from-motion visual-localization

Last synced: about 1 month ago
JSON representation

Provide mapping and localization pipelines based on kapture format

• Host: GitHub
• URL: https://github.com/naver/kapture-localization
• Owner: naver
• License: bsd-3-clause
• Created: 2020-10-14T01:22:56.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2024-03-28T13:55:53.000Z (about 1 year ago)
• Last Synced: 2025-04-13T04:58:29.538Z (about 1 month ago)
• Topics: colmap, image-retrieval, localization, r2d2, sfm, structure-from-motion, visual-localization
• Language: Python
• Homepage:
• Size: 23.6 MB
• Stars: 277
• Watchers: 13
• Forks: 42
• Open Issues: 1
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

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}

}

----