Unity中创建MutableRuntimeReferenceImageLibrary及解决添加图片报错

错误原因 #

你遇到的CS1061错误是因为AR Foundation 4.x系列（包括4.2.7）中，MutableRuntimeReferenceImageLibrary没有同步的AddReferenceImage/Add/AddImage方法，官方提供的异步添加方法是AddImageAsync，且相关API位于UnityEngine.XR.ARSubsystems命名空间下，若未引入该命名空间也会导致找不到方法。

完整解决方案步骤 #

1. 检查图片导入设置 #

确保你要添加的图片满足以下要求：

• 勾选Read/Write Enabled（在Texture Import Settings的Advanced面板）
• Texture Type设置为Texture2D（不要设为Sprite或其他类型）
• 图片格式建议为PNG/JPG，尺寸尽量符合AR识别要求（比如正方形，分辨率不低于200x200）

2. 正确引入命名空间 #

代码头部必须包含：

using UnityEngine;
using UnityEngine.XR.ARFoundation;
using UnityEngine.XR.ARSubsystems;

3. 完整实现代码示例 #

以下是可直接复用的代码，包含创建Mutable库、异步添加图片、替换TrackedImageManager的库的逻辑：

public class ImageLibraryManager : MonoBehaviour
{
    [SerializeField] private ARTrackedImageManager _trackedImageManager;
    [SerializeField] private Texture2D[] _imagesToAdd; // 在Inspector中拖入要添加的图片

    private MutableRuntimeReferenceImageLibrary _mutableLibrary;

    private void Awake()
    {
        // 确保AR Tracked Image Manager已赋值
        if (_trackedImageManager == null)
        {
            _trackedImageManager = GetComponent<ARTrackedImageManager>();
        }
    }

    IEnumerator Start()
    {
        // 等待AR Session初始化完成
        yield return new WaitForARSessionInitialization();

        // 创建MutableRuntimeReferenceImageLibrary实例
        _mutableLibrary = _trackedImageManager.CreateRuntimeLibrary() as MutableRuntimeReferenceImageLibrary;

        if (_mutableLibrary == null)
        {
            Debug.LogError("无法创建MutableRuntimeReferenceImageLibrary，当前AR Subsystem不支持可修改的图像库");
            yield break;
        }

        // 逐个异步添加图片
        foreach (var image in _imagesToAdd)
        {
            // 调用异步添加方法，传入图片、图片名称、物理尺寸（单位：米）
            var addRequest = _mutableLibrary.AddImageAsync(image, image.name, 0.1f);
            
            // 等待添加完成
            while (!addRequest.IsDone)
            {
                yield return null;
            }

            if (addRequest.Status == AsyncStatus.Succeeded)
            {
                Debug.Log($"成功添加图片：{image.name}");
            }
            else
            {
                Debug.LogError($"添加图片失败：{image.name}，错误信息：{addRequest.Error}");
            }
        }

        // 将Tracked Image Manager的引用库替换为新创建的Mutable库
        _trackedImageManager.referenceLibrary = _mutableLibrary;
        // 重启Tracked Image Manager以应用新库
        _trackedImageManager.enabled = false;
        _trackedImageManager.enabled = true;
    }

    // 自定义等待AR Session初始化的协程
    private IEnumerator WaitForARSessionInitialization()
    {
        var arSession = FindObjectOfType<ARSession>();
        if (arSession == null)
        {
            yield break;
        }

        while (!arSession.enabled || !ARSession.state.IsSessionReady())
        {
            yield return null;
        }
    }
}

4. 关键注意事项 #

• 异步操作必须等待完成：AddImageAsync是异步方法，必须通过IsDone判断完成状态，不能直接同步调用后续逻辑
• AR Subsystem支持性：部分AR平台（如某些ARCore/ARKit版本）可能不支持Mutable库，需确保目标平台启用了对应的AR Subsystem
• 图片物理尺寸：AddImageAsync的第三个参数是图片对应的真实世界尺寸（米），这个值会影响AR识别的精度

内容的提问来源于stack exchange，提问作者Aegylon