使用示例

四种端到端 Vision 配置，涵盖场景摄像机、物理网络摄像头、Meta Quest 透视和手动触发发布工作流。

实践中的 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 中显示可用设备

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 组件已存在且处于启用状态。

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

Inspector 摘要

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

---

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

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

组件设置

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

Inspector 摘要

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

脚本：从 UI 按钮触发发布

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);
    }
}

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

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

---

结论

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