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 conjunction 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.
As with other trackables, AreaTarget has a specific id, name, and type. Its size is in meters 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.
Status in AreaTargetResult
Different from other targets, the AreaTarget’s pose status is reported 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, 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:
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, to gain more knowledge about the overall fidelity of the tracking experience at run-time.
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. Consider that a very large space of maximum 1000m2 can consist of multiple smaller AreaTargets which have the benefit of freeing 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.
NOTE: The DeviceTracker must be initialized and enabled before starting the AreaTracker.
NOTE: For both Native and Unity, ARKit or ARCore supported devices or a HoloLens headwear is required when deploying to a device.
NOTE: In order to cover a larger space with multiple Area Targets, you need to 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 parts on app level.
Multiple Target Types
Since AreaTarget is tracked and managed by the AreaTracker, it is necessary to involve the ObjectTracker for tracking other types of trackables in parallel to the AreaTarget. The use of multiple types is worth considering as it can be a source for aiding relocalization if the AreaTarget tracking becomes LIMITED. See the section below on Location Prior for more information. Another useful consideration is to combine Model Targets with Area Targets in situations where you want users to inspect objects up close.
Location Prior from an External Source
The 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 the Area Target feature in large and/or repetitive environments.
Especially on the first-time localization attempts (‘warm-up’ of the AR experience), such an input can visibly 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 by calling:
bool setExternalPosition(Vec2F position, float radius);
NOTE: A location prior is also required to be set for a first localization when you use Area Targets that return true for
The function of the location prior achieves
- faster (first-time) localization by restricting valid localization positions to the specified part of the AreaTarget. (vertical (y) component of the position is not restricted).
- 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.
NOTE: The provided location prior is valid until a successful localization or the Area Target is deactivated and unloaded. 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 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.