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, a Magic Leap or a HoloLens  headwear, is required when using Area Targets.

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. The requireExternalPositions's default is VU_FALSE. When set to VU_TRUE, the Area Target will wait to load target data until an external position is injected during the Observer lifecycle.

When an Area Target is set requireExternalPositions = VU_TRUE and activated, all other activated Area Targets will also require requireExternalPositions set to VU_TRUE and an external position injected

HINT: You can create Area Target Observers with other requireExternalPositions settings but activating them will require they are consistent with other activated Area Targets.

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

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

TIP: An Area Target Observer can be used as a source for the Mesh Observer to provide runtime occlusion meshes. See Create Mesh Observer from Area Target for more information.

Area Target size

Area Target databases require additional loading and memory allocation which is done asynchronously in the background after activation of the Area Target Observer. It’s necessary that the dataset remains available for the duration of its usage as loading of data might continue after activation. Loading Area Targets may result in a delay of up to a few seconds between activation and the first detection of the target.

A large Area Target can always be activated and loaded as the first one, but an activated large Area Target may prevent the activation of other Area Targets due to its size. A large Area Target will return VU_TRUE for vuAreaTargetObserverRequiresExternalPositions(), and will consequently, require a location prior to first localize the user in the environment. For details, see the Location Prior for Area Targets section below or the API reference page.

Multiple Area Targets

If you wish to use multiple Area Targets, we recommend implementing a switching logic in the app to deactivate and activate Area Targets most relevant to the user’s position. Vuforia Engine does support multiple active Area Target Observers during runtime. You can create up to 255 Area Targets Observers in one session, but we recommend in these use cases to disable auto-activation by setting areaTargetConfig.activate to VU_FALSE to reduce the number of active Area Targets; too many active Area Targets can, just like a large Area Target, prevent other Area Targets from being loaded and instead fail with the error code VU_AREA_TARGET_CREATION_ERROR_AUTO_ACTIVATION_FAILED.

When an Area Target fails to activate it’s likely because it would cause the total size of active Area Target datasets to exceed the maximum supported size. You then have two options:

  • Deactivate some active Area Target Observers to gain space for activating the new one.
  • Or activate all your Area Target Observers concurrently by configuring them to require external positions for initial detection. See the location prior for more information.

Manage activated and deactivated Area Targets:

vuObserverActivate(areaTargetObserver);
vuObserverDeactivate(areaTargetObserver);

A logic should be developed for switching between the active Area Targets, for example, by using the location priors. 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 Pose Status 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 information about the overall fidelity of the tracking experience at runtime.

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, Area Targets of repetitive environments, and switching between multiple Area Targets.

  • Location priors can manage the loading of data from a set of activated Area Targets with requireExternalPositions set to VU_TRUE. Vuforia Engine then pick and load the most appropriate Area Targets based on proximity and overlap.
  • The location prior enables faster (first-time) localization and will only begin loading necessary Area Target data asynchronously when the external position is set during the lifecycle.
  • An external position can reduce 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.

Large Area Targets are identified as approximately 4000 m2 or 40.000 sq ft and bigger and require VU_TRUE for requiresExternalPositions. Check at runtime whether an Area Target requires an external position and inject a value as coordinates in 2D or 3D values.

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

TIP: Set an external prior for each Area Target to let Vuforia Engine pick the most appropriate and closest Area Targets among active Area Targets.

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. See Geolocation as External Prior for Area Targets on how to use GPS coordinates. 

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 value for horizontalAccuracy(agreeing with the accuracy of the prior) to an active AreaTarget Observer.

vuAreaTargetObserverSetExternalPositionFrom2D(VuObserver* observer, VuVector2F position, float horizontalAccuracy);

Vertical (y) component of the position can be set when Area Targets are at different heights, such as the floors in a multistory building. Like the horizontalAccuracy, the verticalAccuracy is an uncertainty value in meters but in the y-direction.

vuAreaTargetObserverSetExternalPositionFrom3D(VuObserver* observer, VuVector3F position, float horizontalAccuracy, float verticalAccuracy);

NOTE: The provided location prior is valid until a successful localization or the Area Target is deactivated. Repeatedly setting the external position replaces the previous one, which is helpful when using continuous external sources, such as a GPS reading.

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.

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 approx. 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 your external sensor data or ask the user to indicate their approximate location.

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

Can this page be better?
Share your feedback via our issue tracker