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

### 所需权限

{% 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 会在构建时将其与生成的 manifest 合并。构建后，请验证导出的 APK 中的 manifest 是否包含这两个权限。

### 设置 QuestVisionFrameSource

{% stepper %}
{% step %}

#### 导入 Meta XR SDK

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

{% step %}

#### 添加 QuestVisionFrameSource

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

{% step %}

#### 分配 PassthroughCameraAccess 引用

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

{% step %}

#### 添加一个 vision 发布器

添加 `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 Settings Panel 中的 Vision 状态应显示 **就绪**。角色将开始接收透视帧，并能对其所见内容做出响应。
{% endhint %}

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

{% 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.