ARTrackedImage has no name

[unity_4F3B7922DC57567DC247]

Hi,

I added a XRReferenceImageLibrary via Runtime and with the MutableRuntimeReferenceImageLibrary method ScheduleAddImageWithValidationJob I added a referenceImage.
The image is also recognized in the XR test environment.

Now the problem is, that when I want to read the name of the referenceImage on the event, it’s empty. The log just says:

“Found image:
UnityEngine.Debug:Log (object)”

So the name is missing.

Here is my code:

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using Unity.VisualScripting;
using Unity.XR.CoreUtils;
using UnityEditor.VersionControl;
using UnityEditor.XR.ARSubsystems;
using UnityEngine;
using UnityEngine.Networking;
using UnityEngine.Tilemaps;
using UnityEngine.XR.ARFoundation;
using UnityEngine.XR.ARSubsystems;

public class OnStartUp : MonoBehaviour
{
    [SerializeField] private Response response;

    [SerializeField]
    private XRReferenceImageLibrary runtimeImageLibrary;

    private ARTrackedImageManager trackImageManager;

    // Start is called before the first frame update
    public void Start()
    {
        Debug.Log("Started Game");

        StartCoroutine(DownloadJson());
    }

    IEnumerator DownloadJson()
    {
        Debug.Log("Download json file");
        String url = Config.APPURL + "data.json";
        UnityWebRequest www = UnityWebRequest.Get(url);
        yield return www.SendWebRequest();

        if (www.result != UnityWebRequest.Result.Success)
        {
            Debug.Log("Download json file failed");
            Debug.Log(www.error);
        }
        else
        {
            Debug.Log("Download json file successfully");
            Debug.Log(www.downloadHandler.text);
            Debug.Log("Parse json file");
            response = JsonUtility.FromJson<Response>(www.downloadHandler.text);
            Debug.Log("Parse json file successfully");
            Debug.Log("Download image targets");

            trackImageManager = gameObject.AddComponent<ARTrackedImageManager>();
            trackImageManager.referenceLibrary = trackImageManager.CreateRuntimeLibrary(runtimeImageLibrary);
            trackImageManager.enabled = true;
            trackImageManager.trackedImagesChanged += OnTrackedImagesChanged;


            for (int i = 0; i < response.files.Count; i++)
            {
                StartCoroutine(RetrieveTextureFromWeb(response.files[i]));
            }
        }
    }

    IEnumerator RetrieveTextureFromWeb(FileData fileData)
    {
        String url = Config.APPURL + "TrackingImage/" + fileData.image;
        Debug.Log("Download image target \"" + fileData.image + "\"");
        using (UnityWebRequest uwr =
            UnityWebRequestTexture.GetTexture(url))
        {
            yield return uwr.SendWebRequest();
            if (uwr.result != UnityWebRequest.Result.Success)
            {
                Debug.Log(uwr.error);
            }
            else
            {
                Debug.Log("Download image target \"" + fileData.image + "\" successfully");
                Texture2D imageFromWeb;
                var texture = DownloadHandlerTexture.GetContent(uwr);
                
                imageFromWeb = texture;

                CreateImageTargetFromDownloadedTexture(fileData.image, imageFromWeb);
            }
        }
    }


    void CreateImageTargetFromDownloadedTexture(String name, Texture2D image)
    {
        float x = 0.2f;

        Debug.Log("Add image target \"" + name + "\"");
        if (trackImageManager.referenceLibrary is MutableRuntimeReferenceImageLibrary mutableLibrary) {
            AddReferenceImageJobState jobState = mutableLibrary.ScheduleAddImageWithValidationJob(image, name, x);

            if (jobState.status == AddReferenceImageJobStatus.Success)
            {
                Debug.Log($"Added image {name} successfully.");
            }
            else
            {
                Debug.LogWarning($"Failed to add image {name} to library. {jobState.status}");
            }
        }
        else
        {
            Debug.Log($"The reference image library is not mutable.");
        }
    }

