Interpreting Tracking State API Results

Introduction

Vuforia Engine 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 Engine 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
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.

Note: STATUS_INFO is always reported as NORMAL for ObjectTargetResult.

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. The provided status values and additional information differs in interpretation from other trackable results. The DeviceTrackableResult is always reported on the Vuforia::State() as soon as the DeviceTracker is initialized.

Beginning Vuforia Engine 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 abstracted and consolidated by Vuforia Engine.

Positional Device Tracker

The below table summarizes the possible values available on the DeviceTrackableResult. 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

Developer Recommendations

NO_POSE

No device pose available.

UNKNOWN

Vuforia cannot determine a device pose and is also not capable of providing information why.

You should reset the PDT or offer user UX to restart entire AR experience if this situation is reported for eg. ~10s.
INITIALIZING The device tracker is initializing.

You should engage user with UX to wait and move device slightly around.

Vuforia reports this states using any provider to allow a consistent app behavior. On ARKit this is reported when no Pose is delivered just after starting a ARSession.

RELOCALIZING

The device tries to re-attach to the world, restoring Anchor locations.

You should recommend the user via UX to go back to previously seen area. You should reset the PDT or offer user UX to restart entire AR experience if this situation is reported for eg. ~10s.

Some Anchors/Trackables might not be reported anymore after a relocalization. We recommend to clean these up after some period after re-localization happened. (Note: the actual period length depends on your expected user behavior and use case).

This STATUS_INFO is not reported on ARKit.

When using FUSION_PROVIDER_VUFORIA_SENSOR_FUSION or FUSION_PROVIDER_VUFORIA_VISION_ONLY and detecting a previously not detected Trackable in this state the PDT status will switch to LIMITED-INITIALIZING after short delay only. This indicates that actually no relocalization happened but internally the PDT was re-started. Previous mid-air anchors are lost. Other Anchors and Targets might be re-detected.

LIMITED

The device pose is of degraded quality. The application may inform the user to help recover a better device tracking.

Note: Limited STATUS is not reported on ARCore platform.

UNKNOWN Vuforia is not capable of providing information why pose is limited.  
INITIALIZING The device tracker is initializing.

A degraded 3 degree of freedom pose might be available as fall back.

 

EXCESSIVE_MOTION The device is being moved too fast. Advise the user to move slower or hold device still. (Only reported on ARKit.)
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 or check on lighting situation and contrast. (Only reported on ARKit.)
TRACKED A reliable device pose is provided, experiences are anchored with respect to the environment. NORMAL Normal device tracking condition.

Time to render your full augmented experience!

Note: Hit test may still fail in certain cases, eg. if insufficient scene geometry has been discovered by the underlying platform, or when pointing into direction with no surface to hit.

 

Rotational Device Tracker

When using the RotationalDeviceTracker() the following STATUS and STATUS_INFO is provided:

STATUS STATUS_INFO
NO_POSE No device pose available. UNKNOWN Vuforia Engine cannot determine a device pose and is also not capable of providing information why.
TRACKED A reliable device pose is provided, experiences are anchored with respect to the environment. NORMAL Normal device tracking conditon.

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 a 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 pose.
               if (result->getStatus() != TrackableResult::LIMITED)
               {
                       // Do something with 6DOF pose.
               }
               else
               {
                       // Check the reason for limited pose.                      
                       switch (result->getStatusInfo())
                       {
                               case TrackableResult::UNKNOWN:
                                      // Do something, e.g. inform user.
                                      break;
                               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.
               switch (result->getStatusInfo())
               {
                       case TrackableResult::UNKNOWN:
                               // Do something, e.g. inform user.
                               break;
                       case TrackableResult::INITIALIZING:
                               // Do something, e.g. inform user.
                               break;
                       case TrackableResult::RELOCALIZING:
                               // 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 a result.
        if (state.getStatus() != TrackableResult::NO_POSE)
        {
               // Get the device pose.
               const DeviceTrackableResult* result = state.getDeviceTrackableResult();
               const Matrix34F& pose = result->getPose();
               
               // Do something with pose.            
               ...
        }
        else
        {
               ...
        }
}
else
{
        // Do something, like e.g. start the device tracker.
        ...
}