Cartographer Modular Resource

The Cartographer Project contains a C++ library that performs dense Simultaneous Localization And Mapping (SLAM).

To use Cartographer with the Viam SLAM service, you can use the cartographer modular resource.

The source code for this module is available on the viam-cartographer GitHub repository.

Using Cartographer

The cartographer module supports three modes of operation:

• Create a new map
• Update an existing map
• Pure localization

Hardware requirements

RPLidar

• You must have an RPlidar, such as the RPlidar A1 or RPlidar A3, physically connected to your machine.

  Be sure to position the RPlidar so that it faces forward in the direction of travel. For example, if you are using a Viam Rover and the RPlidar A1 model, mount it to the Rover so that the pointed end of the RPlidar mount housing is facing in the same direction as the webcam.

  Furthermore, ensure that the center of the RPlidar is mounted at the center of your machine’s base. In the case of the Viam Rover the center is in the middle between the wheels.

  If you need a mount plate for your RPlidar A1 or A3 model, you can 3D print an adapter plate using the following:

  • RPlidar A1 adapter STL
  • RPlidar A3 adapter STL

• In addition, you must add the rplidar module to your machine to support the RPlidar hardware, if you have not done so already.

  SUPPORT

  Currently, the rplidar and cartographer modules only support the Linux platform.

Movement sensors (optional)

You can use data from one or more movement sensors on your machine to supplement the required LiDAR data. If you choose to use movement sensor data for SLAM, you can:

• Add only inertial measurement unit (IMU) data
  • Requires a movement sensor that supports AngularVelocity and LinearAcceleration readings
• Add only odometry data
  • Requires a movement sensor that collects Position and Orientation data (for example, wheeled-odometry)
• Add both IMU and odometry data
  • Requires all four of the above kinds of data, merged together using the merged movement sensor model
  • If you choose this option, be sure to configure data capture on the merged sensor and not on the individual movement sensors when following the steps below.

Create a new map

To create a new map, follow the instructions below.

{
  "modules": [
    {
      "type": "registry",
      "name": "viam_rplidar",
      "module_id": "viam:rplidar",
      "version": "0.1.16"
    },
    {
      "type": "registry",
      "name": "viam_cartographer",
      "module_id": "viam:cartographer",
      "version": "0.3.45"
    }
  ],
  "services": [
    {
      "attributes": {
        "config_params": {
          "max_range_meters": "25",
          "mode": "2d",
          "min_range_meters": "0.2"
        },
        "camera": {
          "name": "rplidar",
          "data_frequency_hz": "5"
        },
        "enable_mapping": true,
        "use_cloud_slam": false
      },
      "name": "slam",
      "type": "slam",
      "namespace": "rdk",
      "model": "viam:slam:cartographer"
    }
  ],
  "components": [
    {
      "namespace": "rdk",
      "attributes": {},
      "depends_on": [],
      "name": "rplidar",
      "model": "viam:lidar:rplidar",
      "type": "camera"
    }
  ]
}

For more information about the configuration attributes, see Attributes.

After configuring cartographer the machine should begin mapping automatically. Navigate to the CONTROL tab on your machine’s page and click on the dropdown menu matching the name of the service you created. See our tips for making good maps. If you want to save your locally built map, you can use the GetInternalState API or use the local map uploading feature of the cloudslam wrapper module.

Update an existing map

To update an existing map with new pointcloud data from a new SLAM session, follow the instructions below.

1. Configure your cartographer SLAM service using a map from your location:

   • Config Builder
   • JSON Example

   1. Select the Mapping mode dropdown and choose the Update existing map option.
   2. Configure Select map and Map version with the name and version of the map you would like to update. For the other attributes, review the information in Create a new map. You can see more details about the available maps from your machine’s Location page by clicking View SLAM library.

   This example JSON configuration:

   • adds the viam:rplidar and the viam:cartographer modules
   • configures the viam:slam:cartographer service
   • adds an viam:lidar:rplidar camera
   • specifies the slam_map to be updated in the packages

   
   

   {
     "modules": [
       {
         "type": "registry",
         "name": "viam_rplidar",
         "module_id": "viam:rplidar",
         "version": "0.1.16"
       },
       {
         "type": "registry",
         "name": "viam_cartographer",
         "module_id": "viam:cartographer",
         "version": "0.3.45"
       }
     ],
     "services": [
       {
         "attributes": {
           "config_params": {
             "max_range_meters": "25",
             "mode": "2d",
             "min_range_meters": "0.2"
           },
           "camera": {
             "name": "rplidar",
             "data_frequency_hz": "5"
           },
           "enable_mapping": true,
           "use_cloud_slam": false,
           "existing_map": "${packages.slam_map.test-map-1}/internalState.pbstream"
         },
         "name": "slam",
         "type": "slam",
         "namespace": "rdk",
         "model": "viam:slam:cartographer"
       }
     ],
     "components": [
       {
         "namespace": "rdk",
         "attributes": {},
         "depends_on": [],
         "name": "rplidar",
         "model": "viam:lidar:rplidar",
         "type": "camera"
       }
     ],
     "packages": [
       {
         "name": "test-map-1",
         "version": "1697208847",
         "package": "d1c224e8-483e-4cc7-980f-76b89d8fb507/test-map-1",
         "type": "slam_map"
       }
     ]
   }
   

   For more information about the configuration attributes, see Attributes.

   If you want to configure cartographer to use a locally saved map instead, see Using locally built maps.

