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 BridgeROS2 module: This module acts as a wrapper of mola-kernel virtual interfaces implemented in other MOLA modules and the ROS 2 system.
3D LiDAR odometry
State estimators

https://mrpt.github.io/imgs/mola-lo-ros2-launch-demo-kitti.png

1. Nodes and launch files

1.1. ROS 2 node for Lidar Odometry (LO)

Note

It is recommended to start with the tutorial on how to build a map.

This launch file (view sources) runs MOLA-LO live on point clouds received from a ROS 2 topic, demonstrating a few features:

Launching and visualizing LO in both, mola_viz and RViz2 (or use FoxGlove if preferred).
How MOLA mola_lidar_odometry publishes the local map, the estimated trajectory, and /tf for the estimated odometry.

https://mrpt.github.io/imgs/mola-lo-ros2-launch-demo-live-forest.png

Basic usage

# Minimal use case (requires correct LiDAR sensor /tf):
ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \
   lidar_topic_name:=ouster/points

# Usage without sensor /tf:
ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \
   lidar_topic_name:=ouster/points \
   ignore_lidar_pose_from_tf:=True \
   publish_localization_following_rep105:=False

Robot with NS

If your robot uses a ROS 2 namespace ROBOT_NS for all its sensor and tf topics, use:

# Minimal use case:
ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \
   lidar_topic_name:=ouster/points \
   use_namespace:=True \
   namespace:=ROBOT_NS

All launch arguments

$ ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py --show-args
Arguments (pass arguments as '<name>:=<value>'):

   'namespace':
      Top-level namespace
      (default: '')

   'use_namespace':
      Whether to apply a namespace to the navigation stack
      (default: 'false')

   'lidar_topic_name':
      Topic name to listen for PointCloud2 input from the LiDAR (for example '/ouster/points')

   'ignore_lidar_pose_from_tf':
      If true, the LiDAR pose will be assumed to be at the origin (base_link). Set to false (default) if you want to read the actual sensor pose from /tf
      (default: 'false')

   'gnss_topic_name':
      Topic name to listen for NavSatFix input from a GNSS (for example '/gps')
      (default: 'gps')

   'imu_topic_name':
      Topic name to listen for Imu input (for example '/imu')
      (default: 'imu')

   'use_mola_gui':
      Whether to open MolaViz GUI interface for watching live mapping and control UI
      (default: 'True')

   'publish_localization_following_rep105':
      Whether to publish localization TFs in between map->odom (true) or directly map->base_link (false)
      (default: 'True')

   'start_mapping_enabled':
      Whether MOLA-LO should start with map update enabled (true), or in localization-only mode (false)
      (default: 'True')

   'start_active':
      Whether MOLA-LO should start active, that is, processing incoming sensor data (true), or ignoring them (false)
      (default: 'True')

   'mola_lo_reference_frame':
      The /tf frame name to be used for MOLA-LO localization updates
      (default: 'map')

   'mola_lo_pipeline':
      The LiDAR-Odometry pipeline configuration YAML file defining the LO system. Absolute path, or relative to 'mola-cli-launchs/lidar_odometry_ros2.yaml'. Default is the 'lidar3d-default.yaml' system described in the IJRR 2025 paper.
      (default: '../pipelines/lidar3d-default.yaml')

   'generate_simplemap':
      Whether to create a '.simplemap', useful for map post-processing. Refer to online tutorials.
      (default: 'False')

   'mola_initial_map_mm_file':
      Can be used to provide a metric map '.mm' file to be loaded as initial map. Refer to online tutorials.
      (default: '""')

   'mola_initial_map_sm_file':
      Can be used to provide a keyframes map '.simplemap' file to be loaded as initial map. Refer to online tutorials.
      (default: '""')

   'mola_footprint_to_base_link_tf':
      Can be used to define a custom transformation between base_footprint and base_link. The coordinates are [x, y, z, yaw_deg, pitch_deg, roll_deg].
      (default: '[0, 0, 0, 0, 0, 0]')

   'enforce_planar_motion':
      Whether to enforce z, pitch, and roll to be zero.
      (default: 'False')

   'use_state_estimator':
      If false, the basic state estimator 'mola::state_estimation_simple::StateEstimationSimple' will be used. If true, 'mola::state_estimation_smoother::StateEstimationSmoother' is used instead.
      (default: 'False')

   'state_estimator_config_yaml':
      A YAML file with settings for the state estimator. Absolute path or relative to 'mola-cli-launchs/lidar_odometry_ros2.yaml'
      (default: PythonExpr(''../state-estimator-params/state-estimation-smoother.yaml' if ' + LaunchConfig('use_state_estimator') + ' else '../state-estimator-params/state-estimation-simple.yaml''))

   'use_rviz':
      Whether to launch RViz2 with default lidar-odometry.rviz configuration
      (default: 'True')

