Cartographer Integrated Library

The Cartographer Project performs dense SLAM using LIDAR data.

Requirements

Install the binary required to utilize the cartographer library on your machine and make it executable by running the following commands according to your machine’s architecture:

sudo curl -o /usr/local/bin/cartographer-module https://storage.googleapis.com/packages.viam.com/apps/slam-servers/cartographer-module-stable-aarch64.AppImage
sudo chmod a+rx /usr/local/bin/cartographer-module
sudo curl -o /usr/local/bin/cartographer-module https://storage.googleapis.com/packages.viam.com/apps/slam-servers/cartographer-module-stable-x86_64.AppImage
sudo chmod a+rx /usr/local/bin/cartographer-module
brew tap viamrobotics/brews && brew install cartographer-module

Configuration

Add a SLAM Service

Go to your robot’s page on the Viam app. Navigate to the Config tab on your robot’s page, and click on the Services subtab.

Add a service with type slam, model viam:slam:cartographer, and a name of your choice:

adding cartographer slam service

Paste the following into the Attributes field of your new service:

{
  "data_dir": "/home/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
  "delete_processed_data": true,
  "sensors": ["<YOUR_RPLIDAR_COMPONENT_NAME>"],
  "config_params": {
    "mode": "2d"
  }
}
{
  "data_dir": "/Users/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
  "delete_processed_data": true,
  "sensors": ["<YOUR_RPLIDAR_COMPONENT_NAME>"],
  "config_params": {
    "mode": "2d"
  }
}

Click on the Modules subtab. Add the cartographer module with a name of your choice and an executable path that points to the location of your installed cartographer-module binary:

Go to your robot’s page on the Viam app. Navigate to the Config tab. Select the Raw JSON mode, then copy/paste the following "services" and "modules" JSON to add to your existing RPlidar configuration:

"modules": [
  // { ...}, YOUR RPLIDAR MODULE,
  {
    "executable_path": "/usr/local/bin/cartographer-module",
    "name": "cartographer-module"
  }
],
// "components": [ ...], YOUR RPLIDAR MODULAR COMPONENT,
"services": [
  {
    "model": "viam:slam:cartographer",
    "name": "<your-service-name>",
    "type": "slam",
    "attributes": {
      "data_dir": "/home/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
      "delete_processed_data": true,
      "sensors": ["<YOUR_RPLIDAR_COMPONENT_NAME>"],
      "config_params": {
        "mode": "2d"
      }
    }
  }
]
"modules": [
  // { ...}, YOUR RPLIDAR MODULE,
  {
    "executable_path": "/usr/local/bin/cartographer-module",
    "name": "cartographer-module"
  }
],
// "components": [ ...], YOUR RPLIDAR MODULAR COMPONENT,
"services": [
  {
    "model": "viam:slam:cartographer",
    "name": "<your-service-name>",
    "type": "slam",
    "attributes": {
      "data_dir": "/Users/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
      "delete_processed_data": true,
      "sensors": ["<YOUR_RPLIDAR_COMPONENT_NAME>"],
      "config_params": {
        "mode": "2d"
      }
    }
  }
]
"modules": [
  // { ...}, YOUR RPLIDAR MODULE,
  {
    "executable_path": "/opt/homebrew/bin/cartographer-module",
    "name": "cartographer-module"
  }
],
// "components": [ ...], YOUR RPLIDAR MODULAR COMPONENT,
"services": [
  {
    "model": "viam:slam:cartographer",
    "name": "<your-service-name>",
    "type": "slam",
    "attributes": {
      "data_dir": "/Users/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
      "delete_processed_data": true,
      "sensors": ["<YOUR_RPLIDAR_COMPONENT_NAME>"],
      "config_params": {
        "mode": "2d"
      }
    }
  }
]

Adjust data_dir

Change the data_dir attribute to point to a directory on your machine where you want to save the sensor data your SLAM service uses and the maps and config files it produces.

This directory must be structured as follows:

.
└──\(CARTOGRAPHER_DIR)
    ├── map
    ├── data
    └── config

