Imported upstream version '1.3.0' of 'upstream'

.github/workflows/build-ros.yml

@@ -10,13 +10,6 @@ jobs:
       DEBIAN_FRONTEND: noninteractive
     strategy:
       matrix:
-        # Github Actions requires a single row to be added to the build matrix.
-        # See https://help.github.com/en/articles/workflow-syntax-for-github-actions.
-#        ros_distribution:
-#          - humble
-#          - iron
-#          - rolling
-
         # Define the Docker image(s) associated with each ROS distribution.
         # The include syntax allows additional variables to be defined, like
         # docker_image in this case. See documentation:
@@ -31,11 +24,6 @@ jobs:
             ros_distribution: humble
             ros_version: 2
 
-          # Iron Irwini (May 2023 - November 2024)
-          - docker_image: ubuntu:jammy
-            ros_distribution: iron
-            ros_version: 2
-
           # Jazzy (2024 - ??)
           - docker_image: ubuntu:noble
             ros_distribution: jazzy

.github/workflows/check-clang-format.yml

@@ -31,7 +31,7 @@ jobs:
 
       - name: Install Dependencies
         run: |
-          sudo apt install clang-format-11 -yq
+          sudo apt install clang-format-14 -yq
           pip3 install --user -r .github/python_clang_format_reqs.txt
 
       - name: Check code style

docs/source/building-maps.rst

@@ -285,6 +285,9 @@ Afterwards, visualizing :ref:`metric map files <mp2p_icp_basics>` (``*.mm``) can
 
 |
 
+
+.. _tutorial-pub-map-server-to-ros:
+
 5. Publish the map to ROS 2
 ----------------------------------------
 

docs/source/concept-slam-configuration-file.rst

@@ -52,7 +52,7 @@ in either absolute path, or relative to the current YAML file being parsed.
       - type: CLASS_NAME1       # mandatory
         #...
         params:                 # Other module-specific parameters
-          $include{$(mola-dir module-name)/params/xxxx.yaml}
+          $include{$(ros2 pkg prefix mola_lidar_odometry)/share/xxx/xxxx.yaml}
         config:
           $include{params/xxxx.yaml}
 
@@ -69,3 +69,11 @@ Replace output of external process: ``$(cmd)``
 The pattern ``$(cmd arg1 arg2...)`` is replaced by the console output of running
 the given command with the given arguments. See for example its usage together
 with ``$include{xxx}`` above.
+
+Mathematical formulas : ``$f{xxx}``
+-----------------------------------------------
+The pattern ``$f{expr}`` can be used to indicate mathematical expressions. 
+The `ExprTk library <https://github.com/ArashPartow/exprtk>`_ is used
+(via `mrpt-expr <https://docs.mrpt.org/reference/latest/group_mrpt_expr_grp.html>`_),
+so refer to their documentation for built-in functions and syntax.
+User-defined variables can be used, depending on the context of the YAML file being parsed.

docs/source/dataset-conversions.rst

@@ -247,7 +247,7 @@ and launch it using `mola-cli`. See existing ROS launch examples
 under `ros2-launch (mola_demos package) <https://github.com/MOLAorg/mola/tree/develop/mola_demos/ros2-launchs>`_,
 with corresponding MOLA cli launch files in the `mola-cli-launchs <https://github.com/MOLAorg/mola/tree/develop/mola_demos/mola-cli-launchs>`_ directory.
 
-.. dropdown:: Example: play back a KITTI dataset sequence to ROS 2
+.. dropdown:: Example #1: play back a KITTI dataset sequence to ROS 2
   :open:
 
   .. code-block:: bash
@@ -258,3 +258,9 @@ with corresponding MOLA cli launch files in the `mola-cli-launchs <https://githu
 
   .. figure:: https://mrpt.github.io/imgs/screenshot_mola_demo_kitti_replay_to_ros.jpg
     :width: 600
+
+.. dropdown:: Example #2: play back a Mulran dataset sequence to ROS 2
+  :open:
+
+  Refer to the :ref:`complete tutorial <tutorial-mulran-replay-to-ros2>`.
+

docs/source/geo-referencing.rst

@@ -31,24 +31,7 @@ which extends the standard `REP-105 <https://www.ros.org/reps/rep-0105.html>`_ w
    :width: 500
    :align: center
 
