Add docs on geo-ref and localization

MOLAorg · Aug 28, 2024 · 21b0527 · 21b0527
1 parent 6724b04
commit 21b0527
Show file tree

Hide file tree

Showing 6 changed files with 239 additions and 18 deletions.
diff --git a/docs/source/building-maps.rst b/docs/source/building-maps.rst
@@ -6,12 +6,16 @@ Tutorial: build a map
 
 This tutorial describes the steps for building metric maps using MOLA.
 
+____________________________________________
 
 .. contents::
    :depth: 1
    :local:
    :backlinks: none
 
+____________________________________________
+
+|
 
 1. Prepare the input data
 ---------------------------------
@@ -184,6 +188,7 @@ To verify that the generated simple-map is correct, you can use :ref:`sm-cli <ap
 
 |
 
+.. _building-maps_step_mm:
 
 4. Build metric maps and visualize them
 ------------------------------------------

diff --git a/docs/source/geo-referencing.rst b/docs/source/geo-referencing.rst
@@ -0,0 +1,127 @@
+.. _geo-referencing:
+
+======================
+Georeferencing
+======================
+Georeferencing trajectories and metric maps is implemented in the :ref:`mola_sm_loop_closure <mola_licenses>` package.
+
+The concept of using simple-maps as intermediary map format together with the layered metric map format (see :cite:`blanco2024mola_lo`)
+enables embedding georeferenced coordinates to any kind of map typically used in robotics: grid maps, voxel maps, point clouds, etc.
+
+.. image:: https://mrpt.github.io/imgs/kaist01_georef_sample.png
+
+|
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+   :backlinks: none
+
+|
+
+1. How to build a georeferenced map
+--------------------------------------------
+First, build a simple-map from a dataset or a live robot as described in :ref:`building-maps`.
+Make sure of having a GPS (GNSS) sensor source emitting observations, and that they were captured
+by MOLA-LO (see :ref:`the corresponding variable <mola_lo_pipeline_sensor_inputs>` in the LO pipeline).
+
+Then, build the corresponding metric map by applying a metric map generation pipeline (see :cite:`blanco2024mola_lo`
+or :ref:`this step  <building-maps_step_mm>` in the tutorial: 
+
+.. code-block:: bash
+
+      # Build metric map (mm) from simplemap (sm):
+      sm2mm -i datasetWithGPS.simplemap -o myMap.mm -p sm2mm_pipeline.yaml
+
+Now, to find out the optimized map-to-ENU transformation and write it into the
+map file, use:
+
+.. code-block:: bash
+
+      # georeference it:
+      mola-sm-georeferencing -i datasetWithGPS.simplemap --write-into myMap.mm
+
+
+.. dropdown:: Full CLI reference
+   :icon: code-review
+
+   .. code-block:: bash
+
+      USAGE:
+
+         mola-sm-georeferencing  [-v <INFO>] [-l <foobar.so>] [--write-into
+                                    <map.mm>] -i <map.simplemap> [--]
+                                    [--version] [-h]
+
+
+      Where: 
+
+         -v <INFO>,  --verbosity <INFO>
+         Verbosity level: ERROR|WARN|INFO|DEBUG (Default: INFO)
+
+         -l <foobar.so>,  --load-plugins <foobar.so>
+         One or more (comma separated) *.so files to load as plugins, e.g.
+         defining new CMetricMap classes
+
+         --write-into <map.mm>
+         An existing .mm file in which to write the georeferencing metadata
+
+         -i <map.simplemap>,  --input <map.simplemap>
+         (required)  Input .simplemap file
+
+         --,  --ignore_rest
+         Ignores the rest of the labeled arguments following this flag.
+
+         --version
+         Displays version information and exits.
+
+         -h,  --help
+         Displays usage information and exits.
+
+|
+
+2. Georeferenced trajectories
+--------------------------------------
+Once you already have a **trajectory** file in the **local map frame of reference**,
+for example, as generated by MOLA-LO in TUM format,
+and after georeferencing the generated map as shown above,
+you can use the CLI tool ``mola-trajectory-georef`` to convert it into geodetic coordinates,
+for example in KML format suitable for visualization in Google Earth.
+
+.. dropdown:: Full CLI reference
+   :icon: code-review
+
+   .. code-block:: bash
+
+      USAGE:
+
+         mola-trajectory-georef  -o <path.kml> -t <traj.tum> -m <map.mm> [--]
+                                    [--version] [-h]
+
+      Where: 
+
+         -o <path.kml>,  --output <path.kml>
+         (required)  The name of the google earth kml file to write to
+
+         -t <traj.tum>,  --trajectory <traj.tum>
+         (required)  Input .tum trajectory, in map local coordinates
+
+         -m <map.mm>,  --map <map.mm>
+         (required)  Input .mm map with georef info
+
+         --,  --ignore_rest
+         Ignores the rest of the labeled arguments following this flag.
+
+         --version
+         Displays version information and exits.
+
+         -h,  --help
+         Displays usage information and exits.
+
+
+|
+
+3. Georeferenced maps in mm-viewer
+----------------------------------------
+Write me!
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -12,9 +12,11 @@ MOLA
   :caption: Quickstart
 
   Home <index.html#http://>
-  solutions
   building-maps
+  localization
+  geo-referencing
   use-cases
+  solutions
 
 .. toctree::
   :maxdepth: 2
@@ -157,11 +159,9 @@ How to install all MOLA modules:
     .. code-block:: bash
 
         # Install core MOLA modules and 3D LiDAR odometry:
-        sudo apt install ros-$ROS_DISTRO-mola ros-$ROS_DISTRO-mola-lidar-odometry
-        
-        # As of Aug 2024, lidar_odometry is not available for all ROS distros yet!
-        # If the apt command above fails, please remove the "mola-lidar-odometry" part
-        # and see instructions below to clone and build the missing module from sources
+        sudo apt install \
+         ros-$ROS_DISTRO-mola \
+         ros-$ROS_DISTRO-mola-lidar-odometry
 
         # (OPTIONAL) Install example small datasets to run demos/unit tests:
         sudo apt install ros-$ROS_DISTRO-mola-test-datasets

diff --git a/docs/source/localization.rst b/docs/source/localization.rst
@@ -0,0 +1,56 @@
+.. _localization-only:
+
+======================
+Localization
+======================
+Localization differs from SLAM in that the map or world model is **not updated** while
+it is being used to keep a robot or vehicle accurately localized within a pre-mapped environment :cite:`blanco2024mola_lo`.
+
+Once :ref:`a map is built <building-maps>`, the result is a simple-map and/or a metric map (``*.mm``), optionally :ref:`georeferenced <geo-referencing>`.
+This map can then be used to enable autonomous navigation ("Go from A to B"), for which localization is a fundamental
+requirement ("Where is B?").
+
+At present, this framework provides two fundamentally different algorithms for **localization**:
+
+* **Based on optimization**, by using the :ref:`LiDAR odometry module <mola_lidar_odometry>`, without map updates.
+* **Based on particle filtering**, by using any combination of metric maps (grid maps, point clouds, etc.) and wheels odometry.
+
+____________________________________________
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+   :backlinks: none
+
+____________________________________________
+
+|
+
+1. Common aspects
+--------------------------------------
+Independently of the localization algorithm, the problem of finding the *rough* localization
+of the vehicle at start up is quite special due to the large **initial uncertainty**.
+
+MOLA provides a specific module for this task (:ref:`doxid-group__mola__relocalization__grp`)
+which can be used by all position tracking algorithms to solve the initial relocalization problem.
+
+Also, implementations below offer two ways to specify the **initial guess** about the robot
+pose in the environment:
+
+* From **a pose with a covariance**, which needs to be given manually either from a ROS topic, RViz/FoxGlove, or a parameter; and
+* From **GNSS readings** ("Automatic re-localization via GPS"). This version requires :ref:`georeferenced metric maps <geo-referencing>`, naturally.
+
+|
+
+
+2. Localization with LiDAR odometry
+--------------------------------------
+Write me!
+
+
+|
+
+
+3. Localization with particle filtering
+----------------------------------------
+Write me!
diff --git a/docs/source/solutions.rst b/docs/source/solutions.rst
@@ -20,14 +20,13 @@ Check out the tutorial: :ref:`building-maps`.
 2. Full 3D SLAM solution (GNSS, submapping, loop closures)
 ------------------------------------------------------------
 
-Build **geo-referenced** consistent global maps, even mixing indoor and outdoor scenarios.
+Build **georeferenced** consistent global maps, even mixing indoor and outdoor scenarios.
 This functionality is provided by:
 
-- ``mola_sm_loop_closure``: TO-DO: add docs.
-  At present, this package is not open-sourced, see: :ref:`mola_licenses`.
+- ``mola_sm_loop_closure``: At present, this package is not open-sourced, see: :ref:`mola_licenses`.
 
-  - **Geo-referencing** metric maps with consumer-grade GNSS sensors.
-  - Off-line **loop closure** for consistent global maps.
+  - **Geo-referencing** metric maps with consumer-grade GNSS sensors. See: :ref:`geo-referencing`.
+  - Off-line **loop closure** for consistent global maps. (TO-DO: Write docs!)
 
 - ``mola_3d_lidar_slam``: (Coming soon!)
 
@@ -40,7 +39,7 @@ This functionality is provided by:
 3. Full 2D SLAM solution
 ----------------------------
 
-Build **geo-referenced** consistent global 2D maps from 2D LiDARs.
+Build **georeferenced** consistent global 2D maps from 2D LiDARs.
 This functionality is provided by:
 
 - ``mola_2d_lidar_slam``: (Coming soon!)
@@ -69,6 +68,7 @@ The complete framework comprises these software repositories:
 .. _mola_lidar_odometry: https://github.com/MOLAorg/mola_lidar_odometry/
 .. |mola_lidar_odometry| replace:: **mola_lidar_odometry**
 
+
 .. list-table:: Software repositories and modules
    :widths: 75 25
    :header-rows: 1
@@ -77,35 +77,47 @@ The complete framework comprises these software repositories:
      - License
 
    * - |MRPT|_
-
+
+       |
+       
        Underlying C++ data structures, algorithms, serialization, RawLog datasets, etc.
      - BSD-3
 
    * - |mp2p_icp|_
-
+
+       |
+       
        Generic ICP algorithm, metric map pipelines.
      - BSD-3
 
    * - |mrpt_navigation|_
-
+
+       |
+       
        ROS 2 nodes: ``*.mm`` `metric map server <https://github.com/mrpt-ros-pkg/mrpt_navigation/tree/ros2/mrpt_map_server>`_,
        `AMCL-like localization <https://github.com/mrpt-ros-pkg/mrpt_navigation/tree/ros2/mrpt_pf_localization>`_,
        `point cloud pipeline <https://github.com/mrpt-ros-pkg/mrpt_navigation/tree/ros2/mrpt_pointcloud_pipeline>`_,
        etc.
      - BSD-3
 
    * - |MOLA|_
