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

{
  "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"
  }
}

"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:

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

config_params

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

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.