> 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-blueprint-reference.md).

# 视觉蓝图参考

Convai Unreal Engine 插件中可通过 Blueprint 访问的视觉接口完整参考。此处项目已根据以下内容验证： `VisionInterface.h`, `ConvaiWebcamBase.h`, `EnvironmentWebcame.h`, `EnvironmentWebcame.cpp`, `ConvaiAudioStreamer.h`，以及 `ConvaiAudioStreamer.cpp`.

随附的帧源是 **环境摄像头** (`UEnvironmentWebcam`）。当前插件中没有单独的物理摄像头组件。

### 枚举

#### EVisionState

声明于 `VisionInterface.h`。描述视觉组件的生命周期状态。

| 值      | 显示名称 | 说明                  |
| ------ | ---- | ------------------- |
| `已停止`  | 已停止  | 视觉系统处于非活动状态。不捕获任何帧。 |
| `启动中`  | 启动中  | 在该枚举中定义。随附实现未设置。    |
| `正在捕获` | 正在捕获 | 视觉系统处于活动状态并正在捕获帧。   |
| `正在停止` | 正在停止 | 在该枚举中定义。随附实现未设置。    |
| `已暂停`  | 已暂停  | 在该枚举中定义。随附实现未设置。    |

在当前随附实现路径中， **环境摄像头** 仅设置 `已停止` 是位于 `正在捕获`.

#### ETextureSourceType

声明于 `VisionInterface.h`。描述由以下项返回的纹理类型： **获取图像纹理**.

| 值                | 显示名称           | 说明                               |
| ---------------- | -------------- | -------------------------------- |
| `Texture2D`      | Texture2D      | 该纹理是一个 `UTexture2D`.             |
| `RenderTarget2D` | RenderTarget2D | 该纹理是一个 `UTextureRenderTarget2D`. |

### UConvaiWebcamBase Blueprint 节点

`UConvaiWebcamBase` 是 Convai 视觉组件的抽象基类。以下所有节点都属于类别 **Convai | Vision**.

#### 开始

在组件上开始捕获。在 `UEnvironmentWebcam`中，这会验证捕获组件和渲染目标，然后将状态设置为 `正在捕获`.

无输入或输出参数。

#### Stop

在组件上停止捕获。在 `UEnvironmentWebcam`这会将状态设置为 `已停止` 并禁用 `CaptureComponent->bCaptureEveryFrame`.

无输入或输出参数。

#### 获取状态

返回当前 `EVisionState` 的组件状态。 `BlueprintPure`.

| 返回  | 类型             | 说明          |
| --- | -------------- | ----------- |
| 返回值 | `EVisionState` | 当前视觉生命周期状态。 |

#### 设置最大 FPS

设置每秒帧数的最大捕获速率。数值 `<= 0` 将被拒绝并记录为错误。

| 参数     | 类型    | 说明          |
| ------ | ----- | ----------- |
| 最大 FPS | `int` | 要应用的最大 FPS。 |

聊天机器人上传路径将有效发送速率限制为 `1`–`60` 在读取 `GetMaxFPS()`.

#### 获取最大 FPS

返回当前的最大 FPS 设置。 `BlueprintPure`.

| 返回  | 类型    | 说明                  |
| --- | ----- | ------------------- |
| 返回值 | `int` | 当前最大 FPS。默认值为 `15`. |

#### 获取最后错误消息

返回组件记录的最后一条错误消息。 `BlueprintPure`.

| 返回  | 类型        | 说明             |
| --- | --------- | -------------- |
| 返回值 | `FString` | 最后一个错误的人类可读描述。 |

#### 获取最后错误代码

返回组件记录的最后一个错误代码。 `BlueprintPure`。初始值为 `-1`.

| 返回  | 类型    | 说明      |
| --- | ----- | ------- |
| 返回值 | `int` | 数值错误代码。 |

#### 获取图像纹理

返回当前帧纹理及其源类型。

| 参数    | 类型                   | 方向 | 说明                                        |
| ----- | -------------------- | -- | ----------------------------------------- |
| 纹理源类型 | `ETextureSourceType` | 输出 | 所返回的纹理是否为 `Texture2D` 或 `RenderTarget2D`. |
| 返回值   | `UTexture*`          | 返回 | 当前帧纹理。                                    |

`CaptureRaw`, `CaptureCompressed`, `GetCompressedData`，以及 `IsCompressedDataAvailable` 是以下内容的一部分： `IConvaiVisionInterface` 但在随附类中并不是 Blueprint 节点。聊天机器人发送路径使用 `CaptureRaw()` 来自 C++。

### UConvaiWebcamBase 事件

#### 帧就绪时

A `BlueprintAssignable` 委托，位于 `UConvaiWebcamBase`。对于 `UEnvironmentWebcam`，它会在以下期间广播： `TickComponent()` 当组件处于 `正在捕获` 并且事件已绑定时。

若只想在第一帧运行逻辑，请在绑定事件内使用布尔标志进行保护。 `FOnFirstFrameCaptured` on `IConvaiVisionInterface` 仅限 C++。

### UEnvironmentWebcam 属性

`UEnvironmentWebcam` 扩展 `UConvaiWebcamBase`。所有属性都属于类别 **Convai | Vision**.

在以下项上声明的自有属性： `UEnvironmentWebcam`:

| 属性                           | 类型                          | 默认值                               | 说明                                                                                                                     |
| ---------------------------- | --------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ConvaiRenderTarget`         | `UTextureRenderTarget2D*`   | `null`                            | 组件渲染到其中的渲染目标。调用前必需： **开始**.                                                                                            |
| `CaptureComponent`           | `USceneCaptureComponent2D*` | 自动创建为 `EnvironmentSceneCapture2D` | 内部场景捕获组件。构造函数设置 `bCaptureEveryFrame = false`, `bCaptureOnMovement = false`，以及 `CaptureSource = SCS_FinalToneCurveHDR`. |
| `bCopyPostProcessProperties` | `bool`                      | `false`                           | 启用后，会从找到的第一个 `APostProcessVolume` 在以下过程中于世界中找到的 `BeginPlay`.                                                           |
| `bAutoStartVision`           | `bool`                      | `false`                           | 当 `true`，调用 **开始** 在以下过程中自动 `BeginPlay`.                                                                               |

继承自 `UConvaiWebcamBase`:

| 属性               | 类型        | 默认值    | 说明                               |
| ---------------- | --------- | ------ | -------------------------------- |
| `标识符`            | `FString` | `""`   | 可选标签。随附运行时路径未使用。                 |
| `m_MaxFPS`       | `int`     | `15`   | 最大捕获 FPS。通过以下方式设置： **设置最大 FPS**. |
| `bUpdateOnFetch` | `bool`    | `true` | 存储在基类上。随附运行时路径未使用。               |

### UEnvironmentWebcam 运行时行为

| 函数                    | 行为                                                                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BeginPlay()`         | 如果 `bCopyPostProcessProperties` 为 `true`则复制后期处理设置，然后调用 **开始** 如果 `bAutoStartVision` 为 `true`.                                                                             |
| `Start()`             | 如果 `CanStart()` 失败，则不更改状态。否则将状态设置为 `正在捕获`，并分配 `ConvaiRenderTarget` 到 `CaptureComponent->TextureTarget` （如有需要），启用 `bCaptureEveryFrame`，并触发 `OnFirstFrameCaptured` （如果已绑定）。 |
| `停止()`                | 如果 `CanStop()` 失败，则不更改状态。否则将状态设置为 `已停止`，并禁用 `bCaptureEveryFrame`，并触发 `OnFramesStopped` （如果已绑定）。                                                                           |
| `CaptureRaw()`        | 从以下对象读取原始 RGBA 字节： `ConvaiRenderTarget` 并返回渲染目标中的宽度和高度。                                                                                                                   |
| `CaptureCompressed()` | 将 `ConvaiRenderTarget` 转换为 JPEG 字节。聊天机器人发送路径使用 `CaptureRaw()`.                                                                                                            |

### 聊天机器人视觉节点

以下节点声明于 `UConvaiAudioStreamer` 并出现在 `UConvaiChatbotComponent` ，通过继承而出现。类别 **Convai | Vision**。它们也被以下项继承： `UConvaiPlayerComponent`，但返回 `false` 在玩家端，因为只有聊天机器人覆盖 `CanUseVision()`.

#### 设置视觉组件

向聊天机器人注册一个视觉组件，替换任何先前注册的组件。

| 参数   | 类型                 | 说明                                     |
| ---- | ------------------ | -------------------------------------- |
| 视觉组件 | `UActorComponent*` | 任何实现以下接口的组件： `UConvaiVisionInterface`. |

| 返回  | 类型     | 说明                                 |
| --- | ------ | ---------------------------------- |
| 返回值 | `bool` | `true` 如果组件实现了该接口并已注册； `false` 否则。 |

#### 支持视觉

返回 `true` 如果已注册有效的视觉组件。若未注册，则搜索其所属的 `Actor` 以查找第一个实现以下接口的组件： `UConvaiVisionInterface`.

| 返回  | 类型     | 说明                                          |
| --- | ------ | ------------------------------------------- |
| 返回值 | `bool` | `true` 当存在有效的 `IConvaiVisionInterface` 组件时。 |

### 项目设置

#### AlwaysAllowVision

`AlwaysAllowVision` 是一个 `配置` 属性，位于 `UConvaiSettings` ，类别为 **Convai** 其带有 `AdvancedDisplay`。打开 **编辑 > 项目设置 > 插件 > Convai** 以更改它。

启用后，初始连接设置将使用连接类型 `视频`，这允许项目在以下之后注册视觉组件： `BeginPlay`.

Blueprint 用户也可以通过以下方式读取该设置： **是否启用始终允许视觉** on `UConvaiUtils` （类别 **Convai | 设置**).

### 下一步

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

{% content-ref url="/pages/afdaa73f8daaacc42144959e698d777a078e46d3" %}
[自定义视觉组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/custom-vision-components.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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-blueprint-reference.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.