> 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-unity-sdk/features/vision/debug-preview.md).

# Vision 调试预览

`VisionDebugPreview` 是一个仅限编辑器的组件，它将实时摄像头画面渲染为屏幕覆盖层，并显示捕获统计面板。可在发布前的开发阶段用它来回答“AI 实际看到了什么？”。

### 添加该组件

在任意场景 GameObject 上，点击 **添加组件** → **Convai/Vision/Vision 调试预览（仅编辑器）**.

该组件会自动发现场景中的活动帧源。除非存在多个帧源，否则无需显式分配。

{% hint style="info" %}
`VisionDebugPreview` 按优先级发现帧源：同一 GameObject、子对象、父对象，然后是全场景搜索。请显式分配 **帧源组件** 字段，以避免歧义。
{% endhint %}

### 检查器参考

**预览设置**

| 字段         | 类型     | 默认值    | 说明          |
| ---------- | ------ | ------ | ----------- |
| **显示预览**   | `bool` | `true` | 启用摄像头画面覆盖层。 |
| **显示统计信息** | `bool` | `true` | 启用捕获统计面板。   |

**来源**

| 字段          | 类型              | 默认值      | 说明                                         |
| ----------- | --------------- | -------- | ------------------------------------------ |
| **帧源组件**    | `MonoBehaviour` | *（自动发现）* | 要预览的帧源。留空以自动发现。                            |
| **回退到活动帧源** | `bool`          | `true`   | 当分配的源没有纹理时，会在场景中搜索另一个活动帧源。适用于源在预览之后才启动的情况。 |

**覆盖层布局**

| 字段        | 类型              | 默认值   | 说明                                              |
| --------- | --------------- | ----- | ----------------------------------------------- |
| **覆盖层位置** | `预览位置`          | `右下角` | Game 视图中预览锚定的角落。选项： `左上角`, `右上角`, `左下角`, `右下角`. |
| **覆盖层宽度** | `int` （160–640） | `320` | 预览宽度（像素）。高度会根据宽高比自动计算。                          |
| **X 偏移**  | `int` （0–200）   | `10`  | 相对于所选角落的水平内边距（像素）。                              |
| **Y 偏移**  | `int` （0–200）   | `10`  | 相对于所选角落的垂直内边距（像素）。                              |

<figure><img src="/files/909efd2cfbd8e5bd85928e048668544d665e6c2b" alt="Debug preview overlay positioning controls in the Inspector"><figcaption><p>调试预览覆盖层定位控件。</p></figcaption></figure>

**宽高比**

| 字段         | 类型            | 默认值            | 说明                                                   |
| ---------- | ------------- | -------------- | ---------------------------------------------------- |
| **使用源宽高比** | `bool`        | `true`         | 启用时，将从帧源的 `FrameDimensions`中推导宽高比。禁用时，使用 **自定义宽高比**. |
| **自定义宽高比** | `float` （1–3） | `1.778` (16:9) | 启用时使用的宽高比 **使用源宽高比** 被禁用时，用于计算覆盖层高度的宽高比。             |

### 统计覆盖层

当 **显示统计信息** 启用时，会在预览旁边绘制一个文本框。确切输出：

```
视觉捕获调试
状态：正在捕获
源：ConvaiVisionRoot/ConvaiVisionRoot [camera] (CameraVisionFrameSource)
分辨率：1280x720
FPS：14.9（目标：15）
帧数：447
```

| 行               | 来源                              | 说明                                |
| --------------- | ------------------------------- | --------------------------------- |
| `状态：正在捕获 / 已停止` | `IsCapturing` 帧源上的              | 布尔字符串——不是 `VisionSourceState` 枚举。 |
| `源：...`         | 层级路径 + SourceId + 类型名称          | 从场景根节点开始的完整路径，用于消歧。               |
| `分辨率：宽x高`       | `FrameDimensions`               | `(0, 0)` 在捕获开始之前。                 |
| `FPS：X.X（目标：Y）` | 按 0.5 秒间隔测量 + `TargetFrameRate` | 测得的 FPS 每 0.5 秒更新一次。              |
| `帧数：N`          | `FrameCount`                    | 自捕获开始以来的累计总数。                     |

<figure><img src="/files/efb0ea40846e0570464bc740db8e18dcac0fc59e" alt="Statistics panel showing FPS and frame metrics in the Vision Debug Preview overlay"><figcaption><p>显示 FPS 和帧指标的统计面板。</p></figcaption></figure>

{% hint style="warning" %}
**`IsCapturing` 与 `IsPublishing`:** 统计面板显示 `IsCapturing` ——表示帧源是否正在生成帧。这与 `ConvaiVisionPublisher.IsPublishing`不同，后者表示是否有 WebRTC 视频轨道正在主动发送到 Convai。两者可独立检查；某个源可能正在捕获，而发布已暂停或尚未开始。
{% endhint %}

### 脚本访问

这些属性可从其他脚本中读取：

| 属性            | 类型      | 说明                     |
| ------------- | ------- | ---------------------- |
| `ShowPreview` | `bool`  | 获取或设置预览覆盖层是否可见。        |
| `ShowStats`   | `bool`  | 获取或设置统计面板是否可见。         |
| `CurrentFps`  | `float` | 测得的捕获 FPS，每 0.5 秒更新一次。 |
| `FrameCount`  | `long`  | 当前帧源的累计帧数。             |
| `IsCapturing` | `bool`  | 当前帧源是否正在捕获。            |

### 已知限制

* 仅限编辑器。 `VisionDebugPreview` 调用 `enabled = false` 在 `Awake()` 在非编辑器构建中。已发布构建中没有运行时开销。
* 在 WebGL 上，覆盖层为空白，因为 `ConvaiVisionPublisher` 绕过帧源并直接使用 `canvas.captureStream()` 。没有 `RenderTexture` 可显示。通过 `IsPublishing` 代替。
* 覆盖层通过 `OnGUI` （IMGUI）渲染。无法用 UGUI 定位，也无法在世界空间中渲染。
* 每个 `VisionDebugPreview` 组件只会绘制一个统计面板。如果需要并排比较两个帧源，请添加多个组件。

### 下一步

{% content-ref url="/pages/b15c237537e3521d8e360ca90de5e9b15be340ec" %}
[发布策略](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/publishing-and-policies.md)
{% endcontent-ref %}

{% content-ref url="/pages/86612bc613c5a299a468b71b3fb8a40e625ee1fe" %}
[排查 Vision 问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.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-unity-sdk/features/vision/debug-preview.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.