Slamcore ROS1 Wrapper

Software Prerequisites

A working ROS1 installation is required before installing the Slamcore ROS1 Wrapper. More specifically ros-melodic-ros-base should be installed while the desktop packages are optional. To get started with ROS1 you can follow the instructions provided here:

ROS1 Wrapper Layout

The ROS1 wrapper allows you interaction with Slamcore software via ROS Melodic. To allow for maximum flexibility it is split into two separate Debian packages:

  • slamcore-ros

    Consists of the core functionality for communicating with the Slamcore SLAM software over ROS1 (publish estimated pose and map via ROS1 topics, reset SLAM via ROS services etc.) and has the minimum amount of package dependencies, namely the ros-base.

  • slamcore-viz

    Provides a set of nodes and GUIs to better visualise the overall SLAM process. More specifically, it offers a customised rviz view of the camera images, as well as the estimated pose and sparse map of the environment. It also allows interaction with the SLAM process via rqt (Reset SLAM, toggle streams, save session etc.).

This distinction makes slamcore-ros ideal if you want to use Slamcore software over ROS1 but don’t want to bring the whole ROS1 visualisation stack as a dependency. On top of that you can optionally also install slamcore-viz to facilitate the SLAM visualisation.

Finally, here is a more detailed view of the components of each Debian package and how these translate into ROS packages and corresponding components:

slamcore_ros                           <-- Debian Package / ROS Metapackage
│
├── slamcore_bridge                    <-- ROS Package - handles the Slamcore <-> ROS conversions
│
└── slamcore_slam                      <-- ROS Package - handles Interaction with the SLAM engine
    │
    └── slam_publisher                 <-- Main ROS node handling the publishing of SLAM data
    └── dataset_recorder               <-- ROS node handling the recording of datasets
    └── run_slam.launch                <-- Launchfile - wraps slam_publisher
    └── run_dataset_recorder.launch    <-- Launchfile - wraps dataset recorder

slamcore_viz                           <-- Debian Package / ROS Package
│
├── setup_monitoring.launch            <-- Main launchfile - Delegates to rqt, rviz accordingly
├── rqt/slam.perspective
├── rviz/slamcore.rviz
└── scripts
    ├── local_publisher.py             <-- Accumulates individual pose messages, dumps nav_msgs::Path
    │                                      messages to visualise in rviz.
    │
    └── republish_viz_node.py          <-- Republishes /slamcore/{Visible,Infrared}_N messages
                                           on /slamcore/imageN

Installation

Obtain the ROS1 wrapper package(s) from the Download Slamcore Software link on the Slamcore Portal.

Install the packages using apt or an apt-based tool to automatically resolve dependencies.

# Update the list of available packages
$ sudo apt update

# To understand what will be installed, use a command like:
$ apt install --dry-run /path/to/ros-melodic-slamcore-ros*.deb
#                       ^~~~~ Specify the .deb file.

# To Install the slamcore_ros Debian package, use a command like:
$ sudo apt install /path/to/ros-melodic-slamcore-ros*.deb
#                  ^~~~~~~~~~ Specify the .deb file.

Repeat the installation step if you also want to install slamcore-viz.

Usage - SLAM

Our ROS1 node streams poses only when the tracking status is OK.

Note

Make sure you have sourced the setup.bash (adjust suffix according to your shell) before running any of the ROS1 nodes or launchfiles provided.

Live SLAM

Following is an example use case of running Single Session SLAM. Before running it, make sure you have plugged in a registered, supported camera and have sourced the ROS environment.

$ source /opt/ros/melodic/setup.bash

Launch live SLAM with the following command:

$ roslaunch slamcore_slam run_slam.launch

In a new terminal, verify that the node is streaming poses:

$ source /opt/ros/melodic/setup.bash
$ rostopic echo /slamcore/pose

Expect output in the form:

