Migrating from Earlier API Versions

This page aims to briefly highlight changes in the API since previous versions that users should be aware of when migrating. For more detail please refer to example code distributed with the SDK or annotated in the C++ API examples section.

Slamcore SDK v23.04

Coordinate Frames of Reference Convention Change

A new coordinate frame convention has been adopted in the Slamcore SDK v23.04 to comply with ROS standards REP-103 and REP-105.

Note

This affects any of the following:

• Existing static transformations used to integrate Slamcore into a mobile platform

• Trajectories generated with versions prior to v23.04 which use a different coordinate frame convention

This will not affect the following, therefore no changes will be required to:

• VIK configuration files provided to you for Wheel Odometry Integration.

In previous releases, our software reported the pose of the Sensor frame (with the positive X axis pointing to the right, the positive Y axis pointing down and the positive Z axis pointing forward) relative to the World frame. The World frame was initialised based on the gravity direction, with the Z axis pointing up, opposite to the gravity direction, the X axis pointing to the right and the Y axis pointing forward.

Fig. 21 Frames of reference during a forward motion of the camera in v23.01

With the previous convention, if you started the RealSense parallel to the ground and started moving it forwards, you would see the Y coordinate increasing. If you moved the camera up, you would see the Z coordinate increasing.

From 23.04 onward, our SLAM will report the pose of the Body frame. The Body frame is at the same location as the Sensor frame (which remains unchanged), but with a different axes convention, with the positive X axis pointing forward, the positive Y axis pointing left and the positive Z axis pointing up. The World frame will still be initialised based on the gravity direction, with the Z axis pointing up, opposite to the gravity direction. The World X axis, however, will be initialised to match the direction of the Body X axis. The World Y axis will be initialised pointing to the left of this World X axis.

Fig. 22 Frames of reference during a forward motion of the camera in v23.04

With this new convention, if you started the RealSense parallel to the ground and started moving it forwards, you would see the X coordinate increasing. If you moved the camera up, you would see the Z coordinate increasing.

For more information on the updated coordinate frame convention please refer to the Coordinate Frames Convention page.

This change may impact existing integrations of the Slamcore system into your transform tree and you should review any existing transforms you may have defined between the Slamcore pose tracking frame and your other systems. Note, however, that VIK calibration files still use the T_SO transformation between the wheel odometry frame and the Slamcore Sensor frame, which uses the same axes convention as in previous releases. Therefore, no changes are required to VIK calibrations files.

Additionally, this change will impact trajectory generation, as can be seen below when plotting the same trajectory generated with v23.01 (blue trajectory) of our software vs v23.04 (green trajectory).

Fig. 23 Comparison of generated trajectories between v23.01 and v23.04

Slamcore SDK v23.01

Session file format

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.

JSON configuration file migration

The configuration file format for running SLAM on customized parameters has changed in this software version. This means that your old configuration files may fail to be parsed, or be parsed incorrectly when used with Slamcore SDK v23.01 and above. This affects any of the following:

• configuration files you have created based on the Configuration Overview page,

• configuration files provided by Slamcore for your test/deployment environment, and

• any VIK configuration files provided to you for Wheel Odometry Integration.

To update your existing JSON configuration files, please install the “Slamcore Tools” package from the Slamcore Portal, run the slamcore_migrate_config tool and save the text output in a new .json file, for example:

$ slamcore_migrate_config vik_odometry_config.json >> new_vik_odometry_config.json

Tracking Information

We have redefined our tracking status information to better differentiate between the instantaneous status of the pose estimation and the events triggered only at certain frames to update SLAM.

The Relocalised and Loop Closure states are no longer reported under the “Tracking Status” information, and instead under a new “SLAM Event” metadata alongside a new IMU Initialization event. For more information please refer to Tracking Information.

Slamcore SDK v21.06.85

Layout

The API has been reorganised to provide more granular header files for development. Please be aware that some interfaces are no longer included by slamcore/slamcore.hpp and therefore must be included in the implementation file explicitly.

Subsystems and I/O

Accessing trajectories

Previously the slamcore::TrajectorySubsystemInterface subsystem offered access to both the unoptimised and optimised trajectories where available.

This functionality has been split into two classes as follows:

• The slamcore::OptimisedTrajectorySubsystemInterface subsystem continues to offer access to the optimised trajectory from the SLAM instance.

• The unoptimised trajectory must be accumulated by the client. To do so correctly the SDK provides the slamcore::TrajectoryHelper class.

Please see the write_trajectory.cpp example distributed with the SDK for detailed usage.

Wheel odometry integration

Integration of wheel odometry has been comprehensively re-implemented via a new slamcore::SensorSourceInterface. The slamcore::MobileRobotSubsystemInterface class has been removed.

Please see the wheel_odometry.cpp example distributed with the SDK for details regarding how to integrate wheel odometry.

Types and Objects

LogMessageInterface timestamps

slamcore::LogMessageInterface::getTimestamp() method has been modified to return a slamcore::host_timestamp.

Code that previously read:

void sample(const slamcore::LogMessageInterface& message)
{
  const time_t time = std::chrono::system_clock::to_time_t(message.getTimestamp());
}

Should be updated to:

void sample(const slamcore::LogMessageInterface& message)
{
  const time_t time = slamcore::host_clock::to_time_t(message.getTimestamp());
}

Renamed slamcore::CameraSensorsInfoInterface

The slamcore::CameraSensorsInfoInterface class has been replaced with slamcore::SensorsInfoInterface.

Re-implemented slamcore::MultiFrameInterface

The slamcore::MultiFrameInterface previously used slamcore::ImageInterface as its value_type. It has been modified to use the more general slamcore::FrameInterface.

To access a slamcore::MultiFrameInterface’s image for a given sensor, code that previously read:

void sample(const slamcore::MultiFrameInterface& multiFrame, const uint8_t sensorIndex)
{
  const slamcore::ImageInterface& image = multiFrame->get(sensorIndex);
}

Should be updated to:

void sample(const slamcore::MultiFrameInterface& multiFrame, const uint8_t sensorIndex)
{
  const slamcore::ImageInterface& image = multiFrame->get(sensorIndex).image();
}

Concrete Matrix class

Previously matrix and vector types were represented by the slamcore::Matrix and slamcore::Vector which adapted the std::vector to the slamcore::MatrixInterface and slamcore::VectorInterface respectively.

The implementation of slamcore::Matrix has been changed to a concrete template class which requires

• the element type; and,

• dimensions or slamcore::Dynamic

as template parameters. The corresponding interfaces have been removed, therefore all APIs now return the concrete type.

Any use of slamcore::Vector or slamcore::Matrix should be amended to include the required template parameters.

Pointers or references to returned interfaces should be changed to auto or the precise concrete type.

Removed slamcore::ObjectInterface

slamcore objects previously implemented the common slamcore::ObjectInterface to provide the object’s type(). This interface has been removed.

All calls to type() should be removed.