2D Occupancy Mapping
This mapping feature uses the depth sensor to obtain a 2.5D height map of the ground plane area, which can then be converted into a 2D occupancy grid map used in robot navigation.
To use the mapping feature to its best capabilities, you require:
An installation of Slamcore’s “Slamcore Tools” package v21.06 or above
An installation of Slamcore’s ROS 2
Humblepackage v21.06 or above (see Slamcore ROS 2 Wrapper)
An environment with a single ground plane (multi-level floors or slopes are not supported)
Slamcore SDK v23.01 brings several breaking changes, one of them being the
session file format. Session files (
.session) generated using older
software versions (v21.06) will no longer be usable with v23.01 and above. You
may use the new software to generate a new session file if you have retained the
Please contact firstname.lastname@example.org, providing your Slamcore account email address, if you require access to the v21.06 SDK packages and its supporting documentation to use in conjunction with your old session files.
Step 1 - Record a dataset of the entire test environment
If you wish to generate a height map with a live sensor feed instead of from a dataset you can skip this step and run SLAM live to visualise the building of the height map in real-time as you travel through the test environment. However, we recommend recording a dataset first as that allows you to further tune parameters in the configuration file for the SLAM algorithm and the map settings.
With depth stream enabled, record your entire test environment and cover every area thoroughly as this will be used to generate the occupancy grid map. For optimal results:
Traverse paths twice in both directions (e.g. go up and down a corridor twice),
Ensure loop closures,
Use a ground robot on a single-level flat ground plane,
Keep the sensor angled downwards to point slightly towards the ground so that it “sees” the ground plane.
Loop closure is supported in the mapping mode, however, even loop closure cannot always compensate for all the drift. Significant drift during mapping can result in very poor height / occupancy maps.
To record a dataset with depth enabled:
################## if using Slamcore tools with GUI ################### $ slamcore_dataset_recorder --depth ################# if using Slamcore tools without GUI ################# $ slamcore_dataset_recorder_cli --depth -o <output-dir> ############################# if using ROS 2 ############################ $ source /opt/ros/foxy/setup.bash $ ros2 launch slamcore_slam dataset_recorder.launch.py \ > override_realsense_depth:=true \ > realsense_depth_override_value:=true \ > output_dir:=<output-dir>
The depth stream is disabled by default on the NVIDIA Jetson platforms,
and must be turned on with the
--depth flag. You do not need to provide
the flag on x64 machines as it is enabled by default.
Step 2 - Prepare the mapping configuration file
When you install the “Slamcore Tools” packages from the Slamcore Portal, the
configuration files are automatically saved under the
directory. You may use the presets best suited for your environment based on the
description in Configuration Overview, or further tune the parameters to create a custom
configuration for your use case.
We recommend creating a new configuration file combining the settings in the
indoor_ground_robot JSON files
that are suitable for generating a high accuracy map, and further tune it based
on your setup.
You can download this file as as a template:
Tracking On Plane
Tracking On Plane enables detection of a flat ground plane and
constrains the pose’s vertical displacement to the plane. If your camera is
mounted rigidly on a wheeled platform in a flat, single-level ground plane
Height and Occupancy Map Generation
Height Mapping Parameters allow you to change settings for the height and
occupancy map. If you require occupancy map images of higher cell size (higher
resolution pixels), you can lower
MaxMapDimensions to limit the memory
usage, and reduce the
CellSize to a minimum of 0.025 metres/pixel. Ensure
that your environment’s square area does not exceed the
You can download this file as a template for high resolution mapping, with a
CellSize of 0.025 and a corresponding
MaxMapDimensions of 30m ×
30m, which is the maximum dimension allowed at that cell size:
Wheel Odometry Integration
Additionally, if you have wheel odometry integrated and obtained a VIK configuration file, you may also include these parameters in the configuration file shown above. You may parse multiple configuration files to Slamcore Tools, for example:
$ slamcore_visualiser dataset -u <path/to/dataset> -m \ > -c high_accuracy_mapping.json vik_odometry_config.json
Step 3 - Create a session map
You cannot process the EuRoC dataset for this tutorial as they don’t offer any depth information.
To enable mapping in the software tools, use the flag
--generate-map2d. The tools accept a dataset or live camera feed. Once the
data is processed, you can save a session file, which will contain the sparse
map and height map.
For this step, you may use any of the following tools:
Using the Slamcore Visualiser
$ slamcore_visualiser dataset -u <path/to/dataset> -m -c high_accuracy_mapping.json
START and wait for the dataset to be processed. Once done, press the
button and save the session file.
See more information about the Visualiser’s user interface for mapping in the Height Mapping Mode section.
Using the CLI Dataset Processor
With the CLI Dataset Processor, you must also enable session saving with the
-s flag and specify an output directory:
$ slamcore_dataset_processor dataset -u <path/to/dataset> -m -s \ > -c high_accuracy_mapping.json -o <output/directory>
Using ROS 2
$ source /opt/ros/foxy/setup.bash $ ros2 launch slamcore_slam slam_publisher.launch.py \ > dataset_path:=<path/to/dataset> \ > config_file:=high_accuracy_mapping.json \ > session_save_dir:=<output/directory> \ > generate_map2d:=true # Save the session once the dataset is fully processed $ ros2 service call /slamcore/save_session std_srvs/srv/Trigger
Memory consumption is expected to grow constantly (but relatively slowly) during mapping.
Step 4 - Inspect Map in Session Explorer
Once the session map is obtained, you may use our Session Explorer tool to inspect and/or edit the map. To start the tool, run:
Open and choose the
.session file to load.
Step 4.1 - Map Editing
There are two ways to edit the occupancy map that has been automatically generated in the session file: by tuning the map extraction, or by updating it with a manually edited image file.
Step 4.1.1 - Tuning Map Extraction
Occupancychannel selected, on the left sidebar, select the
From height mapbutton to edit the map extraction method. Two options are provided: “Gradient” or “Height”. You may tweak the settings for different results in the occupancy map generated. For more information see Occupancy Map.
Once satisfied with the changes, click
OKto confirm or
Cancelto reset. You can also reset to the default configuration later with the
Step 4.1.2 - Import Edited Map
The Slamcore Session Explorer tool also provides a functionality to update the session file by importing an edited occupancy map image. This is useful to map “unknown” areas missed during the session map generation and add or remove obstacles and walls from the map.
Export occupancy pngto export the current map as an image.
Load the image in an image editor software (e.g. GIMP).
Using a pencil tool with a hard brush edge, manually edit the map using only three colours:
Occupied Pixel: Black RGB(0, 0, 0)
Free Pixel: White RGB(255, 255, 255)
Unknown Pixel: Grey RGB(128, 128, 128)
Save the image as an 8-bit Grayscale PNG.
In the Session Explorer tool, with the channel set to
Occupancy, select the
From filebutton on the left side bar and import the edited image. The map will automatically be updated.
The Session Explorer tool does not support other image formats, a different image size or resolution, soft edges, or colours and values not mentioned above.
Step 4.1.3 - Saving Session
Once satisfied with the map, select
Save .session to save the session
map. This edited map can be used in ROS for navigation.
Step 5 - Load Occupancy Map in ROS
To load the occupancy map in ROS 2, parse a session file that contains a height/occupancy map:
$ source /opt/ros/foxy/setup.bash $ ros2 launch slamcore_slam slam_publisher.launch.py session_file:=<path/to/session>
You can now use the occupancy map for obstacle avoidance and robot navigation.