Area Target API Overview

Area Targets are tracked by the VuAreaTargetObserver. It is dedicated to track whole environments.

Area Targets are created from digital representations of entire spaces. An Area Target can be associated with an Area Target Observer and is suitable for use cases such as indoor navigation and spatial awareness.

NOTE: For both Native and Unity, ARKit or ARCore supported devices or a HoloLens headwear is required when using Area Targets.

General Setup

Please see the Vuforia Engine Lifecycle for a general introduction to the Vuforia Engine lifecycle. The Engine is required for creating and using Observers.

Create an Area Target Observer

The Area Target Observer is created from an Area Target database. An Area Target Observer is configured with a databasePath and targetName that must match a database and its target. In addition, a Device Pose Observer is required for the Area Target Observer to report observations to the state. See Device Tracking for steps to create one. By default, the Area Target Observer is activated upon creation unless otherwise specified with activate.

// Create an Observer config
VuAreaTargetConfig areaTargetConfig = vuAreaTargetConfigDefault();
areaTargetConfig.devicePoseObserver = devicePoseObserver;
areaTargetConfig.databasePath = "area_target_database.xml";
areaTargetConfig.targetName = "AreaTarget";
areaTargetConfig.activate = VU_TRUE;

// Create an Area Target Observer
VuObserver* areaTargetObserver = { NULL };
vuEngineCreateAreaTargetObserver(engine, &areaTargetObserver, areaTargetConfig, NULL);

Target size

Area Target databases require some substantial additional loading and memory allocation which is done asynchronously in the background after activation of the observer. This may result in a delay of up to a few seconds between activation and the first detection of the target. Very large Area Targets requires additionally a location prior to first localize. For details, see the Location Prior for large Area Targets section below.

Multiple Area Targets

Vuforia Engine supports multiple active Area Target Observers during runtime. You can create up to 255 Area Targets Observers in one session but recommend in such use cases to disable auto-activation by setting areaTargetConfig.activate to VU_FALSE to reduce the number of simultaneously active Area Targets. Activation of an Area Target Observer will fail with error code VU_AREA_TARGET_CREATION_ERROR_AUTO_ACTIVATION_FAILED if too many Area Targets Observers are already active.

Manage activated and deactivated Area Targets:

vuObserverActivate(areaTargetObserver);
vuObserverDeactivate(areaTargetObserver);

A logic can be developed for switching between the Area Targets. For a continuous experience and common pose observations you will need to maintain an offset between the Area Targets on app level. See Multiple Area Targets in Unity for a guide to configuring smaller Area Targets to a common pose.

Observation

The Area Target Observer produces Observations that are  collected in the State. Get the State from the Engine and parse them to the VuAreaTargetObservationTargetInfo. See the Observer and Observations article for more information on target info and status info from Observers.

Creation of Observation list

// Create observation list
VuObservationList* obsList = { NULL };
vuObservationListCreate(&obsList);

// Get and parse area target observations list
vuStateGetAreaTargetObservations(state,obsList);

int32_t listSize = 0;
vuObservationListGetSize(obsList, &listSize);

Then, parse the observation list to get info on the target(s).

// Parse the Area Target list
for (int i = 0; i < listSize; i++)
{
    VuObservation* obs = { NULL };
    vuObservationListGetElement(obsList, i, &obs);

    VuPoseInfo poseInfo;
    vuObservationGetPoseInfo(obs, &poseInfo);

    VuAreaTargetObservationTargetInfo targetInfo;
    vuAreaTargetObservationGetTargetInfo(obs, &targetInfo);

    if (poseInfo.poseStatus != VU_OBSERVATION_POSE_STATUS_LIMITED)
    {
        // Do something with poseInfo and targetInfo
    }
}

Destroy Observer and Observation

Destroy objects and processes after usage to free up memory.

For Area Targets, you call the following to destroy the Area Target ObservationList and the Area Target Observer:

Destroy ObservationList

// Destroy observation list
vuObservationListDestroy(obsList);

Destroy the Observer

// Destroy the observer
vuObserverDestroy(areaTargetObserver);

Area Target Info and Status Info

The Area Target Observation pose status is reported as VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED in normal operation or VU_OBSERVATION_POSE_STATUS_LIMITED if there is a risk that the target is slightly misaligned with the environment. In that case, we suggest you render only content which does not rely on exact alignment, e.g., navigation arrows and floating banners. When the Area Target Observer relocalizes, the target and alignment improve and pose status will become _EXTENDED_TRACKED again.

