AR Tracked Image component

Understand the AR Tracked Image component and how to interpret lifecycle events.

The ARTrackedImage component is a type of trackable that contains the data associated with a detected 2D image. The ARTrackedImageManager creates an ARTrackedImage when the device detects a 2D image from the Reference image library in the environment.

Component reference

AR Tracked Image component.

Property	Description
Destroy On Removal	If true, this component's GameObject is destroyed when this trackable is removed.

Tracked image lifecycle

As trackables, AR tracked images have a lifecycle that consists of three phases: added, updated, and removed. Your app can Respond to detected images during your AR session by subscribing to the AR Tracked Image Manager component's trackablesChanged event.

Added

When a 2D image is first detected in the environment, the AR Tracked Image Manager creates a new GameObject with an AR Tracked Image component attached. The tracked image manager then invokes its trackablesChanged event. This event passes you a reference to the new Tracked Image component via the added property.

Updated

The ARTrackedImageManager.trackablesChanged method is invoked in each frame where a tracked image is updated. This method contains a list of all changed images in the frame.

Tracking state

If your app responds to image lifecycle events, you should check each image's trackingState value whenever the image is updated.

There are three possible tracking states for an ARTrackedImage:

TrackingState	Description
None	The image is not being tracked. Note that this may be the initial state when the image is first detected.
Limited	The image is being tracked, but not as effectively. The situations in which an image is considered Limited instead of Tracking depend on the underlying AR framework. Examples that could cause Limited tracking include: Obscuring the image so that it is not visible to the camera. The image is not tracked as a moving image. This can happen, for example, if the maxNumberOfMovingImages is exceeded.
Tracking	The underlying AR SDK reports that it is actively tracking the image.

When an image leaves the device camera's field of view, the AR Tracked Image Manager might set its trackingState to Limited instead of removing it. A value of Limited indicates that the AR Tracked Image Manager is aware of an image but can't currently track its position.

Determine when an image is visible

There is no API to determine the visibility of an image. Generally, if the tracking state is Tracking, it likely changes to Limited when the image isn't visible. However, there are other situations in which the tracking state can be in states other than Tracked.

If this information is important to your application, considering comparing the ARTrackedImage's transform with the camera's view frustum.

Removed

When an image is no longer detected, the AR Tracked Image Manager might remove it. Removed images can no longer be updated. If a removed image's Destroy On Removal property is set to true, the AR Tracked Image Manager will destroy it immediately after invoking the trackablesChanged event.

Important

Do not call Destroy on any AR Tracked Image component or its GameObject. AR images are managed by the AR Tracked Image Manager component, and destroying them yourself can result in errors. Consider disabling the GameObject instead.