From 42ff9a3a7d81ae41f9cf13392f07de3ba7603f4b Mon Sep 17 00:00:00 2001 From: Jose Luis Blanco-Claraco Date: Fri, 20 Dec 2024 21:34:53 +0100 Subject: [PATCH] docs: clarify tutorial on relocalization --- docs/source/index.rst | 2 +- docs/source/ros2api.rst | 17 +++++++++-- .../tutorial-mola-lo-map-and-localize.rst | 29 ++++++++++++++++--- 3 files changed, 40 insertions(+), 8 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8819fa6..c911943 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -56,7 +56,7 @@ MOLA :octicon:`mark-github` `MOLA`_ is a Modular system for Localization and Mapping. Get started: - - Read: :ref:`building-maps`. + - Follow the tutorials: :ref:`Building your first map `, :ref:`Mapping and localization `. - Read :octicon:`rocket` :ref:`mola_lidar_odometry` documentation. - See :ref:`use-cases` for examples of use. - See :ref:`installing` and :ref:`how to cite it `. diff --git a/docs/source/ros2api.rst b/docs/source/ros2api.rst index addab5e..74b453f 100644 --- a/docs/source/ros2api.rst +++ b/docs/source/ros2api.rst @@ -126,8 +126,19 @@ And this is who is responsible of publishing each transformation: | +.. _ros2api_topics: -5. Map publishing +5. Published topics +-------------------------------------- +Write me! + +| + +---- + +| + +6. Map publishing -------------------------------------- There are two ways of publishing maps to ROS: @@ -159,12 +170,12 @@ The metric map layer C++ class will determine the ROS topic type to use. .. _ros2api_runtime_params: -6. Runtime dynamic reconfiguration +7. Runtime dynamic reconfiguration ---------------------------------------- MOLA modules may expose a subset of their parameters through an interface that allows runtime reconfiguration via ROS 2 service requests: -6.1. Runtime parameters for ``mola_lidar_odometry`` +7.1. Runtime parameters for ``mola_lidar_odometry`` ====================================================== List all existing parameters: diff --git a/docs/source/tutorial-mola-lo-map-and-localize.rst b/docs/source/tutorial-mola-lo-map-and-localize.rst index a4d2f56..32e2022 100644 --- a/docs/source/tutorial-mola-lo-map-and-localize.rst +++ b/docs/source/tutorial-mola-lo-map-and-localize.rst @@ -136,10 +136,8 @@ the robot needs to operate so it can localize correctly. | - - -3. Load a prebuilt map in localize-only mode ---------------------------------------------- +3. Load a prebuilt map in localization-only mode +-------------------------------------------------- .. note:: @@ -163,6 +161,7 @@ Again, we will use **three terminals**: .. code-block:: bash MOLA_MAPPING_ENABLED=false \ + MOLA_START_ACTIVE=false \ ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \ lidar_topic_name:=/lidar1_points @@ -170,6 +169,12 @@ Again, we will use **three terminals**: Remember replacing ``/lidar1_points`` with your actual PointCloud2 topic with raw LiDAR data. + Explanation: + + - ``MOLA_MAPPING_ENABLED=false`` disables map updates, so the loaded map will remain static. + - ``MOLA_START_ACTIVE=false`` is recommended so LO does not attempt to match incoming sensor + data until a relocalization method or rough initial localization is set (see next section below). + .. tab-item:: #3: Load the map Next, in terminal #3, let's order MOLA-LO to **load our former map** from disk: @@ -198,6 +203,7 @@ Again, we will use **three terminals**: .. code-block:: bash MOLA_MAPPING_ENABLED=false \ + MOLA_START_ACTIVE=false \ MOLA_LOAD_MM=/tmp/my_map.mm \ MOLA_LOAD_SM=/tmp/my_map.simplemap \ ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \ @@ -231,6 +237,8 @@ relocalization via ROS 2 API. Just use the RViz2's button ``2D pose estimate`` or FoxGlove's "Pose Estimate" to pick a pose and MOLA-LO will try to re-localize the vehicle in the given area. + .. image:: https://mrpt.github.io/imgs/mola-lo-relocalization-from-fox-glove.jpg + .. tab-item:: Re-localize with a service There is also a ROS 2 service for programmatically request a relocalization, and @@ -239,6 +247,19 @@ relocalization via ROS 2 API. - Service default name: ``/relocalize_near_pose`` - Service interface: `mola_msgs::srv::RelocalizeNearPose `_ +| + +Once MOLA-LO knows how to handle initialization, we can activate it, either from the GUI (click the "active" checkbox) +or via this command (see all other similar commands): + + .. code-block:: bash + + # active: true + ros2 service call /mola_runtime_param_set mola_msgs/srv/MolaRuntimeParamSet \ + "{parameters: \"mola::LidarOdometry:lidar_odom:\n active: true\n\"}" + +Then, the module will start to produce localization estimates via ``/tf``, ``Odometry`` messages, +together with a localization quality metric (see all :ref:`published topics `). |