2. Map loading / saving

During a live SLAM run, BridgeROS2 will look for modules implementing MapServer and will expose these ROS 2 services to load or save the current map:

/map_load: See ROS docs for mola_msgs/MapLoad
/map_save: See ROS docs for mola_msgs/MapSave

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 MOLA-LO GUI (block “6” below):

3. Re-localization

Write me!

4. Published `/tf` frames

The frames of reference (`frame_id`s) at work when using MOLA depend on your system configuration:

Using just mola_lidar_odometry: Two situations here depending on the ROS launch argument publish_localization_following_rep105:
- 1. Strictly following ROS REP-105 in systems with wheels (encoders-based) high-frequency odometry, or
- 1. Not following REP-105 (e.g. if you do not have wheels odometry).
1. Using state estimation data fusion (this case does not follow REP-105), and

And orthogonal to both above, whether the map is geo-referenced or not.

The diagrams below show the cases of following or not following ROS REP-105 for the different situations listed above:

(A) LO+REP105

For cases with ground robots with wheel-based odometry:

https://mrpt.github.io/imgs/mola_mrpt_ros_geo_referenced_utm_frames.png

This is who is responsible of publishing each transformation:

odom → base_link: Wheel odometry module. High-frequency, relatively accurate in the short term, but drifts in the long term.
map → odom: Localization module, which corrects the odometry drift.
enu → {map, utm}: Published by mrpt_map_server (github) or mola_lidar_odometry map loading service if fed with a geo-referenced metric map (.mm) file.

(B) LO, no REP105

When using just a LiDAR as single sensor.

https://mrpt.github.io/imgs/mola_mrpt_ros_frames_no_rep105.png

This is who is responsible of publishing each transformation:

map → base_link: Localization module.
enu → {map, utm}: Published by mrpt_map_server (github) or mola_lidar_odometry map loading service if fed with a geo-referenced metric map (.mm) file.

(C) Data fusion

When using state estimation data fusion: applicable if having just one LiDAR sensor, or LiDAR + wheel odometry, or several odometry sources, optionally GNNS (GPS) and IMU, etc.

https://mrpt.github.io/imgs/mola_mrpt_ros_frames_fusion.png

This is who is responsible of publishing each transformation:

odom_{i} → base_link: One or more odometry sources.
map → base_link: Published by state estimation data fusion.
enu → {map, utm}: Published by mrpt_map_server (github) or mola_lidar_odometry map loading service if fed with a geo-referenced metric map (.mm) file.

Note

For non geo-referenced maps, all frames remain the same but utm and enu will not exist.

Definition of the frames above:

base_link: The robot reference frame. For ground vehicles, normally placed at the center of the rear axle.
base_footprint (optional): The projection of base_link on the ground plane. In MOLA, this frame is published by BridgeROS2 as a child of base_link.
odom, odom_1,… odom_n: The arbitrary origin for odometry measurements. There may be different odometry sources: wheels, LiDAR odometry, visual odometry, etc.
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 in which enu falls. Unlike enu, it is independent of the trajectory followed while building the map.

5. Published topics

Write me!

6. Map publishing

There are two ways of publishing maps to ROS:

Using mrpt_map_server (github): 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 this tutorial.
During a live map building process (e.g. MOLA-LO).

In this latter case, BridgeROS2 will look for modules implementing MapSourceBase 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

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:

7.1. Runtime parameters for `mola_lidar_odometry`

List all existing parameters:

ros2 service call /mola_runtime_param_get mola_msgs/srv/MolaRuntimeParamGet

Documented parameters:

active: Whether MOLA-LO should process incoming sensor data (active: true) or ignore them (active: false).

mapping_enabled: Whether MOLA-LO should update the localmap (true) or just use it in localization-only mode (false).

generate_simplemap: Whether MOLA-LO should build the keyframes-based map (apart of the local metric map), so you end up with a *.simplemap file.

ROS 2 API

1. Nodes and launch files

1.1. ROS 2 node for Lidar Odometry (LO)

2. Map loading / saving

3. Re-localization

4. Published /tf frames

5. Published topics

6. Map publishing

7. Runtime dynamic reconfiguration

7.1. Runtime parameters for mola_lidar_odometry

4. Published `/tf` frames

7.1. Runtime parameters for `mola_lidar_odometry`