How to Use Image Tracking Colocalization

With Image Tracking Colocalization, you can use an image target to trigger a Shared AR experience without having a VPS-Activated location. The image serves as the origin of the experience. This means you can carry a printed image with you for testing and demo purposes.

Prerequisites

1. You will need to have a Shared AR Unity project.
2. This code uses Unity's Netcode for Game Objects. Once you have setup a room, you will use that API for networking.

Steps

To setup image colocalization in your Shared AR project:

1. Select XR Origin in the Hierarchy. In the Inspector window, click Add Component, then add a Shared Space Manager.
2. In the Shared Space Manager options in the Inspector:
   1. Set the ColocalizationType to ImageTrackingColocalization.
   2. In the Shared Space Manager script, add your image tracking and room options, then pass them to SharedSpaceManager.StartSharedSpace().
3. Call StartHost() or StartClient() as normal.

tip

You will want to pick a unique room name for your project, and if you want multiple concurrent experiences without everybody in the same room, you will want different room names per session. The Shared AR Image Tracking sample uses a PIN code for this reason.

To use the image to colocalize:

1. Pick an image to identify the shared room. You can find an example image in Assets/Samples/SharedAR/IMG-2689.png. This needs to be the same image the set by the Target Image property in the Shared Space Manager.
2. Print out the image and place it on a surface. The size of the image needs to match the Target Image Size the Shared Space Manager expects (for this sample, 9cm wide).
3. Point the device camera at the image. Select Create New Room.

caution

Image tracking is not supported in the Unity editor, even with playback. You can only run it on a device.

note

You do not have to keep the image on screen at all times. If you notice some object drift during the experience, point the camera at the image to reset the origin.

Example Colocalization Script

public SharedSpaceManager _sharedSpaceManager;

[SerializeField]
private Texture2D _targetImage;

[SerializeField]
private float _targetImageSize;

public void StartSharedSpace(string roomName)
{
    var imageTrackingOptions = ISharedSpaceTrackingOptions.CreateImageTrackingOptions(
                _targetImage, _targetImageSize);
    var roomOptions = ISharedSpaceRoomOptions.CreateLightshipRoomOptions(
        roomName,
        10,
        "image tracking colocalization demo"
    );

    _sharedSpaceManager.StartSharedSpace(imageTrackingOptions, roomOptions);

    // start as host
    NetworkManager.Singleton.StartHost();
    // Or start as client
    // NetworkManager.Singleton.StartClient();
}