    void OnTrackedImagesChanged(ARTrackedImagesChangedEventArgs eventArgs)
    {
        foreach (ARTrackedImage trackedImage in eventArgs.added)
        {
            // Display the name of the tracked image
            Debug.Log("Found image: " + trackedImage.referenceImage.name);
        }

        foreach (ARTrackedImage trackedImage in eventArgs.updated)
        {
            // Display the name of the tracked image
            Debug.Log("Found image: " + trackedImage.referenceImage.name);
        }
    }
}

[System.Serializable]
public class Response
{
    public List<FileData> files;
}

[System.Serializable]
public class FileData
{
    public string image;
    public string model;
    public float scale;
}

[makaka-org]

In Short, use Unity 2022.3 and AR Foundation 5 instead, which are recommended for production for Now. Mutable Library works incorrectly in Unity 6.

Long Discussion:

Tracking images from MutableRuntimeReferenceImageLibrary

Hello everyone. I am developing an augmented reality application. I am a newbie in Unity, so do not judge strictly if this is some kind of trivial question. The task is as follows: I have a server from which I download images and videos after authorization. Then the user can go to the AR scene. Accordingly, when scanning one of the downloaded images, the corresponding video should appear. For this approach, I use Mutable Runtime Reference Image Library. Images are added to the library after the …

My Article about Testing Mutable Library:

AR Testing: New Unity 2024 — AR Foundation Editor Remote

[unity_4F3B7922DC57567DC247]

Thank you for the answer.
But I don’t really get it. I’m using 2022.349f1. ImageTracking with XRReferenceImageLibrary is part of the AR Foundation I thought?

[makaka-org]

You set the tag 6-0-Preview for your post — it is intended for Unity 6.

Operating with XRReferenceImageLibrary is a part of the AR Foundation.

Unity 2022.3 supports AR Foundation 5 and not AR Foundation 6, if you are talking about this.

[unity_4F3B7922DC57567DC247]

Sorry, I removed that.
Okay, I’m using AR Foundation 5 with 2022.3 like in the Docs.
The Tracking works, but I cannot access the name of the Image of the event (like in the Code above).
That’s the only problem. Why does the XRReferenceImage of the event has no informaton ? also no GUUID, height or everthing else

[makaka-org]

This is because XR simulation has specific needs to test Mutable Library and Image Tracking properly.

I really described all you need in the 2 links provided. It solves everything.

[makaka-org]

I just can duplicate My Tutorial here.

This is a Video Demo on How to test Mutable Runtime Reference Image Library correctly in Unity based on my Text Tutorial.

Mutable Runtime Reference Image Library - AR Testing: New Unity 2025 — AR...

Testing of Mutable Runtime Reference Image Library in Unity Editor: XR Simulation + AR Foundation

MutableRuntimeReferenceImageLibrary is intended to add Images for Tracking on the go when the user has running app on his phone. Using AR Foundation 5.1.0+ and the next tips, you can test the Adding of New Images into the Mutable Library in the Runtime correctly with XR Simulation.

---

Demo Scene to Test

There is BasicImageTracking Example Scene that uses Mutable Library in AR Foundation Samples, and I:

1. Duplicated the Simulated Environment by Default: Window — XR — AR Foundation — XR Environment — XR Environment overlay — Pencil icon — Duplicate Environment.

2. Added one more Tracked Image next to the existing one on the Scene and set the Image field of its Simulated Tracked Image component for All Images: to bind a simulated tracked image to your reference image library.

3. Added the next parts of code in the OnTrackablesChanged() method of ARTrackedImageManager.cs.

---

2 Approaches to Test

You can test the Adding of New Image in Runtime using 2 predefined lists.

1. added list

{
    Debug.Log("added  : " + newImage.referenceImage.guid);
}

There is no reaction to added list when a new image added to the library during runtime because all Simulated Tracked Images were in the Camera View at start.

The Simulated Environment assumes that AR Image is static in the environment, so once it appears in the camera view, it marks as static because this is not a separate image — this is a container for an image (SimulatedTrackedImage.cs) which is not moving.

To trigger added list, you just need to add a new SimulatedTrackedImage.cs into the camera view: you can just place the SimulatedTrackedImage Game Objects before the Scene Start at some distance to the right/to the left from the Camera View.

