Meta Quest Vision 设置

说明如何将 Meta Quest 透视摄像头流式传输给 Convai 角色，使其能够看到玩家的真实周围环境。

QuestVisionFrameSource 将 Meta Quest 头显的透视摄像头画面流式传输到 Convai，使 AI 角色能够看见并响应学习者所看到的真实世界。本页涵盖所需的 Android manifest 权限、逐步的组件设置、Inspector 字段参考，以及针对 Quest 3 和 Quest 3S 的故障排查。

支持的硬件： 运行 Horizon OS 且可用 Passthrough Camera API 的 Meta Quest 3 和 Quest 3S。

该组件使用反射在运行时绑定到 Meta XR SDK 的 PassthroughCameraAccess 在运行时。Convai SDK 与任何 Meta SDK 包都没有硬性的编译时依赖——你可以更新或替换 Meta XR SDK 版本，而无需修改 Convai SDK。

所需权限

这两个权限都必须在你的 AndroidManifest.xml。透视摄像头在没有它们的情况下不会启动，并且 QuestVisionFrameSource 将进入 Failed 状态，在三次重试后。

AndroidManifest.xml

<uses-permission android:name="horizonos.permission.HEADSET_CAMERA" />
<uses-permission android:name="android.permission.CAMERA" />

将这两个条目添加到 Assets/Plugins/Android/AndroidManifest.xml。如果该文件不存在，请创建它——Unity 会在构建时将其与生成的 manifest 合并。构建后，请验证导出的 APK 中的 manifest 是否包含这两个权限。

设置 QuestVisionFrameSource

1

导入 Meta XR SDK

从 Meta XR Developer Hub 或 Unity Asset Store 安装 Meta XR SDK 包。向场景中的一个 GameObject 添加一个 PassthroughCameraAccess 组件——该组件由 Meta SDK 提供，负责底层的透视摄像头 API。

2

添加 QuestVisionFrameSource

添加 QuestVisionFrameSource 组件到场景中的一个 GameObject。它可以与 PassthroughCameraAccess 是同一个 GameObject，也可以是单独的一个。

3

分配 PassthroughCameraAccess 引用

将 PassthroughCameraAccess 组件拖到 透视摄像头访问 字段在 QuestVisionFrameSource。如果留空，当调用 StartCapture() 时，组件会自动在活动场景中搜索。若场景中存在多个 PassthroughCameraAccess 实例，请显式分配。

4

添加一个 vision 发布器

添加 ConvaiVisionPublisher 到同一个 GameObject。它会自动发现 QuestVisionFrameSource 在场景中，或者你也可以在发布器的 Inspector 字段中分配帧源引用。

5

声明 manifest 权限

添加这两个 horizonos.permission.HEADSET_CAMERA 和 android.permission.CAMERA 到你的 AndroidManifest.xml 于 Assets/Plugins/Android/AndroidManifest.xml。请参见上方“所需权限”部分。

构建并部署到你的 Quest 设备。场景加载后，Convai Settings Panel 中的 Vision 状态应显示 就绪。角色将开始接收透视帧，并能对其所见内容做出响应。

在 Unity 编辑器中， QuestVisionFrameSource 不会生成任何帧。如果 StartCapture() 被调用，源将切换到 Failed 状态，并 InvalidConfiguration — PassthroughCameraAccess 仅适用于 Horizon OS。请在实体 Quest 3 或 3S 设备上测试 Vision。

检查器参考

字段	默认	说明
透视摄像头访问	无	对以下内容的可选引用： PassthroughCameraAccess 组件。如果留空，将从活动场景中自动发现。该组件在进入 Failed 状态之前会以一秒间隔重试最多三次——若 PassthroughCameraAccess 异步初始化或延迟初始化，请显式分配。
源 ID	quest-passthrough	由 ConvaiVisionPublisher 用于选择此帧源的标识符。
最大输出宽度	1280	发送给 Convai 的帧的最大像素宽度。降低它可减少带宽使用。
最大输出高度	720	发送给 Convai 的帧的最大像素高度。
目标帧率	15	透视捕获循环的每秒帧数上限。较低的值可减少带宽和处理负载。
Y 轴翻转	是	将透视纹理垂直翻转，使发布的帧为正向。仅当你的 Meta SDK 版本在将纹理交给 Unity 之前已处理好方向时才禁用。

使用示例

带有透视场景感知的外科住院医师培训

一款在 Quest 3 上的外科住院医师培训应用将学习者置于模拟手术环境中。Convai 角色扮演一名外科团队成员，能够看见并评论住院医师举起的实体道具——解剖模型、器械和手术参考卡。

设置： QuestVisionFrameSource 在带有 透视摄像头访问 的场景 GameObject 上自动发现。 ConvaiVisionPublisher 在同一个对象上。manifest 中声明了这两个权限。角色的 Convai 配置包含一个具备视觉感知能力的系统提示，指示它承认并回应透视画面中所看到的内容。

结果： 角色会连同对话一起响应视觉上下文——“我看到你正在准备手术刀——让我们复习一下这个手术的切口深度。”住院医师无需在 Unity 项目中编写任何对象检测代码，就能练习口头交互和实际任务执行。

具备环境物体识别的工业安全检查

一款在 Quest 3S 上的工厂安全培训应用引导设备操作员完成机械检查。AI 角色会识别透视画面中可见的物理组件，并根据操作员正在看的内容调整其安全指导。

设置： 与医疗培训示例相同的配置。 目标帧率 设置为 10（从 15 降低），以适应带宽受限的工业网络环境。 最大输出宽度 设置为 960，以在不明显影响物体识别任务质量的情况下减少每帧负载大小。

结果： 角色会识别透视视图中的机械设备，并提供组件特定的安全说明——无需硬编码对象检测，也无需自定义计算机视觉管线。SDK 会将透视帧流式传输到 Convai，由后者处理场景理解并生成符合上下文的指导。

故障排查

症状	可能原因	修复方法
源切换到 失败 / 设备不可用 在场景加载后的几秒钟内	PassthroughCameraAccess 在三次重试后仍未找到 —— 或 —— 缺少 horizonos.permission.HEADSET_CAMERA / android.permission.CAMERA 中的 AndroidManifest.xml	(1) 将 PassthroughCameraAccess 添加到场景中，或在 透视摄像头访问 Inspector 字段中显式分配它。(2) 验证这两个权限是否已声明在 AndroidManifest.xml 中，并出现在导出的 APK manifest 里。
QuestVisionFrameSource 在编辑器中不会产生输出	预期—— PassthroughCameraAccess 仅在 Horizon OS 上运行	请在实体 Quest 3 或 3S 设备上测试。
角色不响应视觉上下文	vision 发布器未连接，或角色配置中未启用 Vision	验证 ConvaiVisionPublisher 存在于场景中，并且已在角色的 Convai 仪表板配置中启用 Vision。
透视画面正确，但图像看起来上下颠倒	Y 轴翻转 已被禁用	重新启用 Y 轴翻转 的 QuestVisionFrameSource Inspector。

下一步

使用 QuestVisionFrameSource 完成配置并声明 manifest 权限后，你的 Quest 构建就可以进行设备端测试了。请查看 Vision 功能文档，以配置发布策略、根据你的带宽目标设置帧率和分辨率，并在开发期间启用调试预览叠加层。

视觉iOS 和 Android