-These are the existing frames:
-
-- ``base_link``: The robot reference frame. For ground vehicles, normally placed at the
-  center of the rear axle.
-- ``odom``: The arbitrary origin for odometry measurements.
-- ``map``: The origin of the reference metric map used for localization.
-- ``enu``: For geo-referenced maps, the North (``y`` axis), East (``x`` axis), Up (``z`` axis) frame for which
-  we have reference geodetic coordinates (latitude and longitude). Different maps built in the same zone
-  will surely have different ``enu`` frames, since it is defined by collected GNSS measurements.
-- ``utm``: The origin of the `UTM zone <https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>`_
-  in which ``enu`` falls. Unlike ``enu``, it is **independent** of the trajectory followed while building the map.
-
-And this is who is responsible of publishing each transformation:
-
-- ``odom → base_link``: Odometry module. High-frequency, accurate in the short term, but drifts in the long term.
-- ``map → odom``: :ref:`Localization <localization>` module, which corrects the odometry drift.
-- ``enu → {map, utm}``: Published by ``mrpt_map_server`` (`github <https://github.com/mrpt-ros-pkg/mrpt_navigation/tree/ros2/mrpt_map_server/>`_),
-  if fed with a geo-referenced metric map (``.mm``) file.
+The existing frames are :ref:`explained here <mola_ros2_tf_frames>`.
 
 |
 

docs/source/index.rst

@@ -16,6 +16,7 @@ MOLA
   localization
   geo-referencing
   use-cases
+  ros2api
   solutions
 
 .. toctree::
@@ -43,7 +44,7 @@ MOLA
 .. toctree::
   :maxdepth: 2
   :hidden:
-  :caption: Details
+  :caption: Learn more
 
   mola_architecture
   tutorials

docs/source/refs.bib

@@ -113,4 +113,13 @@ @article{magnusson2007scan
   pages={803--827},
   year={2007},
   publisher={Wiley Online Library}
+}
+
+@INPROCEEDINGS{gskim-2020-mulran,
+    TITLE={MulRan: Multimodal Range Dataset for Urban Place Recognition}, 
+    AUTHOR={Giseop Kim and Yeong Sang Park and Younghun Cho and Jinyong Jeong and Ayoung Kim}, 
+    BOOKTITLE = { Proceedings of the IEEE International Conference on Robotics and Automation (ICRA) },
+    YEAR = { 2020 },
+    MONTH = { May },
+    ADDRESS = { Paris }
 }

docs/source/ros2api.rst

