> 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-unreal-engine-plugin/features/vision/vision-usage-examples.md).

# 视觉使用示例

应用 Unreal 视觉的常见 Blueprint 模式，包括自动启动捕获、手动控制、FPS 调优和源切换。

这些示例展示了适用于 **环境摄像头**。完成 [Vision 快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-quick-start.md) 如果你还没有为角色添加视觉功能，请先进行此操作。

每个示例都包含一个场景、要应用的设置、预期的运行时行为以及验证方法。

### 在 BeginPlay 时自动启动视觉

**场景：** 固定工位上的训练 NPC 应在关卡加载后立即开始场景捕获。

**设置：** 选择 **环境摄像头** 在角色 Blueprint 中。在 **Details** 面板中的 **Convai | 视觉**，启用 `bAutoStartVision`。分配 **Convai 渲染目标** 在进入播放模式之前。

**预期行为：** 在……期间 `BeginPlay`，该组件会调用 **开始**。当 **Convai 渲染目标** 已分配后， **获取状态** 返回 `捕获中` 并且聊天机器人可以在活动会话期间发送帧。

**验证：** 调用 **支持视觉** 在聊天机器人上，并且 **获取状态** 在 **环境摄像头**。两者都应在 `捕获中` 状态中报告一个活动的视觉源。

### 手动启动和停止

**场景：** 医疗培训模拟应仅在操作阶段使用视觉。

**设置：**

1. 在你的 procedure-start 事件中，获取对 **环境摄像头** 并调用 **开始**.
2. 在你的 procedure-end 事件中，调用 **停止** 同一个组件上的
3. 在调用之前 **开始**，检查 **获取状态** 以避免在事件可能触发多次时重复启动。

**预期行为：** 该组件仅在活动的操作阶段捕获帧。 **获取状态** 返回 `捕获中` 在 **开始** 和 `已停止` 在 **停止**.

**验证：** 仅在操作处于活动状态时，才向角色询问可见对象。离开该阶段后，回复不应引用场景内容。

### 限制捕获 FPS 以降低带宽

**场景：** 企业入职培训模拟运行在受限网络上。较低的捕获频率是可以接受的。

**设置：** 在 **Details** 面板中，设置 **最大 FPS** (`m_MaxFPS`）设为 `5`。或者调用 **设置最大 FPS** 其值为 `5` 在 Blueprint 初始化函数中。

**预期行为：** 聊天机器人读取 `GetMaxFPS()` 并将帧上传节流到大约每 `0.2` 秒。

**验证：** 比较更改前后的响应延迟。 **输出日志** 应继续显示 `SendImage: 正在发送原始图像` ，以降低后的频率。

### 检查是否已注册视觉组件

**场景：** UI 指示器应显示聊天机器人是否具有有效的帧源。

**设置：** 在事件图或控件 Tick 函数中，调用 **支持视觉** 在 `UConvaiChatbotComponent`。使用布尔返回值来驱动指示器。

**预期行为：** **支持视觉** 返回 `true` 当实现 `UConvaiVisionInterface` 的组件已在聊天机器人上注册或可被发现时 `Actor`.

**验证：** 同时调用 **获取状态** 在 **环境摄像头**。仅注册还不足以进行上传；源必须处于 `捕获中` 状态中报告一个活动的视觉源。

### 捕获开始后触发逻辑

**场景：** 角色应仅在 **环境摄像头** 进入 `捕获中`.

**设置：** 绑定 **在帧就绪时** 在 **环境摄像头** 连接到一个自定义事件。使用布尔标志，使逻辑只运行一次。

```
// 蓝图伪代码
bool bSetupComplete = false

OnFrameReady →
  如果未设置 bSetupComplete：
    bSetupComplete = true
    → 触发设置逻辑
```

**预期行为：** 设置逻辑会在第一次 **在帧就绪时** 在组件捕获期间触发的 tick 中运行一次。

**验证：** 确认 **获取状态** 返回 `捕获中` 在自定义逻辑运行之前。

### 在运行时切换视觉组件

**场景：** 同一关卡中的两个角色各自拥有自己的 **环境摄像头**。当控制切换到另一个角色时，活动聊天机器人应使用该角色的帧源。

**设置：** 在切换事件中：

1. 获取目标聊天机器人的 `UConvaiChatbotComponent` 引用。
2. 获取所需的 **环境摄像头** 该角色上的组件引用。
3. 调用 **设置视觉组件** 到聊天机器人上，并传入摄像头组件。

**预期行为：** **设置视觉组件** 返回 `true` 并替换先前注册的源。聊天机器人会在下一个上传 tick 中转发来自新组件的帧。

**验证：** 调用 **支持视觉** 在目标聊天机器人上，并且 **获取状态** 在新摄像头上。询问一个仅对新源可见的对象。

### 下一步

{% content-ref url="/pages/ec5b9bfb145ddc8145050976e8e8db28d33fc076" %}
[视觉 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/dd7a120c7a038befb7a1fe27de94e6b81d28e845" %}
[排查视觉问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/troubleshoot-vision.md)
{% endcontent-ref %}

{% content-ref url="/pages/a5aa237a7b13fb2c8d46ff004c1de14a2c4cda2a" %}
[视觉帧源](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-frame-sources.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-unreal-engine-plugin/features/vision/vision-usage-examples.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.