This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
Area Targets are tracked by the AreaTracker. It is dedicated to track AreaTarget trackables and provide methods for managing the AreaTarget DataSet. AreaTarget is a trackable that represents a scanned space and can be used in combination with other target types. This article presents the structure of Area Targets in C++.
High-Level Overview of the API
- The AreaTarget is a trackable that represents a scanned space.
- AreaTracker tracks AreaTargets. The data for this trackable is stored in DataSet, which is owned and managed by the AreaTracker.
- AreaTargetResult carries information on the pose and status of the AreaTarget.
For examples and general App initialization using Area Targets, please see Area Targets Native Workflow.
NOTE: For both Native and Unity, ARKit or ARCore supported devices or a HoloLens headwear is required when deploying to a device.
AreaTarget
As with other trackables, AreaTarget has a specific id, name, and type. Its size is in meters and getSize() and getBoundingBox() methods provide information on the size and the bounding-box of the AreaTarget, respectively. setSize() is not supported for this trackable because it represents a real-world space and therefore it makes no sense to scale it.
In contrast to other targets which allocate memory when the dataset is loaded, AreaTarget datasets require some substantial additional loading and memory allocation which is done asynchronously in the background after activation of the target. This may result in a delay of up to a few seconds between activation and the first detection of a target.
Consider that a very large space also can consist of multiple smaller AreaTargets to free up memory as only one AreaTarget needs to be active at a certain position in the area. Then, a logic can be developed for switching between the targets.
- Segment the regions already during scanning and create independent scans covering adjacent parts of the environment. The scans need to be converted individually to Area Targets. For a continuous experience and pose you will need to maintain an offset between the segments on app level. See Multiple Area Targets in Unity that describes how smaller Area Targets can be configured to a common pose.
Status in AreaTargetResult
Different from other targets, the AreaTarget’s pose status is reported to AreaTargetResult as EXTENDED_TRACKED in normal operation or 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 AreaTracker 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 him/her out from the LIMITED status. The same holds true for the situation when a newly activated AreaTarget 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 him/her within the space. See below for more information.
The Status Info of AreaTarget is reported as NORMAL when EXTENDED_TRACKED and RELOCALIZING when in the LIMITED STATE:
STATUS |
STATUS_INFO |
|
|---|---|---|
| EXTENDED_TRACKED | NORMAL |
Normal target tracking conditions. |
| LIMITED | RELOCALIZING | The alignment of the target with the environment may not be perfect. |
For more information on the Trackable Pose statuses, please see Tracking States.
NOTE: During operation, we also recommend observing the STATUS and STATUS_INFO of the DeviceTracker which must be initialized and started to get information from AreaTargetResult. It provides more knowledge about the overall fidelity of the tracking experience at run-time.
AreaTracker
AreaTracker only supports AreaTarget trackables and it differs from the ObjectTracker because it can be used for indoor navigation and spatial awareness.
AreaTracker supports multiple active AreaTargets during runtime. You can load up to 255 AreaTargets in one session and activate them after each other. Activation of an AreaTarget can fail if one large Area Target (see location prior below) or too many Area Targets are already activated. In that case, deactivate some of the active Area Targets before activating the new one.
Location Prior for Large Area Targets
A location prior is a direct aid to the AreaTracker 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 above approximately 1000 m2 or 10.000 sq ft return true for AreaTarget::requiresExternalPositions() and will need a location prior to before it can localize in the environment.
The function of the location prior achieves:
- Faster (first-time) localization by restricting valid localization positions to the specified part of the AreaTarget.
- Reduction of erroneous target tracking in cases where the current tracked position of the respective AreaTarget 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. Vertical (y) component of the position is not restricted.
bool setExternalPosition(Vec2F 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 AreaTracker to re-establish tracking and relocalize. If no relocalization happens after 10 seconds, motivate first the user to move or turn around. If in addition AreaTarget::requiresExternalPositions() returns 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 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 ImageTarget 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 AreaTargets with known relative spatial layout are used, one can use the tracked pose of one target to aid localization in the neighboring target.
Multiple Target Types
It is necessary to involve the ObjectTracker for tracking other types of trackables in parallel to the AreaTarget that is tracked by the AreaTracker. The use of multiple types is worth considering as it can be a source for aiding relocalization if the AreaTarget tracking becomes LIMITED. Another useful consideration is to combine Model Targets with Area Targets in situations where you want users to inspect objects up close.