> 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/usage-examples.md).

# 使用示例

## 实践中的 Vision — 实现示例

本页中的示例演示了用于真实交互式模拟场景的端到端 Vision 设置。每个示例都会描述上下文、列出要添加的组件、展示 Inspector 配置，并包含所需的任何脚本。所有示例都假定 `ConvaiRoomManager.Connection Type` 被设置为 **视频**.

***

### 示例 1：安全合规培训 — 工厂现场摄像头画面

**场景：** 一个虚拟安全官 NPC 监控着工业厂房地面模拟场景的实时摄像头画面。受训者必须识别并报告危险；NPC 观察同一个摄像头，并根据它所看到的内容提供纠正性反馈。

#### 组件设置

1. 添加 `ConvaiVisionPublisher` 添加到 NPC 的根 GameObject。
2. 添加 `CameraVisionFrameSource` 添加到同一个 GameObject。
3. 将俯视的工厂车间摄像头分配给 **目标摄像机**.
4. 设置 **捕获预设** 到 `高细节` （1920 × 1080 @ 30 fps），这样 NPC 就能识别设备标签和按颜色编码的安全标记。
5. 在 `ConvaiVisionPublisher`中，设置 **发布策略** 到 `高响应` （15 fps，1 Mbps），这样 NPC 就能及时对地面上的变化作出反应。
6. 留空 **帧源组件** 留空 — 发布器会自动发现同一个 GameObject 上的源。

#### Inspector 摘要

| 组件                        | 字段    | 值           |
| ------------------------- | ----- | ----------- |
| `CameraVisionFrameSource` | 捕获预设  | `高细节`       |
| `CameraVisionFrameSource` | 目标摄像机 | *（工厂车间摄像头）* |
| `ConvaiVisionPublisher`   | 发布策略  | `高响应`       |

此场景无需编写脚本。

***

### 示例 2：工业设备入职培训 — 网络摄像头识别

**场景：** 一名技术人员在基于桌面的入职培训模拟中，将一个实体组件举到自己的网络摄像头前。Convai NPC 会识别该组件，确认其零件编号，并引导技术人员完成安装流程。

#### 组件设置

1. 添加 `ConvaiVisionPublisher` 是位于 `WebcamVisionFrameSource` 添加到同一个场景 GameObject。
2. 留空 **摄像头设备名称** 留空以选择默认网络摄像头。
3. 设置 **请求宽度** / **高度** 到 `1280` / `720` 是位于 **请求 FPS** 到 `15`.
4. 设置 **最大输出宽度** 到 `1280` 是位于 **最大输出高度** 到 `720`.
5. 设置 `ConvaiVisionPublisher`的 **发布策略** 到 `自动兼容` — 10 fps 足以处理静态或缓慢移动的物体。

#### Inspector 摘要

| 组件                        | 字段      | 值                |
| ------------------------- | ------- | ---------------- |
| `WebcamVisionFrameSource` | 摄像头设备名称 | *（留空 — 第一个可用设备）* |
| `WebcamVisionFrameSource` | 请求宽度    | `1280`           |
| `WebcamVisionFrameSource` | 请求高度    | `720`            |
| `WebcamVisionFrameSource` | 请求 FPS  | `15`             |
| `ConvaiVisionPublisher`   | 发布策略    | `自动兼容`           |

#### 脚本：在下拉式 UI 中显示可用设备

```csharp
using UnityEngine;
using UnityEngine.UI;
using Convai.Runtime.Vision.Sources;

public class WebcamSelector : MonoBehaviour
{
    [SerializeField] Dropdown _dropdown;
    [SerializeField] WebcamVisionFrameSource _source;

    void Start()
    {
        string[] devices = WebcamVisionFrameSource.GetAvailableDeviceNames();
        _dropdown.AddOptions(new System.Collections.Generic.List<string>(devices));
        _dropdown.onValueChanged.AddListener(OnDeviceSelected);
    }

    void OnDeviceSelected(int index)
    {
        string[] devices = WebcamVisionFrameSource.GetAvailableDeviceNames();
        _source.SwitchWebcamAsync(devices[index]);
    }
}
```

***