#   header:
#     stamp:
#       sec: 377
#       nanosec: 598881764
#     frame_id: slamcore_map
#   pose:
#     position:
#       x: -0.02378664211846218
#       y: 0.041697142300108944
#       z: -0.10841154367750798
#     orientation:
#       x: 0.12618178364483054
#       y: -0.6937589654026391
#       z: 0.12688238138290922
#       w: 0.6976227610207906

To save a SLAM session in ROS, call the /slamcore/save_session service:

$ rosservice call /slamcore/save_session

The session maps are saved in the ~/.ros/ directory by default.

Note

It is possible to record a dataset whilst running live SLAM. See Dataset Recording during a SLAM run for more information.

SLAM using a recorded dataset

To run SLAM using a prerecorded dataset instead of a live camera you have to set the path to the dataset using either the dataset_path roslaunch argument or using the /slamcore/dataset_path ROS1 parameter:

# set parameter and run
$ roslaunch slamcore_slam run_slam.launch dataset_path:=</path/to/dataset>

VIO Mode

To run in Visual-Inertial Odometry mode, launch the SLAM node whilst passing in the following JSON configuration file:

{
    "Version": "1.0.0",
    "Base":
    {
        "ProfileName": "vio_mode"
    },
    "Position":
    {
        "PositioningMode": "ODOMETRY_ONLY",
    }
}

Launch with:

$ roslaunch slamcore_slam run_slam.launch config_file:=</path/to/vio.json>

Learn more about VIO in the Visual-Inertial Odometry Positioning tutorial.

Localisation Mode

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.

In localisation mode, our system uses a previously created session map. To load a session map, provide the full path to the session file when launching the SLAM wrapper ROS1 node, e.g.:

$ roslaunch slamcore_slam run_slam.launch session_file:=/home/<user>/<path/to/session/file>

Height Mapping Mode

In mapping mode, our system runs in SLAM mode but also generates a height map and an occupancy map which can be used in autonomous navigation.

To generate a height map, set the generate_map2d parameter to true and ensure the depth stream is enabled (true by default on x64, false by default on arm64):

$ roslaunch slamcore_slam run_slam.launch generate_map2d:=true override_realsense_depth:=true realsense_depth_override_value:=true

Usage - Dataset Recording

It is possible to record a dataset with our standalone Dataset Recorder node or whilst running SLAM.

Dataset Recording during a SLAM run

To record a dataset while SLAM is running, simply provide the dataset_write_path when launching run_slam.launch.

$ roslaunch slamcore_slam run_slam.launch dataset_write_path:=/home/<user>/<output-directory>

All streams that have been enabled will be recorded to the provided directory, taking into account any camera configuration settings that may have been loaded on launch using a JSON config_file, e.g., config_file:=$HOME/depth_preset.json.

Standalone Dataset Recorder

To record a dataset with our standalone Dataset Recorder, without running SLAM, run:

$ roslaunch slamcore_slam run_dataset_recorder.launch output_dir:=/home/<user>/<output-directory>

By default, the dataset will be saved in ~/.ros/output, unless the output_dir argument is specified. When recording a dataset, you can also provide a config file, for example to adjust the camera/depth settings config_file:=$HOME/depth_preset.json.

See the Troubleshooting page to help diagnose common errors.

ROS1 Visualisation

Note

Please install the slamcore-viz Debian package to use the tools described in this section.

You can visualise the advertised topics as well as interact with SLAM via the slamcore_viz ROS1 package and its setup_monitoring.launch launchfile.

First, launch the Slamcore ROS1 node to record a dataset or start SLAM as mentioned above. Then, to enable the visualisation in rviz, run on another terminal:

$ roslaunch slamcore_viz setup_monitoring.launch

OR to enable visualisation in rviz and control SLAM execution in rqt:

$ roslaunch slamcore_viz setup_monitoring.launch launch_rqt:=true

When executed, rviz and rqt are launched for visualising and controlling SLAM execution respectively. Following are sample rviz and rqt views when launching:

_images/rviz_view.png

Fig. 17 RVIZ - User Interface

_images/rqt_view.png

Fig. 18 RQT - User Interface

ROS1 API

This section outlines the topics, services, and parameters that the Slamcore ROS1 Wrapper uses as either inputs or outputs.