-
+
+       |
+       
        MOLA modules: kernel, mola_viz, kinematic state estimator, relocalization, etc.
      - GNU-GPLv3
 
    * - |mola_lidar_odometry|_
-
+
+       |
+       
        :ref:`LiDAR odometry <mola_lidar_odometry>` for mapping and optimization-based localization.
      - GNU-GPLv3
 
    * - **mola_sm_loop_closure**
-
+
+       |
+       
        Map geo-referencing, SLAM with loop-closure for consistent large maps.
      - Upon licensing only
 

diff --git a/docs/source/use-cases.rst b/docs/source/use-cases.rst
@@ -8,6 +8,9 @@ This page shows some examples of applications of MOLA SLAM solutions with :ref:`
 .. contents:: Table of Contents
     :depth: 2
 
+|
+
+
 Automotive SLAM
 -----------------
 An example of urban SLAM from the KITTI dataset:
@@ -17,6 +20,9 @@ An example of urban SLAM from the KITTI dataset:
 See how to launch this demo yourself.
 
 
+|
+
+
 Forest inventory (3D mapping)
 --------------------------------
 See paper :cite:t:`aguilar2024lidar`.
@@ -27,6 +33,9 @@ See paper :cite:t:`aguilar2024lidar`.
       <iframe width="560" height="315" src="https://www.youtube.com/embed/sbakEOnsL6Y?si=xV8-RGNiEFKR-dAI" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
     </div>
 
+|
+
+
 
 Backpack 3D mapping indoors
 --------------------------------
@@ -37,6 +46,9 @@ Backpack 3D mapping indoors
       <iframe width="560" height="315" src="https://www.youtube.com/embed/XNvf8OMXZoY?si=QqiMlni2lmcojph_" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
     </div>
 
+|
+
+
 
 3D LiDAR mapping plus georeferencing (GNSS)
 --------------------------------------------
@@ -45,6 +57,9 @@ Demo from the Mulran dataset, which contains both 3D LiDAR and consumer-grade GN
 (TO-DO: add videos)
 
 
+|
+
+
 Mapping from a drone
 ----------------------
 Using the HILTI 2021 dataset:
@@ -55,6 +70,9 @@ Using the HILTI 2021 dataset:
       <iframe width="560" height="315" src="https://www.youtube.com/embed/1h2aayHvhVU?si=xWMJZ7bDfaWKlOfY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
     </div>
 
+|
+
+
 Greenhouse mapping
 --------------------------------
 See paper :cite:t:`greenbot2024canadas`.
@@ -65,3 +83,6 @@ See paper :cite:t:`greenbot2024canadas`.
       <iframe width="560" height="315" src="https://www.youtube.com/embed/tdXzYeG51Bc?si=IgjYINt1t7qoLb7R" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
     </div>
 
+
+|
+