.. _sm2mm_pipelines:

=================
sm2mm pipelines
=================

This page describes the file format for `sm2mm` pipelines and lists some useful ready-to-use examples.

.. contents::
   :local:


1. What does `sm2mm` mean?
############################

`sm2mm` stands for the process of transforming a "simple map" file, a "key-frame map" typically generated by a SLAM system
and having the `.simplemap` extension, into a "metric map" file (`.mm` extension), typically comprising several
:ref:`map layers <mp2p_icp_basics>` of different types, semantics, or serving to different purposes.

.. image:: https://mrpt.github.io/imgs/sm2mm_generic_diagram.png
    :alt: sm2mm generic diagram
    :align: center


Users may use this through two interfaces: a CLI application :ref:`sm2mm <app_sm2mm>` or the C++ API `mp2p_icp_filters::simplemap_to_metricmap() <group_mp2p_icp_filters_grp.html#doxid-group-mp2p-icp-filters-grp-1ga3fa21e8673fcbaff189e60b3d703dbb4>`_.

|


2. Pipeline file specification
###############################
Pipeline configuration files are written in YAML format and define the sequence of operations to be applied to the raw sensor observations stored as map keyframes.

The pipeline can include various filters and generators that process the observations, such as downsampling, noise reduction, or feature extraction.
The pipeline file can also specify custom plugins to be loaded, which can define new metric map classes or custom filter algorithms.

Each pipeline file can contain these sections:

- ``generators:``: A list of generators to create maps from each raw observations in each key-frame. If none is provided, the default :ref:`mp2p_icp::Generator <doxid-classmp2p__icp__filters_1_1_generator>` is used, which generates a point cloud from the observation.
- ``filters:``: A list of filters to apply to each key-frame observations, after generators have been applied. For example, here one typically removes the robot body, de-skew the scan, downsamples the point cloud, and merges the result into one or several final metric map layers used to accumulate the result.
- ``final_filters:``: An optional list of filters to apply to the final map layers, after all key-frames have been processed.

Refer to example pipeline files `sm2mm_*.yaml` under the `demos directory <https://github.com/MOLAorg/mp2p_icp/tree/develop/demos>`_.
Some of them are explained below with a diagram.

|


3. Example sm2mm pipelines
###############################

|

Pipeline: ``sm2mm_no_decim_imu_mls_keyframe_map.yaml``
------------------------------------------------------

**Purpose:** Build a dense (no downsampling) point cloud, using IMU-based motion compensation, then filter the map using the MLS filter,
and store the resulting map into a ``mola::KeyframePointCloudMap`` layer named ``localmap``, suitable for MOLA-LIO localization-only mode.

.. image:: https://mrpt.github.io/imgs/sm2mm_no_decim_imu_mls_keyframe_map.png
    :alt: sm2mm diagram
    :align: center

|

.. dropdown:: Example result screenshots
    :icon: image
    :open:

    .. image:: https://mrpt.github.io/imgs/smm2_demo_dcc02_mls.png
        :alt: sm2mm example result screenshots
        :align: center
        :target: https://mrpt.github.io/imgs/smm2_demo_dcc02_mls.png

.. dropdown:: Pipeline YAML code
    :icon: list-unordered

    .. literalinclude:: ../../../mp2p_icp/demos/sm2mm_no_decim_imu_mls_keyframe_map.yaml
       :language: yaml


|

---------

|

Pipeline: ``sm2mm_pointcloud_voxelize.yaml``
---------------------------------------------

**Purpose:** Process point clouds by applying voxelization to downsample the data while preserving spatial structure,
creating a more memory-efficient representation.

.. image:: https://mrpt.github.io/imgs/sm2mm_pointcloud_voxelize.png
    :alt: sm2mm voxelization diagram
    :align: center

|


.. dropdown:: Example result screenshots
    :icon: image
    :open:

    **Overview of voxelized map:**

    .. image:: https://mrpt.github.io/imgs/smm2_demo_dcc02_voxel_overview.png
        :alt: sm2mm voxel overview
        :align: center
        :target: https://mrpt.github.io/imgs/smm2_demo_dcc02_voxel_overview.png

    |

    **Detailed view of voxel structure:**

    .. image:: https://mrpt.github.io/imgs/smm2_demo_dcc02_voxel.png
        :alt: sm2mm voxel detail
        :align: center
        :target: https://mrpt.github.io/imgs/smm2_demo_dcc02_voxel.png

.. dropdown:: Pipeline YAML code
    :icon: list-unordered

    .. literalinclude:: ../../../mp2p_icp/demos/sm2mm_pointcloud_voxelize.yaml
       :language: yaml


|

---------

|

Pipeline: ``sm2mm_voxels_static_dynamic_points.yaml``
------------------------------------------------------

**Purpose:** Separate point clouds into static and dynamic layers using voxel-based analysis,
enabling differentiation between stationary map features and moving objects for robust localization and mapping.

.. image:: https://mrpt.github.io/imgs/sm2mm_voxels_static_dynamic_points.png
    :alt: sm2mm static/dynamic separation diagram
    :align: center

|

.. dropdown:: Example result screenshots
    :icon: image
    :open:

    **Overview of map with static/dynamic layers:**

    .. image:: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_static_overview.png
        :alt: sm2mm dynamic layer overview
        :align: center
        :target: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_static_overview.png

    |

    **Detailed view of static layer:**

    .. image:: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_static.png
        :alt: sm2mm static layer detail
        :align: center
        :target: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_static.png

    |

    **Voxel representation with dynamic filtering:**

    .. image:: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_voxel.png
        :alt: sm2mm dynamic voxel detail
        :align: center
        :target: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_voxel.png

    |

    **Dynamic layer visualization:**

    .. image:: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_dyn.png
        :alt: sm2mm dynamic layer
        :align: center
        :target: https://mrpt.github.io/imgs/smm2_demo_dcc02_dyn_layer_dyn.png

.. dropdown:: Pipeline YAML code
    :icon: list-unordered

    .. literalinclude:: ../../../mp2p_icp/demos/sm2mm_voxels_static_dynamic_points.yaml
       :language: yaml