> 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/unity-plugin-beta-overview/features/vision.md).

# 视觉

启用 Convai 角色实时感知并响应你的 Unity 场景。Vision 功能、其组件和平台支持概览。

## Convai 角色的实时场景视觉

视觉功能赋予 Convai 角色观察 Unity 场景中所发生事情的能力。启用视觉功能后，系统会从可配置的来源持续采集视频流——场景摄像机、实体网络摄像头或 Meta Quest 头显的透视画面——并将其发布到 Convai，以便与角色的对话上下文一同处理。这样，角色便可根据实时视觉输入，对观察到的内容作出回应、描述物体、标示危险，或为用户提供引导。

视觉是一个模块级功能，依赖于 `ConvaiRoomManager` 以 **Video** 连接模式运行。在原生平台上，视频流来自 `RenderTexture`；在 WebGL 上，则通过 `canvas.captureStream()`.

## 从浏览器当前显示的画布获取视频流

```mermaid
flowchart LR
    subgraph Sources["帧来源（三选一）"]
        A1[CameraVisionFrameSource]
        A2[WebcamVisionFrameSource]
        A3[QuestVisionFrameSource]
    end

    B[ConvaiVisionPublisher\nIConvaiModule]
    C[VisionPublishCoordinator]
    D[VideoTrackManager]
    E[LiveKit Room\nWebRTC]
    F[Convai 后端\nAI 视觉处理]

    A1 -->|RenderTexture| B
    A2 -->|RenderTexture| B
    A3 -->|RenderTexture| B
    B --> C
    C -->|策略：FPS + 比特率| D
    D -->|AsyncGPUReadback| E
    E -->|WebRTC 视频轨道| F
```

在 WebGL 上， `ConvaiVisionPublisher` 会完全绕过帧来源，直接发布浏览器画布。其余管线保持不变。

## 关键概念

| 概念       | 含义                                                                                              |
| -------- | ----------------------------------------------------------------------------------------------- |
| **帧来源**  | 一种 `MonoBehaviour` ，用于采集帧并将其作为沿 Y 轴翻转的 `RenderTexture`提供。内置的三种实现分别支持摄像机、网络摄像头和 Meta Quest 透视画面。 |
| **发布策略** | 控制向后端流式传输时客户端使用的帧率和比特率。此设置不控制后端使用的 AI 模型或服务提供商。                                                 |
| **视频轨道** | 发布到当前 Convai 房间的 WebRTC 视频轨道。由 **视频轨道名称** 字段标识（默认值为 `"unity-scene"`).                           |
| **房间连接** | 只有在 `ConvaiRoomManager` 已连接，且 `Connection Type` 设置为 `Video`。仅音频连接不会传输视频。                        |

## 组件应放置在哪里

了解各个组件应放置的位置，可避免最常见的设置错误。

| 组件                        | 放置位置                          | 备注                             |
| ------------------------- | ----------------------------- | ------------------------------ |
| `ConvaiRoomManager`       | 任意持久化场景 GameObject            | **连接类型** 必须设置为 **视频**          |
| `ConvaiVisionPublisher`   | 任意持久化场景 GameObject            | 通常放置在 NPC 根对象上或其附近             |
| `CameraVisionFrameSource` | 与发布器位于同一 GameObject 上，或作为其子对象 | 每个捕获源一个                        |
| `WebcamVisionFrameSource` | 与发布器位于同一 GameObject 上，或作为其子对象 | 每个捕获源一个                        |
| `QuestVisionFrameSource`  | 与发布器位于同一 GameObject 上，或作为其子对象 | 仅适用于 Meta Quest；需要 Meta XR SDK |
| `VisionDebugPreview`      | 任意场景 GameObject               | 仅限编辑器；在播放器构建中会自动禁用             |

## 前提条件

{% hint style="info" %}
视觉功能要求 `ConvaiRoomManager.Connection Type` 设置为 **视频**。如果设置为 `Audio`，即使其他所有组件均已正确配置，发布器仍会保持闲置。
{% endhint %}

## 平台行为

| 平台            | 支持的帧来源                                               | 备注                                                 |
| ------------- | ---------------------------------------------------- | -------------------------------------------------- |
| PC / Mac / 主机 | `CameraVisionFrameSource`, `WebcamVisionFrameSource` | 完整的 RenderTexture 管线                               |
| Android / iOS | `CameraVisionFrameSource`, `WebcamVisionFrameSource` | 摄像头来源会在启动时请求摄像头权限                                  |
| WebGL         | *（Canvas，自动）*                                        | `canvas.captureStream()` 路径——无需帧来源组件；帧率上限为 15 fps  |
| Meta Quest    | `QuestVisionFrameSource`                             | 需要 Meta XR SDK；通过反射绑定到 `PassthroughCameraAccess` 。 |

## 本节内容

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>快速入门</strong></td><td>通过逐步讲解 Inspector 的操作流程，让角色接收实时摄像头画面——无需编写代码。</td></tr><tr><td><strong>帧来源</strong></td><td>针对各种平台和使用场景配置 CameraVisionFrameSource、WebcamVisionFrameSource 和 QuestVisionFrameSource。</td></tr><tr><td><strong>发布与策略</strong></td><td>选择发布策略、调整帧率和比特率，并控制视频轨道的生命周期。</td></tr><tr><td><strong>调试预览</strong></td><td>将活动帧来源显示为屏幕叠加层，并在编辑器中监控捕获状态。</td></tr><tr><td><strong>使用示例</strong></td><td>为安全培训、设备入门培训、VR 漫游和手动触发会话提供端到端示例。</td></tr><tr><td><strong>高级主题</strong></td><td>脚本 API、自定义 IVisionFrameSource、域事件、WebGL 深入解析以及平台兼容性矩阵。</td></tr><tr><td><strong>故障排查与诊断</strong></td><td>通过结构化检查清单和决策树，诊断发布失败、画面空白、权限错误及平台特定问题。</td></tr></tbody></table>

## 总结

Vision 可将 Unity 场景直接连接到角色的感知，使角色能够根据自己所见作出回应。先从快速入门开始，获取来自场景摄像机的可用流，然后使用帧源，根据你的平台和使用场景选择合适的捕获方式。


---

# 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/unity-plugin-beta-overview/features/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.
