C API Motion Tracking Tutorial

This page describes how the C API handles motion tracking. For more
information, see the C API reference on the
pose functions.

Lifecycle

The normal motion tracking system lifecycle consists of three states:
TANGO_POSE_INITIALIZING, TANGO_POSE_VALID, and TANGO_POSE_INVALID. In the
TANGO_POSE_INITIALIZING state, the system is not yet ready and pose data is
not available. In the TANGO_POSE_VALID state, the system is functioning
normally. In the TANGO_POSE_INVALID state, the system believes its estimate
was invalid and needs to be reinitialized. A fourth state,
TANGO_POSE_UNKNOWN, is used for all other cases.

Should the pose data become TANGO_POSE_INVALID, the motion tracking system
can be reinitialized in two ways. If config_enable_auto_recovery was set to
true, the system will immediately enter the TANGO_POSE_INITIALIZING state. It
will use the last valid pose as the starting point after recovery. If
config_enable_auto_recovery was set to false, the system will essentially
pause and always return poses as TANGO_POSE_INVALID until
TangoService_resetMotionTracking() is called. Unlike auto recovery, this will
also reset the starting point after recovery back to the origin.

The lifecycle state is recorded in the pose status_code.

Configuration

In order to use motion tracking, your TangoConfig must have
config_enable_motion_tracking set to true. If you are using the default
TangoConfig as your starting point, it is already set to true.

You also have the option to set config_enable_auto_recovery. In the default
TangoConfig, this is set to true. See the Lifecycle section for the behavior
of this parameter.

Getting pose data

There are two coordinate frame pair options for basic motion tracking: device
with respect to start of service, and device with respect to the previous
device pose. With start of service, the device's pose is relative to the
position where the motion tracking system initialized. You can receive pose
data in both the callback and polling forms. With previous device pose, the
device's pose is relative to its last position. Pose data is only available as
a callback.

Callback-based

If you are using the callback-based approach, you must define the coordinate
frame pairs you are interested in and construct your onPoseAvailable()
callback. The example below shows a more complicated case where you are
listening to two different coordinate frame pairs.

// Attach onPoseAvailable callback.
// The callback will be called after the service is connected.
if (TangoService_connectOnPoseAvailable(2, pairs, onPoseAvailable)
!= TANGO_SUCCESS) {
// Handle the error.
}

Polling-based

In the polling-based approach, you must first specify the coordinate frame pair
you are interested in. For simple motion tracking, this will always be
TANGO_COORDINATE_FRAME_DEVICE with respect to
TANGO_COORDINATE_FRAME_START_OF_SERVICE.

Then call `TangoService_getPoseAtTime() as desired. In the example below, the
timestamp is set to 0.0 to get the latest pose. If you specify a specific
timestamp, the system will return an interpolated pose at that exact time.
Timestamps are relative to the device boot.