Interpreting Tracking State API Results

Introduction

Vuforia provides status information for every trackable while a result is available for it. This information can be used to analyze the behavior of trackables at run-time. Depending on the provided data the application can react better and direct the user to e.g. point the device back to the target or just move slower.

The status itself describes a state in the life-cycle of tracking from initialization throughout normal operation and in case of difficult tracking conditions. In conditions other than normal operation additional information is provided by the SDK on the most likely reason.

The status is accessible via the TrackableResult::getStatus() API, while the supporting information is available via TrackableResult::getStatusInfo(). Vuforia may add new type of status information from one release to the other, make sure to check the API documentation.

Status in ObjectTargetResult

Status information provided of image-, object-, and VuMark-trackables is identical across the different target types. It describes the state of tracking. Following values are possible:

 

Enumarator Description
NO_POSE No pose was delivered for the trackable. The trackable was not yet detected or tracking was lost.
DETECTED The trackable was detected, this is a transient state, not observable in most cases.
TRACKED The trackable is being tracked, normal operation.
EXTENDED_TRACKED  The trackable is not directly tracked with the specific tracker. It is either out-of-view, too-far or too-close to be tracked directly. Refer to the detail documentation on the behavior of  Extended Tracking.

Status and Information in DeviceTrackableResult

The Device Tracker represents a special case amongst all trackables since it does not track the pose of an object in front of the camera, but rather the pose of the device itself with respect to the surrounding environment. Due to its different behavior the provided status values and additional information is different from other trackers. Starting with Vuforia 7 the Device Tracker leverages Vuforia Fusion to provide the best core technologies available of the individual platforms. As part of this effort the status and additional information provided by the individual platforms is absorbed and consolidated by the Vuforia SDK in future.

The below table summarizes the possible values provided by the DeviceTrackableResult() class. The provided values are relevant when the PositionalDeviceTracker() is being used to track the 6-degree-of-freedom pose of the device in the environment, eg. when used in combination with GroundPlane.

 

STATUS STATUS_INFO
on ARKit devices on all other devices*
NO_POSE No device pose available. UNKNOWN Vuforia cannot determine a device pose and is also not capable of providing information why. UNKNOWN Vuforia cannot determine a device pose and is also not capable of providing information why.
LIMITED The device pose is of degraded quality. The application may inform the user to help recover a better device tracking. INITIALIZING The device tracker is initializing. A degraded 3 degree of freedom pose might be available as fall back. UNKNOWN Vuforia may provide a degraded quality device pose but is currently not able to provide further information how to recover.
EXCESSIVE_MOTION The device is being moved too fast. Advise the user to move slower or hold device still.
INSUFFICIENT_FEATURES The device is pointed to an area with very few visual features. While sensor readings support device tracking, the visual odometry system also relies on visual features in the environment. Advise user to point to an area with more visual features.
TRACKED A reliable device pose is provided, experiences are anchored with respect to the environment. NORMAL Normal device tracking condition. NORMAL Normal device tracking condition.

* NOTE:

  • In Vuforia 7 the additional status information is only provided when the SDK is running on the ARKit platform.
  • When using the RotationalDeviceTracker() the same STATUS and STATUS_INFO is provided as with 'all other devices'.

Coding Examples for Using Tracking Status for DeviceTracker Use-Cases

Below a number of examples are provided to properly handle the above listed different tracking status and detail information.

Handling of STATUS and STATUS_INFORMATION when Using the PositionalDeviceTracker

The PositionalDeviceTracker provides 6 degree of freedom pose of the device with respect to the surrounding environment. The below example shows a framework to process provided status information. In situations when LIMITED tracking is available, we recommend guiding the user with alerts, additional information, graphics to slow-down motion, search for an area with more visual clutter or to just hold on - tracking will be recovered soon.

// Check if device tracker (6DOF) is running.
if (state.getDeviceTrackableResult() != NULL)
{
    // Check if we got an result.
    if (state.getStatus() != TrackableResult::NO_POSE)
    {
        // Get the device pose.
        const DeviceTrackableResult* result = state.getDeviceTrackableResult();
        const Matrix34F& pose = result->getPose();
 
        // Check if we got a 6DOF or 3DOF (limited) pose.
        if (result->getStatus() != TrackableResult::LIMITED)
        {
            // Do something with 6DOF pose.
        }
        else
        {
            // Check the reason for limited pose.
            // Can mean a fallback to 3DOF or a 6DOF pose of questionable quality.
             
            switch (result->getStatusInfo())
            {
                case TrackableResult::INITIALIZING:
                    // Do something, e.g. inform user.
                    break;
                case TrackableResult::EXCESSIVE_DEVICE_MOTION:
                    // Do something, e.g. inform user.
                    break;
                case TrackableResult::INSUFFICIENT_VISUAL_FEATURES:
                    // Do something, e.g. inform user.
                    break;
                default:
                    break;
            }
            // Do something with limited pose.
            ...
        }
         
        ...
    }
    else
    {
        // Check the reason for invalid pose.
        // This will only give us information about the 6DOF failure not a potential additional failure for the fallback to 3DOF (for example a limited 3DOF pose).
        switch (result->getStatusInfo())
        {
            case TrackableResult::INITIALIZING:
                // Do something, e.g. inform user.
                break;
            case TrackableResult::EXCESSIVE_DEVICE_MOTION:
                // Do something, e.g. inform user.
                break;
            case TrackableResult::INSUFFICIENT_VISUAL_FEATURES:
                // Do something, e.g. inform user.
                break;
            default:
                break;
        }
 
        ...
    }
}
else
{
    // Do something, like e.g. start the device tracker.
    ...
}

 

Handling of STATUS and STATUS_INFORMATION when using the RotationalDeviceTracker

The RotationalDeviceTracker provides 3 degree of freedom pose, which is the device orientation only. The below example shows a framework to process provided status information.

// Check if device tracker (3DOF) is running.
if (state.getDeviceTrackableResult() != NULL)
{
    // Check if we got an result.
    if (state.getStatus() != TrackableResult::NO_POSE)
    {
        // Get the device pose.
        const DeviceTrackableResult* result = state.getDeviceTrackableResult();
        const Matrix34F& pose = result->getPose();
 
        // 3DOF pose currently cannot be limited.
         
        // Do something with pose.     
        ...
    }
    else
    {
        // Check the relevant reasons for an invalid pose in the 3DOF case.
        switch (result->getStatusInfo())
        {
            case TrackableResult::INITIALIZING:
                // Do something, e.g. inform user.
                break;
            case TrackableResult::EXCESSIVE_DEVICE_MOTION:
                // Do something, e.g. inform user.
                break;
            default:
                break;
        }
 
        ...
    }
}
else
{
    // Do something, like e.g. start the device tracker.
    ...
}