Instance Property

detectionImages

A set of images for ARKit to attempt to detect in the user's environment.

Declaration

var detectionImages: Set<ARReferenceImage>! { get set }

Discussion

Use this property to choose known 2D images for ARKit to find in the user's environment and present as ARImageAnchor for use in your AR experience. Use an Xcode asset catalog to provide reference images for ARKit to detect, or define them programmatically with the ARReferenceImage class.

ARKit has two ways to recognize images from this set during a session:

  • With image detection, ARKit reports when it first detects an image in view of the camera, and provides infrequent updates to the image anchor's transform thereafter. Image detection doesn't continuously track real-world movement of the image or track when the image disappears from view. Image detection works best for cases where AR content responds to static images in the scene—for example, identifying art in a museum or adding animated elements to a movie poster.

  • In iOS 12.0 or later, set the maximumNumberOfTrackedImages to enable image tracking. Image tracking provides continuous updates for detected images that move relative to the world, and can accurately track when images disappear from view (or reappear afterward). Image tracking is well suited to cases where AR content responds to images on moving objects—for example, adding interactive characters to a tabletop card or board game.

Performance Considerations

Image detection accuracy and performance are reduced with larger numbers of detection images. For best results, use no more than around 25 images in this set.

You can support a larger total number of detection images by changing which set of images is active for detection over time. For example, an app that identifies paintings in an art museum might limit the set of detection images based on which area of the museum the user is currently in (after using Core Location to locate the user within the museum).

To detect a different set of images without otherwise affecting the session, call the session's run(_:options:) method with a configuration containing a different detectionImages set and no options.

See Also

Enabling Image Detection and Tracking

var maximumNumberOfTrackedImages: Int

The maximum number of detection images to simultaneously track movement for.