Pose Status and Status Info

Vuforia Engine provides information on the tracking status for each Observer’s target in a scene. This information helps to maintain an AR experience if changes in the scene occur and provides users with directions (e.g., point the device back at a target or move slower when tracking is lost).

The status type and availability depend on the Observer type. For example, pose and status information are not available for IlluminationObserver and BarcodeObserver.

In general, Observations collect a target’s info; its pose (if available), and its status and status info. The status describes each state of the target during the tracking lifecycle. In some tracking failure cases, the Vuforia Engine API provides information on the likely cause of the failure.

The status is accessible via the VuObservation in the native API. Target pose info is accessed with VuObservationGetPoseInfo. The supporting status info information is available via Observation calls specified to a target type: vuImageTargetObservationStatusInfo() and vuImageTargetObservationTargetInfo(). For some generic info types, you can query if a particular info is available, e.g. for pose info you can call vuObservationHasPoseInfo().

The pose status will be reported as NO_POSE until the first target is detected.

VuMark, Image, Multi, and Cylinder Targets Status Poses and Status Info

The available status poses provided on Observers of type: Image Target, Cylinder Target, Multi Target, and VuMark are identical and their statuses are returned with VuObservationPoseStatus. vuObservationStatusInfo for the observer types can be NORMAL or RELOCALIZING for tracked targets and NOT_OBSERVED for targets not being tracked. The following table lists the available tracking status values:

Model Targets Status Poses and Status Info

The vuModelTargetObservation inherits the same pose status information from VuObservationPoseStatus, but additionally uses VuModelTargetObservationStatusInfo to report about wrongly scaled Model Targets:

Please refer to the Model Target API Overview article for additional details for implementing the status in the app logic.

Area Targets and Anchors Status Poses and Status Info

The following table lists the available pose status values for Area Targets and Anchors:

NOTE: vuAreaTargetObservationStatusInfo and vuAnchorObsevationStatusInfo are always reported as STATUS_INFO_NORMAL for extended tracked poses and STATUS_INFO_RELOCALIZING for limited poses.

You can choose which statuses should be active in the Unity Editor by selecting a target’s DefaultObserverEventHandler component. See Using the Device Tracking in Unity for more information. See also the Area Target API Overview for additional information on Area Targets and Ground Plane API Overview for Anchors.

Device Tracking Status Poses and Status Info

The Device Pose Observer represents a special case among targets 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. Get the device pose status with VuDevicePoseObservationStatusInfo which is always reported by VuState as soon as the Device Pose Observer is created and activated.

Device tracking uses Vuforia Fusion to utilize the core technologies available for each individual platform. The status and status information affected by the individual platforms is abstracted and consolidated by Vuforia Engine. See the table below for details.

Device pose status and status info

The following table summarizes the available values for the VuDevicePoseObservationStatusInfo. The values are relevant when the VuDevicePoseObserver is used to track the device’s 6-degrees-of-freedom poses in the environment (e.g., when used in combination with Ground Plane or Area Targets).

Handling of Status and Status Info in Unity

Most ObserverBehaviours in Unity, including Image Targets, Model Targets, Area Targets and Anchors, come with the DefaultObserverEventHandler that handles Status updates out of the box.

By default, this event handler will show and hide augmentations parented to the target game object based on the current Status. A dropdown in the inspector lets you configure which Status values should be considered for showing the augmentation.

For more complex use cases, you can directly subscribe to the OnTargetStatusUpdated event of an ObserverBehaviour. This event is available for all ObserverBehaviours, including the DevicePoseObserver and will be invoked whenever the Status or StatusInfo changes.

The following example shows a setup for subscribing and processing this event:

using UnityEngine;
using Vuforia;

public class StatusEventHandler : MonoBehaviour
{
    private ObserverBehaviour mObserverBehaviour;
    void Awake()
    {
        ObserverBehaviour mObserverBehaviour = GetComponent<ObserverBehaviour>();

        if (mObserverBehaviour != null)
            mObserverBehaviour.OnTargetStatusUpdated += OnStatusChanged;
    }
    void OnStatusChanged(TargetStatus status)
    {
        Debug.LogFormat("Status is: {0}, statusInfo is: {1}", status.Status, status.StatusInfo);
    }
    void OnDestroy()
    {
        if (mObserverBehaviour != null)
            mObserverBehaviour.OnTargetStatusUpdated -= OnStatusChanged;
    }
}

Handling of Status Poses and Status Info in Native

To handle the status information in a native application, use the vuStateGetDevicePoseObservations() and check the pose info with vuObservationGetPoseInfo().

    VuObservationList* observationList = nullptr;
vuObservationListCreate(&observationList);

if (vuStateGetDevicePoseObservations(mVuforiaState, observationList) == VU_SUCCESS)
{
    int numObservations = 0;
    vuObservationListGetSize(observationList, &numObservations);

    if (numObservations > 0)
    {
        VuObservation* observation = nullptr;
        if (vuObservationListGetElement(observationList, 0, &observation) == VU_SUCCESS)
        {
            assert(observation);
            assert(vuObservationIsType(observation, VU_OBSERVATION_DEVICE_POSE_TYPE) == VU_TRUE);
            assert(vuObservationHasPoseInfo(observation) == VU_TRUE);

            VuPoseInfo poseInfo;
            vuObservationGetPoseInfo(observation, &poseInfo);
            if (poseInfo.poseStatus != VU_OBSERVATION_POSE_STATUS_NO_POSE)
            {
                // Render augmentations
            }
        }
    }
}

Learn More

Observer and Observations

Continued AR Experiences

Device Tracking