Click through the following tabs to see the usage of each folder in this directory:

Whether mapping data is present in map at runtime and the attribute map_rate_sec determines the SLAM mapping mode:

Mapping Modes

ModeDescriptionRuntime Dictation
PURE MAPPINGGenerate a new map in /map.No map is found in /map.
UPDATINGUpdate an existing map with new /data.A map is found in /map + map_rate_sec > 0.
LOCALIZINGLocalize the robot on an existing map without changing the map itself.A map is found in /map + map_rate_sec = 0.

The data folder stores the LIDAR data gathered by your RPlidar and used for SLAM.

The config folder stores any Cartographer specific config files created. These are generated at runtime, so there is no need to add anything to this folder.

View the Map

After saving your config and connecting to your robot, navigate to the Control tab on your robot’s page and click on the drop-down menu matching the name of the service you created.

Change the Refresh frequency to your desired frequency. Move your RPlidar around slowly. Watch a map start to appear.

Attributes

NameData TypeInclusionDescription
data_dirstringRequiredPath to the directory used for saving input LIDAR data in /data and output mapping data in /map.
sensorsstring[]RequiredNames of configured RPlidar devices providing data to the SLAM service.
map_rate_secintOptionalRate of /map generation (seconds).
    Default: 60.
data_rate_msecintOptionalRate of /data collection from sensors (milliseconds).
    Default: 200.
portstringOptionalPort for SLAM gRPC server. If running locally, this should be in the form “localhost:”. If no value is specified a random available port is assigned.
delete_processed_databoolOptional

Setting this to true helps to reduce the amount of memory required to run SLAM.

    true: sensor data is deleted after the SLAM algorithm has processed it.
    false: sensor data is not deleted after the SLAM algorithm has processed it.
config_paramsmap[string] stringOptionalParameters available to fine-tune the cartographer algorithm: read more below.

config_params

Adjust these parameters to fine-tune the algorithm cartographer utilizes in aspects like submap size, mapping update rate, and feature matching details:

Parameter ModeDescriptionInclusionDefault ValueNotes
mode2dRequiredNone
optimize_every_n_nodesHow many trajectory nodes are inserted before the global optimization is run.Optional3
num_range_dataNumber of measurements in each submap.Optional100
missing_data_ray_lengthReplaces the length of ranges that are further than max_range with this value.Optional25Nominally set to max length.
max_rangeMaximum range of valid measurements.Optional25For an RPlidar A3, set this value to 25. For an RPlidar A1, use 12.
min_rangeMinimum range of valid measurements.Optional0.2For an RPlidar A3, set this value to 0.2. For RPlidar A1, use 0.15.
max_submaps_to_keepNumber of submaps to use and track for localization.Optional3Only for LOCALIZING mode.
fresh_submaps_countLength of submap history considered when running SLAM in updating mode.Optional3Only for UPDATING mode.
min_covered_areaThe minimum overlapping area, in square meters, for an old submap to be considered for deletion.Optional1.0Only for UPDATING mode.
min_added_submaps_countThe minimum number of added submaps before deletion of the old submap is considered.Optional1Only for UPDATING mode.
occupied_space_weightEmphasis to put on scanned data points between measurements.Optional20.0
translation_weightEmphasis to put on expected translational change from pose extrapolator data between measurements.Optional10.0
rotation_weightEmphasis to put on expected rotational change from pose extrapolator data between measurements.Optional1.0

Troubleshooting

Tip: Lidar Mounting for the Viam Rover

If you have a Viam Rover and need a mount for your RPLidar, you can 3D print an adapter plate. The STL file for an adapter plate is available on GitHub.

Known Issues

Maps not appearing in UI

When generating a larger map, it will take longer for Cartographer to return the desired map. This can result in errors or failed requests for a map, however, this will not affect the viam-server or cartographer-module process. Re-requesting the map can and should be successful, although there is currently a fundamental limit for the size of map that can be transmitted to the UI and this issue will become more common as you approach it.

You can find additional assistance in the Troubleshooting section.



Have questions, or want to meet other people working on robots? Join our Community Discord.