> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/meta-quest-vision.md).

# Meta Quest Vision 设置

`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。

### 所需权限

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

{% code title="AndroidManifest.xml" %}

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

{% endcode %}

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

### 设置 QuestVisionFrameSource

{% stepper %}
{% step %}

#### 导入 Meta XR SDK

从 Meta XR Developer Hub 或 Unity 资源商店安装 Meta XR SDK 包。添加一个 `PassthroughCameraAccess` 组件到场景中的一个 GameObject 上——该组件由 Meta SDK 提供，用于处理底层透视摄像头 API。
{% endstep %}

{% step %}

#### 添加 QuestVisionFrameSource

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

{% step %}

#### 分配 PassthroughCameraAccess 引用

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

{% step %}

#### 添加一个视觉发布器

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

{% step %}

#### 声明 manifest 权限

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

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

在 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 功能文档以配置发布策略、设置适合你的带宽目标的帧率和分辨率，并在开发期间启用调试预览叠加层。

{% content-ref url="/pages/b40605131fc22d0b4a7a0e62e0e97c744ec19d0e" %}
[视觉](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision.md)
{% endcontent-ref %}

{% content-ref url="/pages/a05c31e79a2f905396785b4f77b4554fc046528d" %}
[iOS 和 Android](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/ios-and-android.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/meta-quest-vision.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.