Advertised Topics

List of topics advertised by slam_publisher:

  • /diagnostics
  • /slamcore/accel

    • Type: sensor_msgs/Imu

    • Description: Accelerometer data, interpolated to align with the gyroscope measurements.

  • /slamcore/gyro
  • /slamcore/{infrared, visual, depth}{, _0, _1, …}/camera_info
  • /slamcore/{infrared, visual}{_0, _1, …}/image_raw
  • /slamcore/depth/image_raw

    • Type: sensor_msgs/Image

    • Description: Depth data. Data is provided with float encoding, where each pixel value is the depth in metres.

  • /slamcore/local_point_cloud
  • /slamcore/metadata/{num_features, tracked_features, tracking_status, slam_event}

    • Type: std_msgs/Int64

    • Description: Metadata published periodically by the SLAM algorithm. See Tracking Information for more information on available tracking statuses and SLAM events.

  • /slamcore/metadata/{distance_travelled}

    • Type: std_msgs/Float64

    • Description: Distance travelled (metres) published periodically by the SLAM algorithm.

  • /slamcore/pose
  • /slamcore/odom

    • Type: nav_msgs/Odometry

    • Description: Smooth Pose, and Twist of the sensor. The pose is in the odometry frame of reference (see the /slamcore/odom_frame ROS Parameter) and the twist is in the instantaneous body frame of the sensor (see the /slamcore/base_frame ROS Parameter).

  • /slamcore/sparse_map
  • /slamcore/map
  • /tf
  • /tf_static

Run the following to view the full list of topics:

$ rostopic list

Advertised Services

Following is the list of services advertised by slam_publisher. These are used mainly for interaction of the client/user with the SLAM machine. Run the following to call the service:

$ rosservice call /slamcore/<service-name>

List of advertised services:

  • /slamcore/reset_signal

    • Type: std_srvs/Trigger

    • Description: Reset SLAM execution. After this call, SLAM automatically restarts. If you are running from a dataset this call will reset the dataset to the beginning.

  • /slamcore/save_session

    • Type: std_srvs/Trigger

    • Description: Save session map file (saved in the ~/.ros/ directory by default).

  • /slamcore/static_map

    • Type: nav_msgs/GetMap

    • Description: Retrieve the static map (only advertised if loading from a session file).

Run the following to view the full list of services:

$ rosservice list

Advertised Parameters

Following is the list of parameters that slam_publisher fetches during initialisation. For each one of the mentioned parameters there is a corresponding roslaunch argument when using run_slam.launch or run_dataset_recorder.launch. Thus there are two ways of setting them:

Set the parameter manually before the run:

$ rosparam set /slamcore/<param-name> <desired-value>       # for run_slam.launch OR
$ rosparam set /dataset_recorder/<param-name> <desired-value> # for run_dataset_recorder.launch

$ rosrun slamcore_slam slam_publisher

Alternatively, set it via the corresponding roslaunch argument:

$ roslaunch slamcore_slam run_slam.launch <param-name>:=<desired-value>             # for run_slam.launch OR
$ roslaunch slamcore_slam run_dataset_recorder.launch <param-name>:=<desired-value> # for run_dataset_recorder.launch

Note

