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.

_images/occupancy_mapping_tutorial_flowchart.png

Fig. 69 Occupancy Mapping Flowchart

Requirements

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 Foxy or Galactic or Humble package v21.06 or above (see Slamcore ROS 2 Wrapper)

  • An environment with a single ground plane (multi-level floors or slopes are not supported)

Warning

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

Please contact support@slamcore.com, 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.

Usage

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.

Note

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>

Warning

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 /usr/share/slamcore/presets 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 high_accuracy, mapping/default and 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: high_accuracy_mapping.json

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 environment, set DoTrackingOnPlane to true.

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 MaxMapDimensions you’ve set.

You can download this file as a template for high resolution mapping, with a reduced CellSize of 0.025 and a corresponding MaxMapDimensions of 30m × 30m, which is the maximum dimension allowed at that cell size: high_resolution_mapping.json.

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

Note

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 -m or --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

Press START and wait for the dataset to be processed. Once done, press the SAVE button and save the session file.

Note

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

Warning

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:

$ slamcore_session_explorer

Select File and 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

  1. With the Occupancy channel selected, on the left sidebar, select the From height map button 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.

  2. Once satisfied with the changes, click OK to confirm or Cancel to reset. You can also reset to the default configuration later with the Reset button.

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.

  1. Select File and Export occupancy png to export the current map as an image.

  2. Load the image in an image editor software (e.g. GIMP).

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

  4. Save the image as an 8-bit Grayscale PNG.

  5. In the Session Explorer tool, with the channel set to Occupancy, select the From file button on the left side bar and import the edited image. The map will automatically be updated.

Warning

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