Visual Global Localization
==========================

Overview of Global Localization
-------------------------------

Global localization is a process in robotics and computer vision to determine a device's
or robot's position in an environment when its initial location is unknown. This contrasts
with local localization, where the starting position is provided.

Global localization is essential for applications such as autonomous navigation,
where a robot needs to determine its position to navigate efficiently through its surroundings.
It is especially useful in environments where GPS signals are weak or unavailable,
such as indoors or in urban canyons. 

By using visual cues and other sensor data,
global localization helps in building a comprehensive understanding of the environment,
enabling tasks like mapping, navigation, and interaction with the physical world.

What is cuVGL?
--------------

cuVGL, short for CUDA-accelerated Visual Global Localization, is a library designed for efficient
and accurate global localization tasks using GPU acceleration.
The library focuses on two main components:

*  **image retrieval via bag of words (BoW)**
*  **relative pose estimation using stereo images**
  
cuVGL uses external poses, such as those provided by a SLAM system,
along with images to produce a keyframe database. This database is later used for global localization,
making cuVGL a flexible component for systems that do not have global localization capabilities.


Map Creation Process
^^^^^^^^^^^^^^^^^^^^

.. figure:: :ir_lfs:`<resources/isaac_ros_docs/concepts/visual_global_localization/map_creation_process.png>`
    :align: center
    :width: 800px

The map creation process in cuVGL is unique as it consumes external poses and images to build a **keyframe database**,
rather than generating a traditional map like a sparse feature map.
 
The input for the map creation includes:

- **stereo camera images**
- **poses from an external source** (for example, a SLAM system)

The output map includes:

- **keyframe database**: storing the map keyframes and the associated poses.
- **BoW vocabulary**
- **BoW image retrieval index**: with BoW vocabulary, enabling fast image retrieval.

Localization Process
^^^^^^^^^^^^^^^^^^^^

.. figure:: :ir_lfs:`<resources/isaac_ros_docs/concepts/visual_global_localization/localization_process.png>`
    :align: center
    :width: 800px

Localization in cuVGL is performed using stereo images for relative pose estimation. The process involves:

* **image retrieval**: for the current input image, cuVGL retrieves the best matching candidates from the keyframe database using the BoW image retrieval index.
*  **relative pose estimation**: after matching candidates are identified, the library computes the relative pose between the input stereo image and the map image candidate.
*   **absolute pose calculation**: by applying the relative transform to the mapping pose of the map image (recorded during the mapping phase), cuVGL outputs an absolute pose for the current input image.


.. note::

  Please follow these guidelines for good localization performance:

  1. Map the entire environment to ensure the vocabulary contains a sufficient number of visual words for accurately describing the environment.
  2. Keep the localization trajectory within 1 meter from the mapping trajectory.

Metrics of cuVGL
----------------

.. include:: _snippets/accuracy.rst


Camera System Requirements
--------------------------

.. include:: _snippets/camera_system_requirements.rst


Repositories and Packages
-------------------------
The following are the major packages related to cuVGL:

* The core implementations of cuVGL in following repository, details see:

  * :doc:`Isaac Mapping </repositories_and_packages/isaac_ros_mapping_and_localization/isaac_mapping_ros/isaac_mapping/index>`

* The localization ROS wrapper of cuVGL in following ROS package, details see:

  * :doc:`Isaac ROS Visual Global Localization </repositories_and_packages/isaac_ros_mapping_and_localization/isaac_ros_visual_global_localization/index>`


Tutorials
---------
To get started with cuVGL, review the following examples:

.. toctree::
   :glob:
   :maxdepth: 1

   tutorials/tutorial_map_creation
   tutorials/tutorial_localization