> 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 包，因此无需修改 Convai SDK，即可更新或替换 Meta XR 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 Asset Store 安装 Meta XR SDK 包。在场景中的某个 GameObject 上添加 `PassthroughCameraAccess` 组件。该组件由 Meta SDK 提供，用于处理底层透视摄像头 API。
{% endstep %}

{% step %}

#### 添加 QuestVisionFrameSource

在场景中的某个 GameObject 上添加 `QuestVisionFrameSource` 组件。它可以与 `PassthroughCameraAccess` 位于同一个 GameObject 上，也可以位于另一个 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 状态应显示 **就绪**。角色将开始接收透视画面，并能对看到的内容作出回应。
{% endhint %}

在 Unity 编辑器中， `QuestVisionFrameSource` 不会生成任何帧。如果调用 `StartCapture()` ，该源将转为 `Failed` 状态，并返回 `InvalidConfiguration` —— `PassthroughCameraAccess` 仅在 Horizon OS 上可用。请在 Quest 3 或 3S 实机上测试 Vision。

### Inspector 参考

| 字段          | 默认值                 | 说明                                                                                                                                         |
| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **透视摄像头访问** | 无                   | 对 `PassthroughCameraAccess` 组件的可选引用。留空时会从活动场景中自动查找该组件。组件最多重试三次，每次间隔一秒，然后进入 `Failed` 状态——如果该组件 `PassthroughCameraAccess` 异步初始化或延迟初始化，请显式指定。 |
| **源 ID**    | `quest-passthrough` | 供 `ConvaiVisionPublisher` 用于选择此帧源的标识符。                                                                                                     |
| **最大输出宽度**  | 1280                | 发送到 Convai 的帧的最大像素宽度。调低该值可减少带宽使用量。                                                                                                         |
| **最大输出高度**  | 720                 | 发送到 Convai 的帧的最大像素高度。                                                                                                                      |
| **目标帧率**    | 15                  | 透视采集循环的每秒帧数上限。调低该值可减少带宽和处理负载。                                                                                                              |
| **翻转 Y 轴**  | true                | 垂直翻转透视纹理，使发布的帧为正向（顶部朝上）。仅当你的 Meta SDK 版本在将纹理交给 Unity 之前已处理方向时，才禁用此选项。                                                                      |

### 使用示例

#### 利用透视场景感知开展外科住院医师培训

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

**设置：** `QuestVisionFrameSource` 位于场景中的某个 GameObject 上，并配有 **透视摄像头访问** 自动发现。 `ConvaiVisionPublisher` 在同一对象上。清单中声明了这两项权限。角色的 Convai 配置包含一条支持视觉的系统提示，指示角色识别并回应其在透视画面中看到的内容。

**结果：** 角色会结合对话回应视觉情境——“我看到你正在准备手术刀，我们来一起复习一下这项手术的切口深度。”住院医师可以同时练习语言交流和实际操作，无需在 Unity 项目中编写任何物体检测代码。

#### 通过环境物体识别进行工业安全检查

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

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

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

### 故障排查

| 症状                                        | 可能原因                                                                                                                                      | 解决方法                                                                                                                    |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 源转换为 `Failed / DeviceUnavailable` 场景加载后几秒 | `PassthroughCameraAccess` 重试三次后仍未找到 — 或 — 缺失 `horizonos.permission.HEADSET_CAMERA` / `android.permission.CAMERA` 位于 `AndroidManifest.xml` | (1) 添加 `PassthroughCameraAccess` 到场景中，或在 **透视摄像头访问** 检查器字段中显式指定它。(2) 确认以下两个权限都已在 `AndroidManifest.xml` 并显示在导出的 APK 清单中。 |
| `QuestVisionFrameSource` 在编辑器中不会产生任何输出    | 预期结果 — `PassthroughCameraAccess` 仅在 Horizon OS 上运行                                                                                        | 请在实体 Quest 3 或 3S 设备上进行测试。                                                                                              |
| 角色无法响应视觉上下文                               | Vision 发布器未连接，或角色配置中未启用 Vision                                                                                                            | 验证 `ConvaiVisionPublisher` 已添加到场景中，并且已在角色的 Convai 控制面板配置中启用 Vision。                                                     |
| 透视画面正常，但图像上下颠倒                            | **翻转 Y 轴** 已禁用                                                                                                                            | 重新启用 **翻转 Y 轴** 中的 `QuestVisionFrameSource` 检查器。                                                                        |

### 后续步骤

配置好 `QuestVisionFrameSource` 并声明清单权限后，你的 Quest 构建即可在设备上进行测试。请参阅 Vision 功能文档，了解如何配置发布策略、根据带宽目标设置帧率和分辨率，以及如何在开发期间启用调试预览叠加层。

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

{% content-ref url="/pages/a05c31e79a2f905396785b4f77b4554fc046528d" %}
[iOS 和 Android](https://docs.convai.com/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.
