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.