### 示例 3：在 Meta Quest 上进行 VR 设施导览

**场景：** 一名 Convai 导览 NPC 陪同新员工在 Meta Quest 头戴设备上完成一场虚拟与实体混合的设施参观。NPC 通过透视画面观察真实环境，并指出安全出口、设备工位和流程检查点。

#### 组件设置

1. 添加 `ConvaiVisionPublisher` 是位于 `QuestVisionFrameSource` 添加到一个持久化的场景 GameObject。
2. 留空 **透视相机访问** 留空 — 源会自动发现 `PassthroughCameraAccess` 的引用。
3. 留空 **翻转 Y** 已启用（默认 `true`).
4. 设置 **目标帧率** 到 `15` （默认）。
5. 设置 `ConvaiVisionPublisher`的 **发布策略** 到 `自动兼容`.
6. 请确保已安装 Meta XR SDK，并且 `PassthroughCameraAccess` 组件已存在且处于启用状态。

{% hint style="warning" %}
`QuestVisionFrameSource` 仅能在 Meta Quest 硬件上正常工作。在编辑器或其他平台上，源会进入 `失败` 状态，并且不会产生任何帧。 `ErrorKind = UnsupportedPlatform`时。使用 `CameraVisionFrameSource` 用于在编辑器中测试此场景。
{% endhint %}

#### Inspector 摘要

| 组件                       | 字段   | 值      |
| ------------------------ | ---- | ------ |
| `QuestVisionFrameSource` | 翻转 Y | `true` |
| `QuestVisionFrameSource` | 目标帧率 | `15`   |
| `ConvaiVisionPublisher`  | 发布策略 | `自动兼容` |

***

### 示例 4：手动触发快照会话

**场景：** 一项流程化评估会向受训者呈现一系列安全检查任务。每完成一项任务后，受训者点击 **提交** 按钮，触发一次 Vision 发布突发，以便 NPC 评估场景状态。任务之间会暂停发布，以减少带宽成本。

#### 组件设置

1. 添加 `ConvaiVisionPublisher` 是位于 `CameraVisionFrameSource` 按正常方式。
2. 设置 `ConvaiVisionPublisher`的 **发布策略** 到 `Manual`。房间连接时，发布器不会自动启动。

#### Inspector 摘要

| 组件                        | 字段   | 值        |
| ------------------------- | ---- | -------- |
| `CameraVisionFrameSource` | 捕获预设 | `平衡`     |
| `ConvaiVisionPublisher`   | 发布策略 | `Manual` |

#### 脚本：从 UI 按钮触发发布

```csharp
using UnityEngine;
using Convai.Modules.Vision;

public class InspectionSubmitButton : MonoBehaviour
{
    [SerializeField] ConvaiVisionPublisher _visionPublisher;
    [SerializeField] float _publishDurationSeconds = 3f;

    public void OnSubmitClicked()
    {
        StartCoroutine(PublishBurst());
    }

    System.Collections.IEnumerator PublishBurst()
    {
        _visionPublisher.EnablePublishing(true);
        yield return new WaitForSeconds(_publishDurationSeconds);
        _visionPublisher.EnablePublishing(false);
    }
}
```

{% hint style="info" %}
在 `Manual` 策略， `EnablePublishing(true)` 使用 `自动兼容` 速率（10 fps，750,000 bps），除非你调用 `SetPublishPolicy` 在启用之前将其设置为其他值。若要使用不同的速率，请调用 `SetPublishPolicy` 先：

```csharp
_visionPublisher.SetPublishPolicy(VisionPublishPolicy.HighResponsiveness);
_visionPublisher.EnablePublishing(true);
```

{% endhint %}

***

## 结论

这些示例涵盖了最常见的四种 Vision 配置：用于模拟监控的场景摄像头画面、用于对象识别的实体网络摄像头、用于混合现实引导的 Meta Quest 透视画面，以及用于评估工作流的手动策略发布。每个示例都建立在相同的双组件基础之上——一个帧源和一个发布器——仅根据场景不同而变化源类型和发布策略。关于脚本 API、自定义帧源实现以及领域事件，请继续查看 [高级主题](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/advanced-topics.md).


---

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