Area Target API Overview

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.

 

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.

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.

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, to gain 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. 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);

Other sources of a location prior can be a map presented to the user to indicate a starting position; a known storyline if the users always start the experience at the same location within the space; or an 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.

Use the function of the location prior to achieve:

  1. 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).
  2.  interruptions 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 target deactivation. Repeated setting of the prior replaces the previous one, which is helpful when using continuous external sources, such as a GPS reading.
 

Learn More

Area Targets Overview

Area Targets Native Workflow

Using Area Targets in Unity

Area Targets Test App User Guide