> 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).

# 视觉调试预览

使用 Unity Editor 调试工具验证视觉摄像机画面，并确认视觉状态请求和触发器已到达 Convai。

`VisionDebugPreview` 是一个仅限编辑器使用的组件，可将实时摄像头画面渲染为屏幕叠加层，并显示采集统计信息面板。在开发期间、正式发布之前，使用它来回答“AI 实际看到了什么？” Sample Debug Hub 的 **Vision** 面板可与其配合使用，确认视觉状态请求和触发器确实已到达 Convai。

### 添加组件

在任意场景游戏对象上，点击 **添加组件** → **Convai/Vision/Vision Debug Preview (Editor Only)**.

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

{% hint style="info" %}
`VisionDebugPreview` 会按优先级顺序发现帧源：同一游戏对象、子对象、父对象，然后在整个场景中搜索。存在多个帧源时，请显式指定 **帧源组件** 字段，以避免产生歧义。
{% endhint %}

### Inspector 参考

**预览设置**

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

**来源**

| 字段          | 类型              | 默认值      | 说明                                             |
| ----------- | --------------- | -------- | ---------------------------------------------- |
| **帧源组件**    | `MonoBehaviour` | *（自动发现）* | 要预览的帧源。留空则自动发现。                                |
| **回退到活动帧源** | `bool`          | `true`   | 当指定的源没有纹理时，会在场景中搜索其他活动帧源。如果源在预览启动后才启动，此选项会很有用。 |

**叠加层布局**

| 字段        | 类型                | 默认值           | 说明                                                                    |
| --------- | ----------------- | ------------- | --------------------------------------------------------------------- |
| **叠加层位置** | `PreviewPosition` | `BottomRight` | 预览在游戏视图中锚定的角落。选项： `TopLeft`, `TopRight`, `BottomLeft`, `BottomRight`. |
| **叠加层宽度** | `int` （160–640）   | `320`         | 预览宽度（像素）。高度会根据宽高比自动计算。                                                |
| **X 偏移**  | `int` （0–200）     | `10`          | 相对于所选角落的水平内缩量（像素）。                                                    |
| **Y 偏移**  | `int` （0–200）     | `10`          | 相对于所选角落的垂直内缩量（像素）。                                                    |

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Ft5AyxDxkoyD5skspgECG%2Fimage.png?alt=media&amp;token=4707ffc6-1b10-4354-9ac6-354a1e6ac32e" alt="Debug preview overlay positioning controls in the Inspector"><figcaption><p>调试预览叠加层的位置控制项。</p></figcaption></figure>

**宽高比**

| 字段         | 类型            | 默认值            | 说明                                             |
| ---------- | ------------- | -------------- | ---------------------------------------------- |
| **使用源宽高比** | `bool`        | `true`         | 启用后，根据帧源的 `FrameDimensions`。禁用时，使用 **自定义宽高比**. |
| **自定义宽高比** | `float` （1–3） | `1.778` (16:9) | 用于 **使用源宽高比** 处于禁用状态时的宽高比。                     |

### 统计信息叠加层

当 **显示统计信息** 启用时，预览画面旁边会显示一个文本框。具体内容如下：

```
Vision Capture Debug
Status: Capturing
Source: ConvaiVisionRoot/ConvaiVisionRoot [camera] (CameraVisionFrameSource)
Resolution: 1280x720
FPS: 14.9 (target: 15)
Frames: 447
```

| 行                             | 来源                              | 备注                                 |
| ----------------------------- | ------------------------------- | ---------------------------------- |
| `Status: Capturing / Stopped` | `IsCapturing` 帧源上的              | 布尔值字符串——不是 `VisionSourceState` 枚举。 |
| `Source: ...`                 | 层级路径 + SourceId + 类型名称          | 从场景根节点开始的完整路径，用于消除歧义。              |
| `Resolution: WxH`             | `FrameDimensions`               | `(0, 0)` 捕获开始前。                    |
| `FPS: X.X (target: Y)`        | 按 0.5 秒间隔测量 + `TargetFrameRate` | 测得的 FPS 每 0.5 秒更新一次。               |
| `Frames: N`                   | `FrameCount`                    | 自开始捕获以来的累计总数。                      |

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FIGx16w1tGysCNKWIiSVJ%2Fimage.png?alt=media&amp;token=786e43d4-ceaf-49ec-825c-a9a13f6df15f" 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`  | 当前帧源是否正在捕获。            |

### 使用 Sample Debug Hub 验证视觉请求

`VisionDebugPreview` 可确认帧源正在本地生成帧，但无法确认 Convai 是否收到了这些帧，也无法确认视觉专属请求是否得到了响应。请从 Package Manager 导入 **LipSync Sample** 并打开其中的场景，以测试这一完整流程。该示例会实例化一个 **Sample Debug Hub** ，其中包含一个 **Vision** 面板，以及 **Context** 和 **Emotion** 面板。

打开 **Vision** 面板以访问以下控件：

| 控件                                 | 动作                                                                                     |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| **文本消息** 输入框 + **发送文本**            | 通过 `ConvaiPlayer.SendTextMessage`发送纯文本消息。首先使用此功能，确认角色是否会响应。                            |
| **视觉提示** 和 **响应模式** 输入框 + **视觉状态** | 调用 `ConvaiRoomManager.RequestVisionStatus()`。Convai 响应后，结果文本会报告后端的缓冲区处理结果、当前活动源以及帧的时效。 |
| **视觉提示** 和 **响应模式** 输入框 + **触发视觉** | 调用 `ConvaiRoomManager.TriggerVision()` ，并传入提示文本和解析后的响应模式。结果文本会报告是否附加了帧，以及请求是否被降级处理。    |

“ **响应模式** ”输入框接受 `silent`, `auto`，或 `must_respond`。无法识别的值会在发送请求前被拒绝。此时结果文本为 `Invalid respond mode '<value>' — use silent, auto or must_respond`.

例如，触发成功后，结果文本如下：

```
Vision trigger: status=success, outcome=frames_available, attach=attached, frames=5, downgraded=False
```

如需在没有 hub 的情况下仅检查场景，请将 `DynamicVisionContextSceneTool` 添加到任意 GameObject。它通过 IMGUI 覆盖层和对应的上下文菜单命令提供相同的三个操作（**发送文本消息**, **请求视觉状态**, **触发视觉**）。LipSync 示例场景还放置了一个视觉目标装置——角色前方的彩色道具——供 **视觉触发** 请求描述。

### 已知限制

* 仅限编辑器。 `VisionDebugPreview` 会在非编辑器版本的 `Awake()` 中调用 `enabled = false` 。已发布的版本不会产生运行时开销。
* 在 WebGL 上，覆盖层为空白，因为 `ConvaiVisionPublisher` 会绕过帧源，直接使用 `canvas.captureStream()` 。没有可供显示的 `RenderTexture` 。请改用 `IsPublishing` 验证流。
* 覆盖层通过 `OnGUI` （IMGUI）渲染。它无法通过 UGUI 定位，也无法在世界空间中渲染。
* 每个 `VisionDebugPreview` 组件只会绘制一个统计信息面板。如需并排比较两个帧源，请添加多个组件。
* `VisionContextDebugPanel` 和 `DynamicVisionContextSceneTool` 是位于 `SamplesShared/`下的示例专用组件。它们不属于运行时 SDK，除非导入并保留该示例，否则不会包含在已发布版本中。

### 后续步骤

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

{% content-ref url="/pages/86612bc613c5a299a468b71b3fb8a40e625ee1fe" %}
[排查视觉问题](https://docs.convai.com/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 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-unity-sdk/features/vision/debug-preview.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.
