> 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 设置

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

`QuestVisionFrameSource` 将 Meta Quest 头显中的透视摄像头画面流式传输到 Convai，使 AI 角色能够看到并回应学习者所看到的真实世界。本页涵盖所需的 Android 清单权限、分步骤组件设置、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。

### 所需权限

{% hint style="danger" %}
这两个权限都必须声明在你的 `AndroidManifest.xml`。没有它们，透视摄像头将无法启动，并且 `QuestVisionFrameSource` 将进入 `Failed` 状态，三次重试后。
{% 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 会在构建时将其与生成的清单合并。构建完成后，验证这两个权限是否出现在 APK 中导出的清单里。

### 设置 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` 组件拖入 **Passthrough Camera Access** 上的字段 `QuestVisionFrameSource`。若留空，组件会在调用 `StartCapture()` 时自动搜索当前活动场景。若场景中存在多个 `PassthroughCameraAccess` 实例，请显式分配。
{% endstep %}

{% step %}

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

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

{% step %}

#### 声明清单权限

同时添加 `horizonos.permission.HEADSET_CAMERA` 和 `android.permission.CAMERA` 到你的 `AndroidManifest.xml` 在 `Assets/Plugins/Android/AndroidManifest.xml`。请参阅上面的“所需权限”部分。
{% endstep %}
{% endstepper %}

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

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

### 字段以避免歧义。

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

### 使用示例

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

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

**设置：** `QuestVisionFrameSource` 在场景中的某个 GameObject 上，配合 **Passthrough Camera Access** 自动发现。 `ConvaiVisionPublisher` 在同一个对象上。清单中声明了这两个权限。角色的 Convai 配置包含一个具备视觉感知的系统提示，指示它承认并回应在透视画面中看到的内容。

**结果：** 角色会结合对话和视觉上下文作出回应——“我看到你正在准备手术刀——让我们复习一下这次手术的切口深度。”住院医师在 Unity 项目中无需任何对象检测代码，就能同时练习语言交流和实际操作任务。

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

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

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

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

### 故障排除

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

### 下一步

在 `QuestVisionFrameSource` 配置完成并声明清单权限后，你的 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.