TIP: You may consider asking the user to step a bit away from the scene or to look around to facilitate the search for a view that gets them out from the _LIMITED status. The same holds true for the situation when a newly activated AreaTarget Observation does not report any pose status. If the user still finds themselves unable to localize within the space, a location prior can be used to aid in localizing them within the space. See below for more information. 

The Status Info of Area Target Observations is reported as VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NORMAL when _EXTENDED_TRACKED and as  VU_AREA_TARGET_OBSERVATION_STATUS_INFO_RELOCALIZING when in the _LIMITED state.

For more information on the Area Target statuses, please see Status Poses and Status Info.

NOTE: During operation, we also recommend observing the Device Pose Observer’s target info and status info. It provides more knowledge about the overall fidelity of the tracking experience at run-time.

Location Prior for Large Area Targets

A location prior is a direct aid to the Area Target Observer in localizing Area Targets correctly with respect to the environment and it can improve the localization speed when using large Area Targets or Area Targets in repetitive environments.

Large Area Targets are identified as approximately 1000 m2 or 10.000 sq ft or bigger and will return VU_TRUE for requiresExternalPositions.

vuAreaTargetObserverRequiresExternalPositions(const VuObserver* observer, VuBool* requiresExternalPositions);

You will therefore need to set a location prior before your Area Target Observer can localize in the environment.

  1. Faster (first-time) localization by restricting valid localization positions to the specified part of the Area Target.
  2. Reduction of erroneous target tracking in cases where the current tracked position of the respective Area Target does not lie within the specified part of the target.

Location prior from external sources

Especially on the first-time localization attempts (‘warm-up’ of the AR experience), such an input can noticeably improve the localization speed in difficult spaces. If an external localization source (i.e. GPS position) is available, it can be provided to the system (e.g. by creating a background task periodically updating the location prior) so that it does not need to rely solely on visual cues when estimating a user’s position in the environment. 

Just remember to convert the GPS values to a position in the Area Target’s coordinate system. The transformed (x, z) position is then provided together with an uncertainty radius (agreeing with the accuracy of the prior) to an active AreaTarget Observer. Vertical (y) component of the position is not restricted.

 vuAreaTargetObserverSetExternalPosition(VuObserver* observer, VuVector2F position, float radius);
NOTE: The provided location prior is valid until a successful localization or the Area Target is deactivated. Repeatedly setting the prior replaces the previous one, which is helpful when using continuous external sources, such as a GPS reading.

Returning from a paused AR session

Returning from a paused or interrupted AR session require the Area Target Observer to relocalize. If no relocalization happens after appx. 10 seconds, motivate first the user to move or turn around. If in addition vuAreaTargetObserverRequiresExternalPositions() gives VU_TRUE , then you should inject a prior from external sensor data or ask the user to indicate their approximate location.

Other sources

Other sources of a location prior can be a UX map presented to the user to indicate a starting point or current position from a room-list; add a known storyline if the users always initiate the experience at the same location within the space; or place identification using e.g. an Image Target and Image Target Observer at a known location – a picture that the user is asked to point their device at, when entering a gallery tour. In cases when multiple Area Target Observers with known relative spatial layouts are used, one can use the tracked pose of one target to aid localization in the neighboring target.

Multiple Target Types

Track other types of targets in parallel to the Area Target Observer. The use of different targets and other elements in an environment is worth considering as it can be a source for aiding relocalization if the VuAreaTargetObservationTargetInfo returns _LIMITED. For example, combine Model Targets with Area Targets in situations where you want users to inspect objects up close.

Target Information for Area Targets

In this section, we present additional common target information options for Area Target Observers. Setting the scale of an Area Target Observer is not supported as it represents a real-world 3D space.

Size

Get the sizes, height, length, and width in meters of the Area Target associated to an Area Target Observer. Scaling the Area Target is not supported.

vuAreaTargetObserverGetTargetSize(const VuObserver* observer, VuVector3F* size);

Bounding Box

Use this function to get an axis-aligned bounding box of the area from the Area Target Observer, and relative to the target’s frame of reference.

vuAreaTargetObserverGetAABB(const VuObserver* observer, VuAABB* bbox);