Image Tracking Sample

This sample demonstrates how to detect and augment image targets found in the real world. For basic information about image tracking and what AR Foundation's AR Tracked Image Manager component does, please refer to the Unity documentation (opens new window). In order to use this feature it has to be enabled in the OpenXR plugin settings located under Project Settings > XR Plug-in Management > OpenXR.

How the sample works

First and foremost, make sure to have the Image Tracking feature enabled in the OpenXR project settings.

TIP

You can find the used reference images in the Image Targets for Testing section

Image targets are fed to the underlying XR plugin through a XR Reference Image Library. The added image has a name which will be useful for identifying a tracked target later on, and an important flag Keep Texture at Runtime which should set to true. This enables the subsystem to pass the texture data to the Snapdragon Spaces Services for tracking purposes. Lastly the texture should have the Read/Write flag also enabled, which could be found under its import settings.

Images must be in a RGB 24bit format - which may also appear as RGB8.

Additionally, the image target in the sample's case was measured at 26 cm in height (when printed in DIN A4 or US letter). The correct measures are essential for a correct pose estimation and subsequent placement of an augmentation. Therefore, it must be specified after enabling Specify Size.

There is just one component needed in the scene to track images when running the experience. Adding the ARTrackedImageManager to the ARSession gameObject will enable the Image Tracking Subsystem included in the Snapdragon Spaces package. The component provides three fields: a field for the RuntimeReferenceimageLibrary created above, a field for specifying the Max Number Of Moving Images, and a field for defining a prefab to spawn upon detecting a tracked image. The prefab used is the target image of the Snapdragon Spaces Town rendered as a textured mesh.

By subscribing to the ARTrackedImageManager's method to listen for tracked images changes, the appropriate UI information gets set for the tracking state and position of the tracked image, as seen in the simplified code example below.

WARNING

For this sample to work the reference image names set in the XR Reference Image Library need to be unique. Any identical names will cause a hash code collision in the _trackedImages Dictionary.

    ...

    private Dictionary<TrackableId, ...> _trackedImages = new Dictionary<TrackableId, ...>();

    public override void OnEnable() {
        ...
        FindObjectOfType<ARTrackedImageManager>().trackedImagesChanged += OnTrackedImagesChanged;
    }

    public override void OnDisable() {
        ...
        FindObjectOfType<ARTrackedImageManager>().trackedImagesChanged -= OnTrackedImagesChanged;
    }

    private void OnTrackedImagesChanged(ARTrackedImagesChangedEventArgs args) {
        foreach (var trackedImage in args.added) {
            if (trackedImage.referenceImage.name == "Spaces Town") {
                _trackedImages.Add(trackedImage.trackableId, ...);
                ...
            }
        }

        foreach (var trackedImage in args.updated) {
            var info = _trackedImages[trackedImage.trackableId];
            ...
        }

        foreach (var trackedImage in args.removed) {
            _trackedImages.Remove(trackedImage.trackableId);
            ...
        }
    }