2. After configuring cartographer the machine should begin mapping automatically. Navigate to the CONTROL tab on your machine’s page and click on the dropdown menu matching the name of the service you created.

See our tips for making a good map! If you want to save your locally built map, you can use the GetInternalState API or use the local map uploading feature of the cloudslam wrapper module

Localize only

In this mode, the cartographer module on your machine executes the Cartographer algorithm to find its position on a map. This mode is better when using motion planning’s MoveOnMap because the map will not be modified.

1. Configure your cartographer SLAM service:

   • Config Builder
   • JSON Example

   1. Select the Mapping mode dropdown and choose the Update existing map option.
   2. Configure Select map and Map version with the name and version of the map you would like to localize on. For the other attributes, review the information in Create a new map. You can see more details about the available maps from your machine’s Location page by clicking View SLAM library.

   This example JSON configuration:

   • adds the viam:rplidar and the viam:cartographer modules
   • configures the viam:slam:cartographer service
   • adds an viam:lidar:rplidar
   • specifies the slam_map for localization in the packages

   
   

   {
     "modules": [
       {
         "type": "registry",
         "name": "viam_rplidar",
         "module_id": "viam:rplidar",
         "version": "0.1.16"
       },
       {
         "type": "registry",
         "name": "viam_cartographer",
         "module_id": "viam:cartographer",
         "version": "0.3.45"
       }
     ],
     "services": [
       {
         "type": "slam",
         "namespace": "rdk",
         "model": "viam:slam:cartographer",
         "attributes": {
           "config_params": {
             "min_range_meters": "0.2",
             "max_range_meters": "25",
             "mode": "2d"
           },
           "camera": {
             "name": "rplidar",
             "data_frequency_hz": "5"
           },
           "enable_mapping": false,
           "use_cloud_slam": false,
           "existing_map": "${packages.slam_map.test-map-1}/internalState.pbstream"
         },
         "name": "slam"
       }
     ],
     "components": [
       {
         "model": "viam:lidar:rplidar",
         "type": "camera",
         "namespace": "rdk",
         "attributes": {},
         "depends_on": [],
         "name": "rplidar"
       }
     ],
     "packages": [
       {
         "type": "slam_map",
         "name": "test-map-1",
         "version": "1697208847",
         "package": "d1c224e8-483e-4cc7-980f-76b89d8fb507/test-map-1"
       }
     ]
   }
   

   For more information about the configuration attributes, see Attributes.

   If you want to configure cartographer to use a locally saved map instead, see Using locally built maps.

2. After configuring cartographer on the machine, the map should appear automatically. Navigate to the CONTROL tab on your machine’s page and click on the dropdown menu matching the name of the service you created.

   Info

   Cartographer may take several minutes to find your machine’s position on the existing map. In the meantime, your machine will show up at the map’s origin (with the (x,y) coordinates (0,0)).

   If you move your machine, it will appear to be moving in a trajectory from the map’s origin.

Attributes

config_params

For more information, see the Cartographer algorithm walkthrough, tuning overview, and config parameter list.

Using locally built maps

You can see details about the available maps from your machine’s Location page by clicking View SLAM library. If you do not have any maps, and you do not wish to use cloudslam, but you still want to use localizing and updating modes with cartographer, you can take the following steps.

1. Save a .pbstream file by using the GetInternalState or InternalStateFull APIs by using one of the SDKs. Note, InternalStateFull is currently only implemented in Go.
2. Ensure the .pbstream file is located somewhere on the machine, and note the directory path to that file.
3. In your cartographer’s config, update the existing_map field with the path to the file that was noted in #2.

your config should look something like the following:

{
  "modules": [
    {
      "type": "registry",
      "name": "viam_rplidar",
      "module_id": "viam:rplidar",
      "version": "0.1.16"
    },
    {
      "type": "registry",
      "name": "viam_cartographer",
      "module_id": "viam:cartographer",
      "version": "0.3.45"
    }
  ],
  "services": [
    {
      "attributes": {
        "config_params": {
          "max_range_meters": "25",
          "mode": "2d",
          "min_range_meters": "0.2"
        },
        "camera": {
          "name": "rplidar",
          "data_frequency_hz": "5"
        },
        "enable_mapping": true,
        "use_cloud_slam": false,
        "existing_map": "/PATH/TO/FILE/<INTERNAL-STATE-NAME>.pbstream"
      },
      "name": "slam",
      "type": "slam",
      "namespace": "rdk",
      "model": "viam:slam:cartographer"
    }
  ],
  "components": [
    {
      "namespace": "rdk",
      "attributes": {},
      "depends_on": [],
      "name": "rplidar",
      "model": "viam:lidar:rplidar",
      "type": "camera"
    }
  ],
  "packages": []
}

Now your cartographer service should be running using your locally saved map.