Interpreting Tracking State API Results

This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.

Vuforia Engine provides status information for every trackable while a result is available, thereby helping to analyze the behavior of trackables at run-time. The data allows the application to better react and provide users with directions (e.g., point the device back at the target or move slower).

The status describes each state in the tracking lifecycle. In conditions that exceed normal operations, the SDK provides information on the likely cause.

The status is accessible via the TrackableResult::getStatus() API.  The supporting information is available via TrackableResult::getStatusInfo(). New types of status information may be added at each release, so regularly check the API documentation.

Status in ObjectTargetResult

The status information provided on ImageTarget, ObjectTarget, and VuMarkResults are identical. The following table lists the available tracking state values:

NOTE: STATUS_INFO is always reported as NORMAL for ObjectTargetResult.

See the ObjectTracker API Overview for additional information.

Status in ModelTargetResult

The ModelTargetResult also inherits the status information from ObjectTargetResult, but additionally uses the STATUS_INFO to warn about wrongly scaled Model Targets:

Please refer to the Model Target API Overview article for details and the Model Targets Native Workflow article for implementing the states in the app logic. 

Status in AreaTargetResult and AnchorResult

The following table lists the available tracking state values for Area Targets and Anchors:

NOTE: STATUS_INFO is always reported as NORMAL for EXTENDED_TRACKED poses and RELOCALIZING for LIMITED poses.

A LIMITED pose of a trackable is known to have substantially larger inaccuracies than a normal EXTENDED_TRACKED pose. Once the inferred pose of the target or anchor is estimated more accurately, it will again start to report EXTENDED_TRACKED poses. You can choose which states should be active in the Unity Editor by selecting a target’s TrackableEventHandler component. See Using the Device Tracker in Unity for more information on Vuforia powered tracking features. See also the Area Target API Overview for additional information.

Status in DeviceTrackableResult

The Device Tracker represents a special case among trackables since it does not track the pose of an object in front of the camera, but rather the pose of the device with respect to the surrounding environment. The status and status information values differ in interpretation from other trackable results. The DeviceTrackableResult is always reported by Vuforia::State() as soon as the DeviceTracker is initialized.

Since Vuforia Engine 7, the Device Tracker uses Vuforia Fusion to provide the optimal core technologies available for each individual platform. The status and status information provided by the individual platforms is abstracted and consolidated by Vuforia Engine.

Positional Device Tracker

The following table summarizes the possible values available for the DeviceTrackableResult. The values are relevant when the PositionalDeviceTracker is used to track the device’s 6-degrees-of-freedom pose in the environment (e.g., when used in combination with GroundPlane).

Example: Handling of STATUS and STATUS_INFO

The following example shows a basic framework for processing the provided status information from the RegisterDevicePoseStatusChangedCallback in Unity. 

public class DeviceTrackerEventHandler
    {
        void Awake()
        {
            DeviceTrackerARController.Instance.RegisterDevicePoseStatusChangedCallback(OnStatusChanged);
        }
        
        void OnStatusChanged(TrackableBehaviour.Status status, TrackableBehaviour.StatusInfo statusInfo)
        {
            Debug.LogFormat("Status is: {0}, statusInfo is: {1}", status, statusInfo);
        }

        void OnDestroy()
        {
            DeviceTrackerARController.Instance.UnregisterDevicePoseStatusChangedCallback(OnStatusChanged);

        }
    }

To handle the status information in a native application, use the DeviceTrackableResult from the State and check the statuses of the poses with GetStatus().