Meta Quest Vision 设置

配置 QuestVisionFrameSource，将 Meta Quest 透视摄像头流式传输到 Quest 3 和 3S 构建中的 Convai 角色。

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

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

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

所需权限

这两个权限都必须在你的 AndroidManifest.xml中声明。没有它们，透视摄像头将无法启动，并且 QuestVisionFrameSource 将进入 失败 状态，在三次重试后。

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 资源商店安装 Meta XR SDK 包。添加一个 PassthroughCameraAccess 组件到场景中的一个 GameObject 上——该组件由 Meta SDK 提供，用于处理底层透视摄像头 API。

2

添加 QuestVisionFrameSource

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

3

分配 PassthroughCameraAccess 引用

将 PassthroughCameraAccess 组件到 透视相机访问 上的字段 QuestVisionFrameSource。如果留空，该组件会在调用时自动搜索当前活动场景， StartCapture() 会被调用。场景中存在多个 PassthroughCameraAccess 实例时，请显式分配。

4

添加一个视觉发布器

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

5

声明 manifest 权限

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

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

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

检查器参考

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

使用示例

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

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

设置： QuestVisionFrameSource 在场景中的一个 GameObject 上，使用 透视相机访问 自动发现。 ConvaiVisionPublisher 在同一个对象上。manifest 中已声明这两个权限。角色的 Convai 配置包含一个具备视觉感知的系统提示，指示它承认并响应透视流中所看到的内容。

结果： 角色会结合对话和视觉上下文作出回应——“我看到你正在准备手术刀——让我们回顾一下这次手术的切口深度。”住院医师可以在 Unity 项目中无需任何物体检测代码的情况下，同时练习口头交互和实体任务执行。

带有环境物体识别的工业安全检查

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

设置： 与医疗培训示例相同的配置。 目标帧率 被设置为 10（从 15 降低）以适应带宽有限的工业网络环境。 最大输出宽度 被设置为 960，以减小每帧负载大小，同时不会对物体识别任务造成明显的质量损失。

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

故障排查

症状	可能原因	修复
源切换到 失败 / DeviceUnavailable 场景加载后几秒钟	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	验证 ConvaiVisionPublisher 已在场景中，且角色的 Convai 仪表板配置中已启用 Vision。
透视流正确但图像看起来是上下颠倒	翻转 Y 已禁用	重新启用 翻转 Y 在 QuestVisionFrameSource 检视面板。

下一步

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

视觉iOS 和 Android