[DefaultExecutionOrder(-2147483647)]
[RequireComponent(typeof(XROrigin))]
[AddComponentMenu("XR/AR Foundation/AR Tracked Image Manager")]
[Icon("Packages/com.unity.xr.arfoundation/Editor/Icons/d_ARVR@4x.png")]
public sealed class ARTrackedImageManager : ARTrackableManager<XRImageTrackingSubsystem, XRImageTrackingSubsystemDescriptor, XRImageTrackingSubsystem.Provider, XRTrackedImage, ARTrackedImage>, ITrackablesChanged<ARTrackedImage>

Remarks

Related information: AR Tracked Image Manager component

Properties

currentMaxNumberOfMovingImages

Get the maximum number of moving images to track in real time that is currently in use by the subsystem.

Declaration

public int currentMaxNumberOfMovingImages { get; }

Property Value

Type	Description
int

gameObjectName

The name to be used for the GameObject whenever a new image is detected.

Declaration

protected override string gameObjectName { get; }

Property Value

Type	Description
string

Overrides

ARTrackableManager<XRImageTrackingSubsystem, XRImageTrackingSubsystemDescriptor, XRImageTrackingSubsystem.Provider, XRTrackedImage, ARTrackedImage>.gameObjectName

referenceLibrary

Get or set the reference image library (that is, the set of images to search for in the physical environment).

Declaration

public IReferenceImageLibrary referenceLibrary { get; set; }

Property Value

Type	Description
IReferenceImageLibrary

Exceptions

Type	Condition
InvalidOperationException	Thrown if the referenceLibrary is set to `null` while image tracking is enabled.

requestedMaxNumberOfMovingImages

The requested maximum number of moving images to track in real time.

Declaration

public int requestedMaxNumberOfMovingImages { get; set; }

Property Value

Type	Description
int

Remarks

Support can vary between devices and providers. Check for support at runtime with descriptor's supportsMovingImages property. If supportsMovingImages is false, setting this property has no effect. The reverse isn't guaranteed: a provider can support moving images without supporting a configurable maximum number of them, in which case supportsMovingImages will be true, but setting this property has no effect.

trackedImagePrefab

If not null, instantiates this Prefab for each detected image.

Declaration

public GameObject trackedImagePrefab { get; set; }

Property Value

Type	Description
GameObject

Remarks

The purpose of this property is to extend the functionality of ARTrackedImages. It is not the recommended way to instantiate content associated with an ARTrackedImage.

Methods

CreateRuntimeLibrary(XRReferenceImageLibrary)

Creates a UnityEngine.XR.ARSubsystems.RuntimeReferenceImageLibrary from an existing UnityEngine.XR.ARSubsystems.XRReferenceImageLibrary or an empty library if serializedLibrary is null. Use this to construct reference image libraries at runtime. If the library is of type MutableRuntimeReferenceImageLibrary, it is modifiable at runtime.

Declaration

[Obsolete("CreateRuntimeLibrary is deprecated in AR Foundation 6.7. Use TryCreateRuntimeLibraryAsync instead.")]
public RuntimeReferenceImageLibrary CreateRuntimeLibrary(XRReferenceImageLibrary serializedLibrary = null)

Parameters

Type	Name	Description
XRReferenceImageLibrary	serializedLibrary	An existing `XRReferenceImageLibrary`, or `null` to create an empty image library.

Returns

Type	Description
RuntimeReferenceImageLibrary	A new `RuntimeReferenceImageLibrary` representing the deserialized version of `serializedLibrary` or an empty library if `serializedLibrary` is `null`.

Exceptions

Type	Condition
NotSupportedException	Thrown if there is no subsystem. This usually means image tracking is not supported.

GetPrefab()

Get the Prefab that will be instantiated for each ARTrackedImage.

Declaration

protected override GameObject GetPrefab()

Returns

Type	Description
GameObject	The Prefab that will be instantiated for each ARTrackedImage.

Overrides

ARTrackableManager<XRImageTrackingSubsystem, XRImageTrackingSubsystemDescriptor, XRImageTrackingSubsystem.Provider, XRTrackedImage, ARTrackedImage>.GetPrefab()

OnAfterSetSessionRelativeData(ARTrackedImage, XRTrackedImage)

Invoked just after updating each ARTrackedImage. Used to update the referenceImage.

Declaration

protected override void OnAfterSetSessionRelativeData(ARTrackedImage image, XRTrackedImage sessionRelativeData)

Parameters

Type	Name	Description
ARTrackedImage	image	The tracked image being updated.
XRTrackedImage	sessionRelativeData	New data associated with the tracked image. Spatial data is relative to the XROrigin.

Overrides

ARTrackableManager<XRImageTrackingSubsystem, XRImageTrackingSubsystemDescriptor, XRImageTrackingSubsystem.Provider, XRTrackedImage, ARTrackedImage>.OnAfterSetSessionRelativeData(ARTrackedImage, XRTrackedImage)

