SLAM Service

Introduction

Simultaneous Localization And Mapping (SLAM) allows your robot to create a map of its surroundings and find its location within that map. SLAM is an important area of ongoing research in robotics, particularly for mobile applications such as drones, boats, and rovers.

The Viam SLAM Service supports the integration of SLAM as a service on your robot. The following SLAM libraries are integrated:

Requirements

Install the binaries required to utilize these libraries on your machine by running the following commands:

Cartographer:

sudo curl -o /usr/local/bin/carto_grpc_server http://packages.viam.com/apps/slam-servers/carto_grpc_server-stable-aarch64.AppImage
sudo chmod a+rx /usr/local/bin/carto_grpc_server
sudo curl -o /usr/local/bin/carto_grpc_server http://packages.viam.com/apps/slam-servers/carto_grpc_server-stable-x86_64.AppImage
sudo chmod a+rx /usr/local/bin/carto_grpc_server
brew tap viamrobotics/brews && brew install carto-grpc-server

ORB-SLAM3:

sudo curl -o /usr/local/bin/orb_grpc_server http://packages.viam.com/apps/slam-servers/orb_grpc_server-stable-aarch64.AppImage
sudo chmod a+rx /usr/local/bin/orb_grpc_server
sudo curl -o /usr/local/bin/orb_grpc_server http://packages.viam.com/apps/slam-servers/orb_grpc_server-stable-x86_64.AppImage
sudo chmod a+rx /usr/local/bin/orb_grpc_server

Configuration

You can configure your robot to use SLAM on the Viam app. Navigate to the CONFIG tab on your robot’s page, and from there, navigate to the SERVICES subtab.

Add a service with type slam, whatever name you want, and the model of the library you want to use.

Use this JSON template to configure the service with the ORB-SLAM3 library, and this JSON template to configure the service with the Cartographer library. Then, adjust general attributes and library-specific config-params.

General Attributes

NameData TypeInclusionDescription
data_dirstringRequiredThis is the data directory used for saving input sensor/map data and output map/ visualizations. Must be structured as specified here.
sensorsstring[]RequiredNames of configured camera components providing data to the SLAM service.
use_live_databoolRequired

This specifies whether to run in Live or Offline mode.

    true: Live mode. The service grabs the most recent sensor readings and uses those to perform SLAM. If no sensors are provided, an error will be thrown.
    false: Offline mode. The service uses image data stored in the data directory to perform SLAM.
map_rate_secintOptionalMap generation rate for saving current state (seconds).
    Default: 60.
