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

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, Object, 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, Object Target, and VuMark are identical and their statuses are returned with VuObservationPoseStatusvuObservationStatusInfo 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:

STATUS Description STATUS_INFO Recommendations for the Developer

Unity NO_POSE

Native VU_OBSERVATION_POSE_STATUS_NO_POSE

No valid pose available. The target is either not yet detected or tracking of it was lost.

Unity NOT_OBSERVED

Native VU_<TARGET>_OBSERVATION_STATUS_INFO_NOT_OBSERVED

Provide the user with visual aids to identify the objects that can be tracked.

Unity TRACKED

Native VU_OBSERVATION_POSE_STATUS_TRACKED

The target is being tracked - indicates normal operation.

Unity NORMAL

Native VU_<TARGET>_OBSERVATION_STATUS_INFO_NORMAL

Tracking working normally and augmentations can be rendered. 

Unity EXTENDED_TRACKED

Native VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED

The target is tracked indirectly. It is either out-of-view, occluded, too-far or too-close to be tracked directly but its pose is maintained by the Device Pose Observer Refer to Device Tracking for more details.

Unity NORMAL

Native VU_<TARGET>_OBSERVATION_STATUS_INFO_NORMAL

Tracking working normally.

Unity LIMITED

Native VU_OBSERVATION_POSE_STATUS_LIMITED

The target 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.

Unity RELOCALIZING

Native VU_<TARGET>_OBSERVATION_STATUS_INFO_RELOCALIZING

Motivate the user to return to the target if needed.

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:

STATUS

Description

STATUS_INFO

Recommendations for the Developer

Unity NO_POSE

Native VU_OBSERVATION_POSE_STATUS_NO_POSE

Vuforia is trying to detect the target but a pose is not available yet.  Please see Model Target API Overview for more details on initiating tracking for Model Targets.

Unity NOT_OBSERVED

Native VU_MODEL_TARGET_OBSERVATION_STATUS_NOT_OBSERVED

No actions required when this status info is reported.

Unity INITIALIZING

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_INITIALIZING

The target is an Advanced Model Target that has not been recognized yet. We recommend showing a Viewfinder UI for multiple targets or a Symbolic Guide View for a single target.

Unity RECOMMENDING_GUIDANCE

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_RECOMMENDING_GUIDANCE

The target does not have an Advanced Guide View. We recommend showing a Guide View Overlay to assist the user in moving to a position where tracking can start.

Unity TRACKED

Native VU_OBSERVATION_POSE_STATUS_TRACKED

The target is being tracked and indicates normal operation.

Unity NORMAL

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_NORMAL

Circumstances are good and augmentations can be rendered.

Unity WRONG_SCALE

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_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.

The 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

Unity EXTENDED_TRACKED 

Native VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED 

The target is tracked indirectly. It is either out-of-view, occluded, too-far or too-close to be tracked directly but its pose is maintained by the Device Pose Observer. Refer to Device Tracking for more details.

Unity NORMAL

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_NORMAL

Motivate the user to return to the target if needed.

Unity WRONG_SCALE

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_WRONG_SCALE

See _TRACKED/_WORNG_SCALE. It is recommended to correct the scale.

Unity LIMITED

Native VU_OBSERVATION_POSE_STATUS_LIMITED

The target 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.

Unity RELOCALIZING

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_RELOCALIZING

Motivate user to return to the target if needed.

Unity WRONG_SCALE

Native VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_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 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:

STATUS Description STATUS_INFO Recommendations to the Developer

Unity EXTENDED_TRACKED

Native VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED 

The target is being indirectly tracked utilizing the Device Pose Observer and is set to operating normally.

Unity NOT_OBSERVED

Native VU_AREA_TARGET_OBSERVATION_STATUS_NOT_OBSERVED

Recommend the user to return to a starting position to re-enable or start tracking the environment.

Unity NORMAL

Native VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NORMAL

Normal target tracking conditions. Augmentations can be rendered with precise alignment.

Unity LIMITED

Native VU_OBSERVATION_POSE_STATUS_LIMITED

The target 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.

Unity RELOCALIZING

Native VU_AREA_TARGET_OBSERVATION_STATUS_INFO_RELOCALIZING

A limited pose of a target 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.

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

STATUS

STATUS_INFO

Recommendations for the Developer

Unity NO_POSE

Native VU_OBSERVATION_POSE_STATUS_NO_POSE

No device pose available.

Unity NOT_OBSERVED

Native VU_DEVICE_POSE_OBSERVATION_STATUS_NOT_OBSERVED

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

Reset the Device Pose Observer 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).

 

Unity UNKNOWN

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_UNKNOWN

Unity INITIALIZING

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_INITIALIZING

The device tracking is initializing.

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

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

Unity RELOCALIZING

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_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 device pose 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 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 status, when using VU_FUSION_PROVIDER_TYPE_VISION_ONLY and detecting a previously undetected target, the device pose status switches to _LIMITED/_INITIALIZING after a short delay. This indicates that no relocalization occurred but internally the device pose was re-started. Previous mid-air anchors are lost. Other anchors and targets might be re-detected

Unity LIMITED

Native VU_OBSERVATION_POSE_STATUS_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.

Unity UNKNOWN

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_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.

Unity INITIALIZING

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_INITIALIZING

The device tracking is initializing.

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

 

Unity RELOCALIZING

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_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 device pose or instruct the user to restart the entire AR experience.

Some Anchors/targets 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.

Unity EXCESSIVE_MOTION

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_EXCESSIVE_MOTION

Only reported on ARKit

The device is being moved too fast.

Instruct the user to move slower or hold the device still

Unity INSUFFICIENT_FEATURES

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_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. 

Unity INSUFFICIENT_LIGHT

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_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.

Unity TRACKED

Native VU_OBSERVATION_POSE_STATUS_TRACKED

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

Unity NORMAL

Native VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_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 was discovered by the underlying platform or when pointing in a direction with no surface to hit).

 

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
            }
        }
    }
}