OnBeforeStart()

Sets the image library on the subsystem before Start() is called on the XRImageTrackingSubsystem.

Declaration

protected override void OnBeforeStart()

Overrides

SubsystemLifecycleManager<XRImageTrackingSubsystem, XRImageTrackingSubsystemDescriptor, XRImageTrackingSubsystem.Provider>.OnBeforeStart()

OnTrackablesChanged(List<ARTrackedImage>, List<ARTrackedImage>, List<ARTrackedImage>)

Invokes the trackedImagesChanged event.

Declaration

[Obsolete("OnTrackablesChanged() has been deprecated in AR Foundation version 6.0.", false)]
protected override void OnTrackablesChanged(List<ARTrackedImage> added, List<ARTrackedImage> updated, List<ARTrackedImage> removed)

Parameters

Type	Name	Description
List<ARTrackedImage>	added	A list of images added this frame.
List<ARTrackedImage>	updated	A list of images updated this frame.
List<ARTrackedImage>	removed	A list of images removed this frame.

Overrides

ARTrackableManager<XRImageTrackingSubsystem, XRImageTrackingSubsystemDescriptor, XRImageTrackingSubsystem.Provider, XRTrackedImage, ARTrackedImage>.OnTrackablesChanged(List<ARTrackedImage>, List<ARTrackedImage>, List<ARTrackedImage>)

TryCreateRuntimeLibraryAsync(XRReferenceImageLibrary, CancellationToken)

Attempts to create a RuntimeReferenceImageLibrary from an existing XRReferenceImageLibrary.

Declaration

public Awaitable<Result<RuntimeReferenceImageLibrary>> TryCreateRuntimeLibraryAsync(XRReferenceImageLibrary referenceImageLibrary, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
XRReferenceImageLibrary	referenceImageLibrary	An existing `XRReferenceImageLibrary`, or `null` to create an empty image library.
CancellationToken	cancellationToken	A cancellation token, which you can use to cancel the operation in progress.

Returns

Type	Description
Awaitable<Result<RuntimeReferenceImageLibrary>>	The result of the operation.

Remarks

If referenceImageLibrary is null, the new library is empty. You can only add images to the resulting library if the platform supports mutable libraries; refer to supportsMutableLibrary.

Exceptions

Type	Condition
NotSupportedException	Thrown if the provider doesn't implement asynchronous library creation.
OperationCanceledException	Thrown if the operation is canceled by `cancellationToken`.

TrySetReferenceLibrary(RuntimeReferenceImageLibrary)

Attempts to assign runtimeLibrary to this manager.

Declaration

public XRResultStatus TrySetReferenceLibrary(RuntimeReferenceImageLibrary runtimeLibrary)

Parameters

Type	Name	Description
RuntimeReferenceImageLibrary	runtimeLibrary	The runtime library to assign.

Returns

Type	Description
XRResultStatus	The status of the operation.

Examples

var status = manager.TrySetReferenceLibrary(runtimeLibrary);
if (status.IsSuccess())
    DoSomething();

Exceptions

Type	Condition
ArgumentNullException	Thrown if `runtimeLibrary` is `null`.

TrySetReferenceLibraryAsync(XRReferenceImageLibrary, CancellationToken)

Attempts to create a runtime reference image library from serializedLibrary, activate it, and assign it to this manager.

Declaration

public Awaitable<Result<RuntimeReferenceImageLibrary>> TrySetReferenceLibraryAsync(XRReferenceImageLibrary serializedLibrary, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
XRReferenceImageLibrary	serializedLibrary	The serialized library to convert to a runtime library and assign, or `null` to assign an empty library.
CancellationToken	cancellationToken	A cancellation token, which you can use to cancel the operation in progress.

Returns

Type	Description
Awaitable<Result<RuntimeReferenceImageLibrary>>	The result of the async operation.

Remarks

After this operation completes successfully, referenceLibrary returns the newly created runtime library.

Only one asynchronous operation from this method may be in progress at a time. Use the cancellationToken to cancel a previous call to this method if needed, otherwise subsequent calls will fail while an operation is in progress.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `serializedLibrary` is `null`.
OperationCanceledException	Thrown if the operation is canceled, either by `cancellationToken` or because this component was destroyed.

Events

trackedImagesChanged

Invoked once per frame with information about the ARTrackedImages that have changed (that is, been added, updated, or removed). This happens just before ARTrackedImages are destroyed, so you can set ARTrackedImage.destroyOnRemoval to false from this event to suppress this behavior.

Declaration

[Obsolete("trackedImagesChanged has been deprecated in AR Foundation version 6.0. Use trackablesChanged instead.", false)]
public event Action<ARTrackedImagesChangedEventArgs> trackedImagesChanged

Event Type

Type	Description
Action<ARTrackedImagesChangedEventArgs>

Implements

ITrackablesChanged<TTrackable>