This method will not work for true testing goals:
Scene View — open Duplicated Simulation Environment prefab to observe camera position — root Game Object — Simulation Environment component — Camera Starting Pose — Rotation/Position.

2. updated list

{
    Debug.Log("updated: " + newImage.referenceImage.guid);
}

It can trigger perfectly for Added Image in Runtime and you can track the first appearance after adding an image to the library.

Complete AR Testing Tutorial:

AR Testing: New Unity 2025 — AR Foundation Editor Remote

[unity_4F3B7922DC57567DC247]

Okay thank you, but that does not solve the problem.
One interesting thing might help from the tutorial:

When XR Simulation detects images that are not part of the reference image library, the corresponding [ARTrackedImage] Instead, the guid property of the [referenceImage] is set to zero, and its texture is set to null .

In my simulation I have exactly this issue. So that meant, that the image in not party of the mutable libary, but why? When I count the mutableLibrary after adding it, it says “1”, also the job was processes successfully.
But looks like the image is not right in the libary.

[makaka-org]

@unity_4F3B7922DC57567DC247

but why?

This way works XR Simulation. Container for Image and Image attached to the Library are different things — here — in XR Simulation.

There is one more thing that you may miss just right above in my tutorial, but it is shown in the video above:

With XR Simulation, can detect and track all simulated tracked images in the Unity Editor, even if you have not included their textures in your reference image library.

To optionally bind a simulated tracked image to your reference image library, set the Image field of its Simulated Tracked Image component to reference a texture asset that is also used in the reference image library.

[unity_4F3B7922DC57567DC247]

But I attached the image in the XR simulation the right way:

Everything is set up right I thing.

The strange thing is, when I try it on an iphone it’s working and showing the image name

[makaka-org]

Well, you may have missed my recommendations about position of image related to camera at start

[andyb-unity]

@unity_4F3B7922DC57567DC247

Why does the XRReferenceImage of the event has no informaton ? also no GUUID, height or everthing else

There was a design oversight in AR Foundation 5 that you need to have the Keep Texture at Runtime option enabled in order to see GUIDs or other reference image information from a tracked image. In Unity 6 we have added new API that removes this restriction.

You can read more about the history of this issue here: How to bind reference image with SimulatedTrackedImage · Issue #1039 · Unity-Technologies/arfoundation-samples · GitHub

So with AR Foundation 5 if you want this to work in Simulation, you need to check Keep Texture at Runtime as shown in the gif in our docs: AR Tracked Image Manager component | AR Foundation | 5.1.5

[unity_4F3B7922DC57567DC247]

Thank you for the answer.
But how can I activate " Keep Texture at Runtime", when I add an image to the libary through script?

Here is how I add an image:

void CreateImageTargetFromDownloadedTexture(String name, Texture2D image)
{
    float x = 0.2f;

    Debug.Log("Add image target \"" + name + "\"");
    if (trackImageManager.referenceLibrary is MutableRuntimeReferenceImageLibrary mutableLibrary) {
        AddReferenceImageJobState jobState = mutableLibrary.ScheduleAddImageWithValidationJob(image, name, x);
    }
    else
    {
        Debug.Log($"The reference image library is not mutable.");
    }
}

[andyb-unity]

@unity_4F3B7922DC57567DC247

But how can I activate " Keep Texture at Runtime", when I add an image to the libary through script?

I looked into it, and I don’t think this is possible with the current API. My recommendation would be to upgrade to Unity 6 / AR Foundation 6 if you need this feature. Keep Texture at Runtime is not required in AR Foundation 6.

[jaelcio-dutra]

Hi Guys, I know this issue is a year old but for those who are having the same problem know that it was fixed in the Ar Foundation Package version 6.3.2.

Changelog | AR Foundation | 6.3.2

I tested grabbing the reference image names and is now returning the right name. Not null as the OP posted.

[makaka-org]

Yes, fix provided:

After upgrading to ARF 6.3.1, referenceImage guid/name becomes empty on device

This is fixed in 6.3.2 (released December 18, 2025)