data_rate_msecintOptionalData generation rate for collecting sensor data to feed to SLAM (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 specific to the model of SLAM library.

config_params

The config_params attribute is populated with parameters that are unique to the SLAM library being used.

You can use these parameters to fine-tune the algorithms these libraries utilize in aspects like submap size, mapping update rate, and feature matching details.

To see library-specific config_params available, navigate to these sections:

data_dir: Data Directory

A running SLAM Service saves the sensor data it uses and the maps and config files it produces locally on the device in the directory path specified by the General Attribute data_dir.

To recap, the directory must be structured as follows:

.
└──\(The Directory Defined in Config as `data_dir`)
    ├── data
    ├── map
    └── config
  • data contains all the sensor data collected from the sensors listed in sensors, saved at data_rate_msec.
  • map contains the generated maps, saved at map_rate_sec.
  • config contains all SLAM library specific config files.

Mapping Modes

These modes dictate SLAM’s mapping behavior at runtime, but are not configured as a part of the SLAM service’s JSON configuration. The mode utilized by the SLAM service is determined by the information found in the data directory at runtime.

ModeDescriptionDictation
PURE MAPPINGIn PURE MAPPING mode, a new map is generated from scratch.This mode is triggered if no map is found in the data_dir/map directory at runtime.
UPDATINGIn UPDATING mode, an existing map is being changed and updated with new data.This mode is triggered when a map is found in the data_dir/map directory at runtime if the attribute "map_rate_sec" is > 0.
LOCALIZINGIn LOCALIZING mode, the map is not changed. Data is used to localize on an existing map. This is similar to UPDATING mode, except the loaded map is not changed.This mode is triggered when a map is found in the data_dir/map directory at runtime if the attribute "map_rate_sec" = 0.

Integrated Library: Cartographer

Cartographer performs dense SLAM using LIDAR data.

Specify whether this LIDAR data is preloaded or collected live by a Rplidar device with the attribute use_live_data.

Example Configuration

Live Mode

To run Cartographer in live mode, follow these instructions to add your Rplidar device as a modular component of your robot, and refer to this example configuration:

{
  "modules": [
    {
      "name": "rplidar_module",
      "executable_path": "/home/<YOUR_USERNAME>/rplidar-module-local-aarch64.AppImage"
    }
  ],
  "components": [
    {
      "namespace": "rdk",
      "type": "camera",
      "depends_on": [],
      "model": "viam:lidar:rplidar",
      "name": "rplidar"
    }
  ],
  "services": [
    {
      "type": "slam",
      "attributes": {
        "config_params": {
          "min_range": "0.3",
          "max_range": "12",
          "mode": "2d"
        },
        "data_rate_msec": 200,
        "delete_processed_data": false,
        "use_live_data": true,
        "sensors": [
          "rplidar"
        ],
        "port": "localhost:8083",
        "data_dir": "/home/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
        "map_rate_sec": 60
      },
        "model": "cartographer",
        "name": "run-slam"
    }
  ]
}
{
  "components": [
    {
      "namespace": "rdk",
      "type": "camera",
      "depends_on": [],
      "model": "viam:lidar:rplidar",
      "attributes": {
        "device_path": "/dev/tty.SLAB_USBtoUART"
      },
      "name": "rplidar"
    }
  ],
  "services": [
    {
      "attributes": {
        "map_rate_sec": 60,
        "data_rate_msec": 200,
        "use_live_data": true,
        "sensors": [
          "rplidar"
        ],
        "config_params": {
          "mode": "2d",
          "min_range": "0.3",
          "max_range": "12"
        },
        "port": "localhost:8083",
        "data_dir": "/Users/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
        "delete_processed_data": false
      },
      "model": "cartographer",
      "name": "run-slam",
      "type": "slam"
    }
  ],
  "modules": [
    {
      "executable_path": "/Users/<YOUR_USERNAME>/rplidar/bin/rplidar-module",
      "name": "rplidar_module"
    }
  ]
}

Offline Mode

Refer to this example configuration for running Cartographer SLAM in offline mode:

    {
      "services": [
        {
          "attributes": {
            "config_params": {
              "min_range": "0.3",
              "max_range": "12",
              "mode": "2d"
            },
            "data_dir": "/home/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>/data",
            "map_rate_sec": 60,
            "data_rate_msec": 200,
            "delete_processed_data": false,
            "use_live_data": false,
            "sensors": []
          },
          "model": "cartographer",
          "name": "run-slam-offline",
          "type": "slam"
        }
      ]
    }

For more information about running Cartographer in Offline Mode, see this tutorial.

Cartographer config_params

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.Optional25
min_rangeMinimum range of valid measurements.Optional0.2
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.0Normalized with translational and rotational.
translation_weightEmphasis to put on expected translational change from pose extrapolator data between measurements.Optional10.0Normalized with occupied and rotational.
rotation_weightEmphasis to put on expected rotational change from pose extrapolator data between measurements.Optional1.0Normalized with translational and occupied.

Integrated Library: ORB-SLAM3

ORB-SLAM3 can perform sparse SLAM using monocular or RGB-D images.

Example Configuration

Live Mode

An example configuration for running ORB-SLAM3 in live mode, with rgbd image data, with two camera streams available (color for RGB images and depth for depth data):

"services": [
  {
    "name": "testorb",
    "model": "orbslamv3",
    "type": "slam",
    "attributes": {
      "data_dir": "/home/<YOUR_USERNAME>/<ORBSLAM_DIR>",
      "sensors": ["color", "depth"],
      "use_live_data": true,
      "map_rate_sec": 60,
      "data_rate_msec": 200,
      "config_params": {
        "mode": "rgbd"
      }
    }
  }
]

Offline Mode

An example configuration for running ORB-SLAM3 in offline mode:

"services": [
  {
    "name": "testorb",
    "model": "orbslamv3",
    "type": "slam",
    "attributes": {
      "data_dir": "/home/<YOUR_USERNAME>/<ORBSLAM_DIR>",
      "sensors": [],
      "use_live_data": false,
      "map_rate_sec": 120,
      "data_rate_msec": 100,
      "config_params": {
        "mode": "mono"
      }
    }
  }
]

ORB-SLAM3 config_params

Parameter ModeDescriptionInclusionDefault Value
modergbd or monoRequiredNo default
debugBoolean specifying if the service should be run in debug mode. Affects log output.Optionalfalse
orb_n_featuresNumber of features per image.Optional1250
orb_scale_factorScale factor between levels in the scale pyramid.Optional1.2
orb_n_levelsNumber of levels in the scale pyramid.Optional8
orb_n_ini_th_fastInitial FAST threshold.Optional20
orb_n_min_th_fastLower threshold if no corners detected.Optional7
stereo_th_depthNumber of stereo baselines used to classify a point as close or far. Close and far points are treated differently in several parts of the stereo SLAM algorithm.Optional40
depth_map_factorFactor to transform the depth map to real units.Optional1000
stereo_bStereo baseline in meters.Optional0.0745


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