@@ -0,0 +1,148 @@
+.. _mola_ros2api:
+
+======================
+ROS 2 API
+======================
+This page reflects the topics and services that a MOLA system will expose when running a SLAM 
+or LiDAR-odometry module. At present, this applies to:
+
+- Any MOLA system including the :ref:`BridgeROS2 <doxid-classmola_1_1_bridge_r_o_s2>` module:
+  This module acts as a wrapper of ``mola-kernel`` virtual interfaces implemented in other
+  MOLA modules and the ROS 2 system.
+- :ref:`mola_lidar_odometry`
+
+.. note::
+
+   It is recommended to start with the tutorial on how to :ref:`build a map <building-maps>`,
+   then check out :ref:`how to launch MOLA-LO for ROS 2 <mola_lo_ros>`.
+
+.. image:: https://mrpt.github.io/imgs/mola-lo-ros2-launch-demo-kitti.png
+
+
+
+____________________________________________
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+   :backlinks: none
+
+____________________________________________
+
+|
+
+1. Map loading / saving
+--------------------------------------
+During a live SLAM run, ``BridgeROS2`` will look for modules implementing
+:ref:`MapServer <doxid-classmola_1_1_map_server>` and will expose
+these **ROS 2 services** to load or save the current map:
+
+* ``/map_load``: See ROS docs for `mola_msgs/MapLoad <https://docs.ros.org/en/rolling/p/mola_msgs/interfaces/srv/MapLoad.html>`_
+
+* ``/map_save``: See ROS docs for `mola_msgs/MapSave <https://docs.ros.org/en/rolling/p/mola_msgs/interfaces/srv/MapSave.html>`_
+
+.. dropdown:: Example ROS 2 cli service calls
+
+    To save the current map:
+
+   .. code-block:: bash
+
+      ros2 service call /map_save mola_msgs/srv/MapSave "map_path: '/tmp/my_map_file_prefix'"
+
+    To load a map from disk:
+
+   .. code-block:: bash
+
+      ros2 service call /map_load mola_msgs/srv/MapLoad "map_path: '/tmp/my_map_file_prefix'"
+
+Note that filename **extension** should not be given, since each service implementation
+may add a different extension, or even save several files that should all, together, be
+later on loaded as one to load the map again.
+
+Alternatively, you can enable saving the map when mapping is ended by checking
+the corresponding checkbox in the
+:ref:`MOLA-LO GUI <mola_lo_gui_common_parts>` (block "6" below):
+
+.. image:: imgs/gui_parts.png
+
+
+|
+
+----
+
+2. Re-localization
+--------------------------------------
+Write me!
+
+|
+
+----
+
+.. _mola_ros2_tf_frames:
+
+3. ``/tf`` frames
+--------------------------------------
+These frames of reference exist when using MOLA :ref:`geo-referenced <geo-referencing>` maps:
+
+.. figure:: https://mrpt.github.io/imgs/mola_mrpt_ros_geo_referenced_utm_frames.png
+   :width: 500
+   :align: center
+
+.. note::
+
+   For non geo-referenced maps, the meaning of all frames are the same but ``utm`` and ``enu``
+   will not be present.
+
+These are the existing frames:
+
+- ``base_link``: The robot reference frame. For ground vehicles, normally placed at the
+  center of the rear axle.
+- ``odom``: The arbitrary origin for odometry measurements.
+- ``map``: The origin of the reference metric map used for localization.
+- ``enu``: For geo-referenced maps, the North (``y`` axis), East (``x`` axis), Up (``z`` axis) frame for which
+  we have reference geodetic coordinates (latitude and longitude). Different maps built in the same zone
+  will surely have different ``enu`` frames, since it is defined by collected GNSS measurements.
+- ``utm``: The origin of the `UTM zone <https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>`_
+  in which ``enu`` falls. Unlike ``enu``, it is **independent** of the trajectory followed while building the map.
+
+And this is who is responsible of publishing each transformation:
+
+- ``odom → base_link``: Odometry module. High-frequency, accurate in the short term, but drifts in the long term.
+- ``map → odom``: :ref:`Localization <localization>` module, which corrects the odometry drift.
+- ``enu → {map, utm}``: Published by ``mrpt_map_server`` (`github <https://github.com/mrpt-ros-pkg/mrpt_navigation/tree/ros2/mrpt_map_server/>`_),
+  if fed with a geo-referenced metric map (``.mm``) file.
+
+
+
+----
+
+4. Map publishing
+--------------------------------------
+There are two ways of publishing maps to ROS:
+
+* Using ``mrpt_map_server`` (`github <https://github.com/mrpt-ros-pkg/mrpt_navigation/tree/ros2/mrpt_map_server/>`_):
+  the recommended way for static, previously-built maps. In this case, one ROS topic
+  will be published for each map layer, as described in the package documentation.
+  See also :ref:`this tutorial <tutorial-pub-map-server-to-ros>`.
+
+* During a live map building process (e.g. MOLA-LO).
+
+In this latter case, BridgeROS2 will look for modules implementing
+:ref:`MapSourceBase <doxid-classmola_1_1_map_source_base>` and will publish
+one **topic** named ``<METHOD>/<LAYER_NAME>`` for each map layer.
+The metric map layer C++ class will determine the ROS topic type to use.
+
+.. note::
+
+   Using the default MOLA LiDAR odometry pipeline, only one map topic will
+   be generated during mapping:
+
+   * Name: ``/lidar_odometry/localmap_points``
+   * Type: ``sensor_msgs/PointCloud2``
+
+|
+
+
+
+
+

