Vuforia Engine provides pose status information on activated Observers at runtime for those that report pose information. This information can help you monitor and adapt to an Observer’s changing tracking status. For example, when the pose status changes, you can offer users directions and guidance using the pose status and status info.
The availability of specific pose status and status info values depend on the Observer type. Furthermore, pose status information is unavailable for Observers that do not report pose information, such as IlluminationObserver
and BarcodeObserver
.
An Observer’s pose info is reported via Observations: If the pose information is available, information about the availability and reliability of the pose is reported as pose status and status info. The pose status describes the tracking state of the Observer’s 6 degrees of freedom pose during its lifetime. A pose status has an associated pose status info that provides further information on the Observer’s pose status.
The pose status is available through the Observation handle VuObservation
. Information on the pose is available with vuObservationGetPoseInfo()
. All Observers have their pose status returned via VuPoseInfo
that contains the status of the pose as VuObservationPoseStatus
. The supporting pose status info to a given pose status is available via functions specific to the respective Observer type, e.g., vuImageTargetObservationGetStatusInfo()
or vuModelTargetObservationGetStatusInfo()
. You can query if an Observer provides pose information by calling vuObservationHasPoseInfo()
.
The pose status will be reported as VU_OBSERVATION_POSE_STATUS_NO_POSE until the observed object is detected for the first time.
VuMark, Image, Multi, and Cylinder Targets Pose Status and Status Info
The available pose status and status info for Observers of type, Image Target, Cylinder Target, Multi Target, and VuMark are identical.
NOTE: In the below table the <TARGET> placeholder is used for better readability denoting any of IMAGE_TARGET, VUMARK, MULTI_TARGET, and CYLINDER_TARGET.
Pose Status |
Status Info |
VU_OBSERVATION_POSE_STATUS_NO_POSE |
|
No valid pose available. The target is either not yet detected or tracking of it was lost. |
VU_<TARGET>_OBSERVATION_STATUS_INFO_NOT_OBSERVED |
Provide the user with visual aid to identify the objects that can be tracked. |
|
VU_OBSERVATION_POSE_STATUS_TRACKED |
|
The target is being tracked - indicates normal operation. |
VU_<TARGET>_OBSERVATION_STATUS_INFO_NORMAL |
Tracking working normally and augmentations can be rendered. |
|
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. |
VU_<TARGET>_OBSERVATION_STATUS_INFO_NORMAL |
Tracking working normally. |
|
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. |
VU_<TARGET>_OBSERVATION_STATUS_INFO_RELOCALIZING |
Motivate the user to return to the target if needed. |
Model Targets Pose Status and Status Info
A Model Target Observer’s pose status includes a unique status info that is reported when a Model Target is detected to be wrongly scaled.
Pose Status |
Status Info |
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. |
VU_MODEL_TARGET_OBSERVATION_STATUS_NOT_OBSERVED |
No actions required when this status info is reported. |
|
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. |
|
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. |
|
VU_OBSERVATION_POSE_STATUS_TRACKED |
|
The target is being tracked and indicates normal operation. |
VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_NORMAL |
Circumstances are good and augmentations can be rendered. |
|
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-world 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 Magic Leap. It is recommended to correct the scale. |
|
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. |
VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_NORMAL |
Motivate the user to return to the target if needed. |
|
VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_WRONG_SCALE |
|
See TRACKED + WRONG_SCALE. It is recommended to correct the scale. |
|
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. |
VU_MODEL_TARGET_OBSERVATION_STATUS_INFO_RELOCALIZING |
Motivate user to return to the target if needed. |
|
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 a factor of 50x compared to the real-world 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 Pose Status and Status Info
Area Targets and Anchors do not report the pose status VU_OBSERVATION_POSE_STATUS_TRACKED but instead will report VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED when tracking is working normally. VuAreaTargetObservationStatusInfo
and VuAnchorObsevationStatusInfo
are always reported as VU_AREA_TARGET_STATUS_INFO_NORMAL for extended tracked poses and VU_AREA_TARGET_STATUS_INFO_RELOCALIZING for limited poses.
The following table lists the available pose status values for Area Targets and Anchors:
Pose Status |
Status Info |
VU_OBSERVATION_POSE_STATUS_NO_POSE |
|
Vuforia is trying to detect the target or anchor point but a pose is not available yet. Please see Area Target API Overview for more details on initiating tracking for Area Targets. |
VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NOT_OBSERVED VU_ANCHOR_OBSERVATION_STATUS_INFO_NOT_OBSERVED |
Recommend the user to return to a starting position to re-enable or start tracking the environment. |
|
VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED |
|
The target or anchor point is being indirectly tracked utilizing the Device Pose Observer and is set to operate normally. |
VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NORMAL VU_ANCHOR_OBSERVATION_STATUS_INFO_NORMAL |
Normal target or anchor point tracking conditions. Augmentations can be rendered with precise alignment. |
|
VU_OBSERVATION_POSE_STATUS_LIMITED |
|
The target or anchor point 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. |
VU_AREA_TARGET_OBSERVATION_STATUS_INFO_RELOCALIZING VU_ANCHOR_OBSERVATION_STATUS_INFO_RELOCALIZING |
A limited pose of a target or anchor point 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. |
See also the Area Target API Overview for additional information on Area Targets and Ground Plane API Overview for Anchors.
Device Tracking Pose Status and Status Info
The Device Pose Observer represents the pose of the device with respect to the surrounding environment. The pose status info is retrieved with vuDevicePoseObservationGetStatusInfo
.
Device tracking uses Vuforia Fusion to utilize the core technologies available for each individual platform. Vuforia Engine abstracts away the information from the underlying platform and consolidates it with the pose status and status info.
The table summarizes the available values for the VuDevicePoseObservationStatusInfo
.
Status |
Status Info |
|
VU_OBSERVATION_POSE_STATUS_NO_POSE |
|
|
No device pose available. |
VU_DEVICE_POSE_OBSERVATION_STATUS_NOT_OBSERVED |
VU_DEVICE_POSE_OBSERVATION_STATUS_INFO_UNKNOWN |
Vuforia cannot determine a device pose or provide information on the reason. |
||
Reset the Device Pose Observer with vuEngineResetWorldTracking() 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). |
||
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. |
||
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. This status info is not reported on ARKit. In this status info, 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. |
||
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. |
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. |
||
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. |
||
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. |
||
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. |
||
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. |
||
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. |
||
VU_OBSERVATION_POSE_STATUS_TRACKED |
|
|
A reliable device pose is provided, and experiences are anchored with respect to the environment. |
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 Pose Status and Status Info
The following code examples show different ways to retrieve the pose information. These examples do not include error checking or memory cleanup. For guidance on those topics, please refer to Vuforia Engine Lifecycle in Native.
This code example checks for all Observations currently reported to the State and checks if any of the Observations have pose info:
12345678910111213141516171819202122232425262728293031323334353637383940414243444546CopyVuState *vuforiaState = NULL;
vuEngineAcquireLatestState(engine, &vuforiaState);
VuObservationList *observationList = NULL;
vuObservationListCreate(&observationList);
vuStateGetObservations(vuforiaState, observationList);
int32_t numObservations = 0;
vuObservationListGetSize(observationList, &numObservations);
for (int32_t idx = 0; idx < numObservations; ++idx)
{
VuObservation *observation = NULL;
vuObservationListGetElement(observationList, idx, &observation);
if (vuObservationHasPoseInfo(observation) == VU_TRUE)
{
VuPoseInfo poseInfo;
vuObservationGetPoseInfo(observation, &poseInfo);
VuObservationType type;
vuObservationGetType(observation, &type);
switch (type)
{
case VU_OBSERVATION_DEVICE_POSE_TYPE:
{
VuDevicePoseObservationStatusInfo poseStatusInfo;
vuDevicePoseObservationGetStatusInfo(observation, &poseStatusInfo);
switch (poseInfo.poseStatus)
{
// Handle possible device pose specific status and status info values here.
}
}
case VU_OBSERVATION_IMAGE_TARGET_TYPE:
{
VuImageTargetObservationStatusInfo poseStatusInfo;
vuImageTargetObservationGetStatusInfo(observation, &poseStatusInfo);
switch (poseInfo.poseStatus)
{
// Handle possible image target specific status and status info values here.
}
}
// Handle other observation types here
}
}
}
You can also get a list with Observations that have pose info using vuStateGetObservationsWithPoseInfo()
. This code example only returns Observations that have pose info.
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950CopyVuState *vuforiaState = NULL;
vuEngineAcquireLatestState(engine, &vuforiaState);
VuObservationList *observationList = NULL;
vuObservationListCreate(&observationList);
vuStateGetObservationsWithPoseInfo(vuforiaState, observationList);
int32_t numObservations = 0;
vuObservationListGetSize(observationList, &numObservations);
for (int32_t idx = 0; idx < numObservations; ++idx)
{
VuObservation *observation = NULL;
vuObservationListGetElement(observationList, idx, &observation);
assert(vuObservationHasPoseInfo(observation) == VU_TRUE);
VuPoseInfo poseInfo;
vuObservationGetPoseInfo(observation, &poseInfo);
VuObservationType type;
vuObservationGetType(observation, &type);
switch (type)
{
case VU_OBSERVATION_DEVICE_POSE_TYPE:
{
VuDevicePoseObservationStatusInfo poseStatusInfo;
vuDevicePoseObservationGetStatusInfo(observation, &poseStatusInfo);
switch (poseInfo.poseStatus)
{
// Handle possible device pose specific status and status info values here.
}
}
case VU_OBSERVATION_IMAGE_TARGET_TYPE:
{
VuImageTargetObservationStatusInfo poseStatusInfo;
vuImageTargetObservationGetStatusInfo(observation, &poseStatusInfo);
switch (poseInfo.poseStatus)
{
// Handle possible image target specific status and status info values here.
}
}
// Handle other observation types here
}
}
Get Observations by Observer type. The following example retrieves pose status information for Image Target Observers. Equivalent functions also exist for other types of observers.
12345678910111213141516171819202122232425262728293031CopyVuState *vuforiaState = NULL;
vuEngineAcquireLatestState(engine, &vuforiaState);
VuObservationList *observationList = NULL;
vuObservationListCreate(&observationList);
vuStateGetImageTargetObservations(vuforiaState, observationList);
int32_t numObservations = 0;
vuObservationListGetSize(observationList, &numObservations);
for (int32_t idx = 0; idx < numObservations; ++idx)
{
VuObservation *observation = NULL;
vuObservationListGetElement(observationList, idx, &observation);
// Image target observations are expected to have pose info
assert(vuObservationHasPoseInfo(observation) == VU_TRUE);
VuPoseInfo poseInfo;
vuObservationGetPoseInfo(observation, &poseInfo);
VuImageTargetObservationStatusInfo poseStatusInfo;
vuImageTargetObservationGetStatusInfo(observation, &poseStatusInfo);
switch (poseInfo.poseStatus)
{
// Handle possible image target specific status and status info values here.
}
}