You’re reading an older version of the Slamcore SDK documenation. The latest one is 23.04.
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 viarqt
(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:

Fig. 17 RVIZ - User Interface

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
Description: Slamcore system diagnostic information.
- /slamcore/accel
Type: sensor_msgs/Imu
Description: Accelerometer data, interpolated to align with the gyroscope measurements.
- /slamcore/gyro
Type: sensor_msgs/Imu
Description: Gyroscope data.
- /slamcore/{infrared, visual, depth}{, _0, _1, …}/camera_info
Type: sensor_msgs/CameraInfo
Description: Corresponding camera intrinsic parameters.
- /slamcore/{infrared, visual}{_0, _1, …}/image_raw
Type: sensor_msgs/Image
Description: Raw image data.
- /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
Type: sensor_msgs/PointCloud2
Description: Unstructured point cloud generated from the depth image.
- /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
Description: Sensor pose. This will only be published if the tracking status is OK [1].
- /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
Type: sensor_msgs/PointCloud
Description: Computed sparse map.
- /slamcore/map
Type: nav_msgs/OccupancyGrid
Description: Computed occupancy grid map.
- /tf
Type: tf2_msgs/TFMessage
Description: Transform tree.
- /tf_static
Type: tf2_msgs/TFMessage
Description: Static transform tree.
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 listconfig_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
anddataset_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
Type: String
Default:
map
Description: Map frame_id published as described in https://www.ros.org/reps/rep-0105.html.
- /slamcore/odom_frame
Type: String
Default:
odom
Description: Odom frame_id published as described in https://www.ros.org/reps/rep-0105.html.
- /slamcore/base_frame
Type: String
Default:
base_link
Description: Base frame_id published as described in https://www.ros.org/reps/rep-0105.html.
- /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:

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.