The full path(s) must be provided for the relevant parameter values. E.g. /home/<user>/<path/to/file>.

  • /slamcore/slam_node/device_id

    • Type: String

    • Description: Integer device index for multiple reader types.

  • /slamcore/config_file

    • Type: String

    • Description: Path to the configuration file override (see Configuration Overview). One can provide a single config file, e.g. config_file:=/usr/share/slamcore/presets/outdoor.json, or multiple config files as a list config_file:=[/usr/share/slamcore/presets/outdoor.json,$HOME/depth_preset.json].

  • /slamcore/publish_hw_timestamps

    • Type: Boolean

    • Default: False

    • Description: Specify whether to publish measurements with hardware or system-clock based timestamps (details).

  • /slamcore/advertise_images

    • Type: Boolean

    • Default: True

    • Description: Advertise images.

  • /slamcore/override_realsense_depth

    • Type: Boolean

    • Default: False

    • Description: Overwrite the depth stream, and therefore the depth topic for a RealSense, with the value provided with /slamcore/realsense_depth_override_value camera. See FAQs for more information.

  • /slamcore/realsense_depth_override_value

    • Type: Boolean

    • Default: True

    • Description: Overwrite the depth stream, and therefore the depth topic for a RealSense camera. See FAQs for more information.

  • /slamcore/enable_color

    • Type: Boolean

    • Default: False

    • Description: Publish RGB image.

  • /slamcore/generate_map2d

    • Type: Boolean

    • Default: False

    • Description: Generate a new 2D map (Requires depth to be ON).

  • /slamcore/session_file

    • Type: String

    • Description: Path to the session map to load to run in localisation mode (details).

  • /slamcore/session_save_dir

    • Type: String

    • Default: ~/.ros

    • Description: Specify directory to save session map at. If none is provided, maps will be saved to the node’s current working directory, usually ~/.ros.

  • /dataset_recorder/odom_reading_topic

    • Type: String

    • Default: None

    • Description: Odometry input topic to subscribe to. The slam_publisher and dataset_recorder will listen on this topic for nav_msgs/Odometry messages. A VIK calibration is required to run SLAM with wheel odometry, see the Wheel Odometry Integration tutorial.

  • /slamcore/map_frame
  • /slamcore/odom_frame
  • /slamcore/base_frame
  • /slamcore/dataset_write_path

    • Type: String

    • Description: Directory to save dataset to whilst running live SLAM. If none is provided, no streams will be recorded during the SLAM run.

  • /slamcore/dataset_path

    • Type: String

    • Description: Path to the recorded dataset to run SLAM with (details).

  • /slamcore/dataset_timescale

    • Type: Float

    • Description: Control the playback speed by selecting a playback timescale. Setting it to values greater than zero sets a corresponding playback speed, and setting the timescale to 1.0 will play back in emulated real time. If no timescale is specified the playback will run as fast as possible to process every frame.

  • /dataset_recorder/output_dir

    • Type: String

    • Default: ~/.ros/output

    • Description: Specify directory to save the recorded dataset at. If none is provided, maps will be saved to the default directory.

  • /dataset_recorder/odom_reading_topic

    • Type: String

    • Default: /odom

    • Description: Odometry input topic to subscribe to.

Host and device timestamps

To abide by the ROS1 common practices, and to facilitate using the SLAM output in other ROS1 nodes, the slam_publisher node publishes messages timestamped in the host computer timeline (using the synchronised camera timestamp if the hardware supports it; this is currently only supported for the D435i and D455). Alternatively, you can switch to the original camera timestamps by using the /slamcore/publish_hw_timestamps ROS1 parameter:

# set parameter and run
$ roslaunch slamcore_slam run_slam.launch publish_hw_timestamps:=true

Note

The slam_publisher adjusts the hardware timestamps in this mode to ensure the clock is monotonic. This differs from the internal timestamps of the D435i.

See Fig. 19 below for more details on the differences between the two types of timestamps:

_images/camera_host_timelines.png

Fig. 19 Camera and Host Timelines

To make a clear separation and avoid mixing data from different timelines, if you instruct the slam_publisher to use the hardware timestamps, then the names of the advertised topics will be suffixed with _hw.

$ roslaunch slamcore_slam run_slam.launch publish_hw_timestamps:=true

$ rostopic list
/rosout
/rosout_agg
/slamcore/accel_hw
/slamcore/depth_hw/camera_info
/slamcore/depth_hw/image_raw
/slamcore/gyro_hw
/slamcore/infrared_0_hw/camera_info
/slamcore/infrared_0_hw/image_raw
/slamcore/infrared_1_hw/camera_info
/slamcore/infrared_1_hw/image_raw
/slamcore/map_hw
/slamcore/odom_hw
/slamcore/pose_hw

Note

ROS1 Visualisation is not compatible with hardware timestamps.