docs/source/tutorial-mulran-replay-to-ros2.rst

@@ -0,0 +1,88 @@
+.. _tutorial-mulran-replay-to-ros2:
+
+=======================================
+Replay MulRan to ROS2
+=======================================
+
+This tutorial will guide you through the process of using MOLA to publish a sequence of the MulRan dataset (:cite:`gskim-2020-mulran`)
+as ROS 2 topics, so they can be visualized in RViz, FoxGlove, or used in your own system.
+
+.. note::
+
+  Users can also access to all MulRan dataset observations directly with the C++ API of :ref:`mola::MulranDataset <doxid-classmola_1_1_mulran_dataset>`.
+
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: none
+
+.. raw:: html
+
+   <div style="width: 100%; overflow: hidden;">
+     <video controls autoplay loop muted style="width: 512px;">
+       <source src="https://mrpt.github.io/videos/mola_demos_Mulran_replay_to_ros2.mp4" type="video/mp4">
+     </video>
+   </div>
+
+|
+
+MOLA installation
+----------------------------------
+This tutorial requires the installation of these MOLA packages: ``mola_demos``, ``mola_input_mulran_dataset``, ``mola_viz``.
+
+Following the default :ref:`installation instructions <installing>` is enough.
+
+|
+
+Dataset preparation
+----------------------------------
+Download the MulRan dataset (:cite:`gskim-2020-mulran`) from their `website <https://sites.google.com/view/mulran-pr/>`_,
+and extract the files anywhere in your system such as the files layout is as expected by :ref:`mola::MulranDataset <doxid-classmola_1_1_mulran_dataset>`.
+
+Remember setting the environment variable ``MULRAN_BASE_DIR`` to the root directory of your dataset, for example: 
+
+.. code-block:: bash
+
+    export MULRAN_BASE_DIR=/home/myuser/mulran/
+
+|
+
+Launching the demo
+----------------------------------
+
+To launch the demo, just run:
+
+.. code-block:: bash
+
+    # Run the default KAIST01 sequence:
+    ros2 launch mola_demos ros-mulran-play.launch.py
+
+    # Or select another sequence:
+    ros2 launch mola_demos ros-mulran-play.launch.py  mulran_sequence:=DCC02
+
+|
+
+Under the hook
+----------------------------------
+This demo comprises two main files:
+
+1) The **MOLA system configuration** file. It defines two MOLA modules: the MulRan input and the ROS2 bridge.
+
+.. dropdown:: YAML listing
+    :icon: code-review
+
+    File: `mulran_just_replay_to_ros2.yaml <https://github.com/MOLAorg/mola/blob/develop/mola_demos/mola-cli-launchs/mulran_just_replay_to_ros2.yaml>`_
+
+    .. literalinclude:: ../../mola_demos/mola-cli-launchs/mulran_just_replay_to_ros2.yaml
+       :language: yaml
+
+2) The **ROS 2 launch** file. It invokes ``mola-cli`` and ``rviz2``.
+
+.. dropdown:: Launch file listing
+    :icon: code-review
+
+    File: `ros-mulran-play.launch.py <https://github.com/MOLAorg/mola/blob/develop/mola_demos/ros2-launchs/ros-mulran-play.launch.py>`_
+
+    .. literalinclude:: ../../mola_demos/ros2-launchs/ros-mulran-play.launch.py
+       :language: python

docs/source/tutorials.rst

@@ -21,4 +21,5 @@ tools.
 
   tutorial-mola-main-cli-tools
   tutorial-mola-cmake-commands
+  tutorial-mulran-replay-to-ros2
 

kitti_metrics_eval/CHANGELOG.rst

@@ -3,6 +3,9 @@ Changelog for package kitti_metrics_eval
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
+1.3.0 (2024-12-11)
+------------------
+
 1.2.1 (2024-09-29)
 ------------------