Application: sm2mm

Convert a `*.simplemap` file into a `*.mm` metric map using a pipeline configuration.

Synopsis

The sm2mm command-line tool is a utility from the mp2p_icp project designed to transform 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). Recall that metric maps in mp2p_icp can have multiple map layers. This conversion is performed by applying a user-defined processing pipeline, specified in a configuration file, to the simple map data.

This tool is for post-processing SLAM outputs, enabling the generation of detailed and structured metric representations of the environment suitable for various applications, such as navigation, visualization, or further geometric analysis.

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 mp2p_icp::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.

Example pipeline
# -----------------------------------------------------------------------------
# Pipeline definition file for sm2mm (simplemap-to-metricmap)
#
# See: https://github.com/MOLAorg/mp2p_icp/tree/develop/apps/sm2mm
#
# Explanation of this particular pipeline:
#  - Generators: empty, so the default generator is used (everything in one 
#                layer named 'raw' with all points).
#  - Filters: Just one downsampling filter, with an additional removal of close
#             points (e.g. the robot body)
# -----------------------------------------------------------------------------


# --------------------------------------------------------
# 1) Generator (observation -> local frame metric maps)
# --------------------------------------------------------
#generators:
#  - class_name: mp2p_icp_filters::Generator
#    params: ~

# --------------------------------------------------------
# 2) Per local frame filtering
# --------------------------------------------------------
filters:
  - class_name: mp2p_icp_filters::FilterAdjustTimestamps
    params:
      pointcloud_layer: 'raw'
      silently_ignore_no_timestamps: true
      method: 'TimestampAdjustMethod::MiddleIsZero'

  - class_name: mp2p_icp_filters::FilterDeskew
    params:
      input_pointcloud_layer: 'raw'
      output_pointcloud_layer: 'deskewed'
      #silently_ignore_no_timestamps: true # To handle more dataset types
      output_layer_class: 'mrpt::maps::CPointsMapXYZIRT'  # Keep intensity & ring channels

      # These (vx,...,wz) are variable names that must be defined via the
      # mp2p_icp::Parameterizable API to update them dynamically.
      twist: [vx,vy,vz,wx,wy,wz]

  - class_name: mp2p_icp_filters::FilterDecimateVoxels
    params:
      input_pointcloud_layer: 'deskewed'
      output_pointcloud_layer: 'decimated'
      voxel_filter_resolution: 0.10  # [m]
      decimate_method: DecimateMethod::FirstPoint

  - class_name: mp2p_icp_filters::FilterByRange
    params:
      input_pointcloud_layer: 'decimated'
      output_layer_outside: 'filtered'
      range_min: 0.0
      range_max: 5.0
      # Measure distances from the moving robot pose:
      center: [robot_x, robot_y, robot_z]

  - class_name: mp2p_icp_filters::FilterDeleteLayer
    params:
      # one or more layers to remove
      pointcloud_layer_to_remove: ['raw', 'deskewed', 'decimated']

# -------------------------------------------------------------------
# 3) Final, overall filter pipeline to apply to the whole metric map
# -------------------------------------------------------------------
#final_filters:
#  - (none)

CLI Reference

USAGE:

sm2mm  [--to-index <0>] [--from-index <0>] [--no-progress-bar]
        [--externals-dir <<ExternalsDirectory>>] [-v <INFO>] [-p
        <pipeline.yaml>] [-l <foobar.so>] -o <out.mm> -i <map.simplemap>
        [--] [--version] [-h]


Where:

--to-index <0>
    If provided, the simplemap keyframes will be processed up to this
    index only.

--from-index <0>
    If provided, the simplemap keyframes until this index will be
    discarded and it will start at this point.

--no-progress-bar
    Disables the progress bar. Useful for cleaner output when using DEBUG
    verbosity level.

--externals-dir <<ExternalsDirectory>>
    Lazy-load base directory for datasets with externally-stored
    observations

-v <INFO>,  --verbosity <INFO>
    Verbosity level: ERROR|WARN|INFO|DEBUG (Default: INFO)

-p <pipeline.yaml>,  --pipeline <pipeline.yaml>
    YAML file with the mp2p_icp_filters pipeline to load. It can
    optionally contain a `filters:`, a `generators:`, and a
    `final_filters:` sections. If this argument is not provided, the
    default generator will be used and no filtering will be applied, which
    might be ok in some cases. See the app README for
    examples:

    https://github.com/MOLAorg/mp2p_icp/tree/develop/apps/sm2mm

-l <foobar.so>,  --load-plugins <foobar.so>
    One or more (comma separated) *.so files to load as plugins, e.g.
    defining new CMetricMap classes

-o <out.mm>,  --output <out.mm>
    (required)  Output .mm file to write to

-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.