Interpreting Tracking State API Results

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:

STATUS Description
DETECTED The trackable was detected. This is a transient state and not observable in most cases.
TRACKED The trackable is being tracked and indicates 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 documentation on the behavior of  Extended Tracking.
LIMITED The trackable is being tracked but only with very low accuracy. If your application requires exact target alignment, it is recommended to discard LIMITED poses of targets. If accurate alignment is less of a concern, then using LIMITED poses may provide a more continuous tracking experience.

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:

STATUS

STATUS_INFO

DETECTED

The trackable was detected. This is a transient state and not observable in most cases.

NORMAL

TRACKED

The trackable is being tracked and indicates normal operation.

NORMAL

 

WRONG_SCALE

Vuforia detects a significant discrepancy between the target and the physical object.

The target’s size is either too small  or too large up to a factor of 50x compared to the real word size of the tracked object.

Target will still track, but reported poses will not be in metrical coordinates. The target will appear at the wrong depth on HoloLens or MagicLeap.

It is recommended to correct the scale.

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 documentation on the behavior of  Extended Tracking.

NORMAL

LIMITED

The trackable is being tracked but only with very low accuracy. If your application requires exact target alignment, it is recommended to discard LIMITED poses of targets. If accurate alignment is less of a concern, then using LIMITED poses may provide a more continuous tracking experience.

NORMAL

 

WRONG_SCALE

Vuforia detects a huge discrepancy between the target and the physical object.

The target’s size is either too small  or too large by more than factor of 50x compared to the real word size of the tracked object.

Tracking will not work reliably.

Make sure to review and correct the scale of the Model Target.

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:

STATUS Description
EXTENDED_TRACKED  The trackable is being indirectly tracked utilizing the Positional Device Tracker and is set to operating normally.
LIMITED The trackable is being tracked but only with very low accuracy. If your application requires exact target alignment, it is recommended to discard LIMITED poses of targets. If accurate alignment is less of a concern, then using LIMITED poses may provide a more continuous tracking experience.

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).

STATUS

STATUS_INFO

Recommendations for the Developer

NO_POSE

No device pose available.

UNKNOWN

Vuforia cannot determine a device pose or provide information on the reason.

Reset the PDT or instruct the user to restart the entire AR experience when the situation is continuously reported for a certain length of time (e.g., 10 seconds).

INITIALIZING

The device tracker is initializing.

Instruct the user to wait and move the device slightly around.

Vuforia reports this state 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 is trying to re-attach to the world and restore Anchor locations.

Instruct the user to go back to a previously seen area. Reset the PDT or instruct the user to restart the entire AR experience when the situation is continuously reported for a certain length of time (e.g., 10 seconds).

Some Anchors/Trackables might not be reported after a relocalization. We recommend cleaning these up sometime after relocalization occurs.
NOTE: The length of time depends on the expected user behavior and your use case.

This STATUS_INFO is not reported on ARKit.

In this state, when using FUSION_PROVIDER_VUFORIA_VISION_ONLY and detecting a previously undetected Trackable, the PDT status switches to LIMITED-INITIALIZING after a short delay. This indicates that no relocalization occurred 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 advise the user to help recover a better device tracking.

Anchor creation is not recommended. There are no guarantees about the accuracy or consistency of new anchors and creation may fail if there is not sufficient scene geometry.

UNKNOWN

Vuforia is not capable of providing information on the cause of the limited pose.

Advise the user to hold the device still and check that lighting conditions are suitable and that the tracked area has sufficient visual features.

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

INITIALIZING

The device tracker is initializing.

Instruct the user to move the device around to achieve better quality tracking.

 

RELOCALIZING

Only reported on ARKit

The device is trying to re-attach to the world and restore Anchor locations.

Instruct the user to return to a previously seen area. If the situation is reported for a certain length of time (e.g., 10 seconds), reset the PDT or instruct the user to restart the entire AR experience.

Some Anchors/Trackables might not be reported after a relocalization. We recommend cleaning these up sometime after relocalization occurs.

NOTE: The length of time depends on the expected user behavior and your use case.

EXCESSIVE_MOTION

Only reported on ARKit

The device is being moved too fast.

Instruct the user to move slower or hold the device still.

INSUFFICIENT_FEATURES

Only reported on ARKit

The device is pointed at 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.

Instruct the user to point to an area with more visual features or check for proper lighting and contrast. 

INSUFFICIENT_LIGHT

Only reported on ARCore

Motion tracking is lost due to poor lighting conditions.

Instruct the user to move to a more brightly lit area.

TRACKED

A reliable device pose is provided, and experiences are anchored with respect to the environment.

NORMAL

Normal device tracking conditions.

Time to render your full augmented experience!

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

 

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().