You’re reading an older version of the Slamcore SDK documenation. The latest one is 23.01.

Overview

Introduction

This page provides an overview of the SLAMcore C++ API. All the calls and types mentioned here are under the namespace slamcore.

Initialisation

Before using the API the library has to be initialised with the slamcore::slamcoreInit() call. The user might optionally pass a callback that will receive the logs from the library (at least at a desired log level).

Once done with using the library please call slamcore::slamcoreDeinit() to free all the resources that might still be acquired.

Example:

slamcore::slamcoreInit(slamcore::LogSeverity::Info,
                       [](const slamcore::LogMessageInterface& message)
{
  const time_t time = std::chrono::system_clock::to_time_t(message.getTimestamp());
  struct tm tm;
  localtime_r(&time, &tm);

  std::cerr << "[" << message.getSeverity() << " " << std::put_time(&tm, "%FT%T%z") << "] "
            << message.getMessage() << "\n";
});

// ... use the SDK

slamcoreDeinit();

Main SLAM interface

Every interaction with the SLAM systems happens through the slamcore::SLAMSystemCallbackInterface, which provides the following methods:

../_images/slam_if.png

Creation

To create the slamcore::SLAMSystemCallbackInterface call the slamcore::createSLAMSystem() factory function. It takes the slamcore::v0::SystemConfiguration struct as an argument. With this struct the system configuration can be fine-tuned:

  • if the system is running live (real camera) or from a pre-recorded dataset,

  • provide a path to a JSON preset file with optional low level config overrides,

  • set the positioning mode,

  • provide the path to the session file to pre-load,

  • disable SLAM altogether, in that scenario the system just passes the camera data (images, IMU samples) to the user, useful for debugging.

Note

Only one instance of a slamcore::SLAMSystemCallbackInterface is allowed. To create another instance the previous instance needs to be deleted. See Example reset.cpp example for more information on running SLAM systems one-by-one.

Example:

slamcore::v0::SystemConfiguration sysCfg;
std::unique_ptr<slamcore::SLAMSystemCallbackInterface> slam = slamcore::createSLAMSystem(sysCfg);
if (!slam)
{
  std::cerr << "Error creating SLAM system!" << std::endl;
  slamcore::slamcoreDeinit();
  return -1;
}

Objects, Streams and Properties

Data returned by the SLAM system is in the form of objects of various types, all inheriting from the slamcore::ObjectInterface. These interfaces often are related, e.g. slamcore::PoseInterface - representation of a 3D pose - returns slamcore::VectorInterface in the getters for the translation and rotation parts.

Many objects additionally inherit from slamcore::MeasurementPointInterface which provides basic metadata for that particular measurement sample (ID, timestamps, sensor type etc).

../_images/objects.png

Receiving a particular object type can be controlled by enabling and disabling a particular stream of data. Below are listed, for example, which data types are coming on which stream:

Additionally, the SLAM system interface provides a number of properties that can be queried and set via the getProperty and setProperty calls. These are often variables with basic data types and related to the current running configuration, not the SLAM/per-frame data itself. For a list of properties see here: slamcore::Property.

Basic operations

The main SLAM API (i.e. slamcore::SLAMSystemCallbackInterface) intends to mimic a typical video camera driver that the user might be familiar with. SLAMcore’s system ultimately estimates and provides much more than just the raw sensor data that a normal video camera does, but the paradigm still fits.

To start interacting with the SLAM system the user has to open it, with either slamcore::SLAMCoreInterface::open() or slamcore::SLAMCoreInterface::openWithSession() calls. Once the system is open the properties can be queried, streams of interest can be enabled and callbacks registered to handle data coming on those streams.

To start processing, call the slamcore::SLAMCoreInterface::start() method. From that moment the SLAM system starts processing sensor readings, estimating the camera pose, the map and calling the user provided callbacks with the most recent data.

To keep receiving data call the slamcore::SLAMSystemCallbackInterface::spinOnce() method which is responsible for receiving and dispatching the incoming data to the callbacks.

The slamcore::SLAMCoreInterface::stop() method can be called when an slamcore::ErrorCodeInterface object signalling the end of a dataset is received or to stop (live camera). The slamcore::SLAMCoreInterface::close() method can be called to shutdown the SLAM system if processing will not be resumed.

Example:

 1// Initialise the library
 2slamcoreInit()
 3
 4// Create a system configuration
 5slamcore::v0::SystemConfiguration cfg;
 6
 7// create a SLAM System
 8std::unique_ptr<slamcore::SLAMSystemCallbackInterface> slam = slamcore::createSLAMSystem(cfg);
 9
10// register any callbacks
11slam->registerCallback<slamcore::Stream::Pose>(
12[](const slamcore::PoseInterface<slamcore::camera_clock>::CPtr& pose)
13{
14  // do something with the pose!
15});
16// ...
17
18slam->open();
19
20// enable the streams you need
21slam->setStreamEnabled(slamcore::Stream::Pose, true);
22// ...
23
24slam->start();
25
26// poll for data
27while(slam->spinOnce(std::chrono::seconds(1)));
28
29// cleanup SLAM
30slam->stop();
31slam->close();
32
33// clean up the library
34slamcoreDeinit();

See Example hello_world_all_streams.cpp example for more information.

Saving & loading sessions

The SLAMcore system can save the state of a session into a portable file and then use that file later to preload the map. The saving process is more than just saving a file, map clean-up and optimisation is carried out to produce higher quality localisation and faster map loading. Session saving is launched by launching an appropriate async task, e.g.:

const std::string ses_path = "/tmp/test.session"; // where to save the session

const slamcore::IDT tid = slam->launchAsyncTask(slamcore::TaskType::SaveSession,
                                                {{"filename", ses_path}});

The code above launches the slamcore::TaskType::SaveSession task, with appropriate parameters (path to the output file) and returns the TaskID of that task. With that ID the task can be cancelled or its status can be queried with the slamcore::SLAMAsyncTasksInterface::getTaskStatus() method.

Warning

Please make sure SLAM is stopped before launching the save session task. Make sure to check the task status before launching a new task.

Loading the session file can be done either by providing the filename in the slamcore::v0::SystemConfiguration struct that is passed to createSLAMSystem or SLAM system can be open with slamcore::SLAMCoreInterface::openWithSession() method instead of slamcore::SLAMCoreInterface::open().

See Example save_load_session.cpp or Example multisession.cpp examples for more information.

Subsystems

To keep the main SLAM system interface stable and simple, extension points are provided for advanced users. This mechanism is called subsystems and they are separate interfaces that can be obtained by calling the getSubsystem method.

CameraInfo

This subsystem allows querying of the camera sensors in the system, their type and the factory calibration for each sensor.

Example:

auto cam_info = slam->getSubsystem<CameraSensorsInfoInterface>();

const std::vector<SensorIDT> sensors = cam_info->getCameraList();

for(const auto& sensor : sensors)
{
  const Vector dims = cam_info->getCameraSensorSize(sensor);

  std::cout << "Sensor " << sensor << ", width: " << dims.x()
                                   << ", height: " << dims.y() << std::endl;
}

General remarks

When using the SLAMcore C++ API with Intel RealSense camera avoid forking the process, as RealSense does not support it.

The SLAMcore C++ API is not thread-safe.