视觉调试预览

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

VisionDebugPreview 是一个仅限编辑器的组件，它会将实时摄像头画面渲染为屏幕覆盖层，并显示一个捕获统计面板。可在发布前的开发阶段用它来回答“AI 实际看到了什么？”。Sample Debug Hub 的 视觉 面板会通过确认视觉状态请求和触发实际上已经到达 Convai 来补充它。

添加组件

在任意场景 GameObject 上，点击 Add Component → Convai/Vision/Vision Debug Preview（仅限编辑器）.

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

VisionDebugPreview 按优先级顺序发现帧源：同一 GameObject、子对象、父对象，然后是全场景搜索。请将 Frame Source Component 字段显式指定，以避免在存在多个帧源时产生歧义。

检查器引用

预览设置

字段	类型	默认值	描述
显示预览	bool	true	启用摄像头画面覆盖层。
显示统计	bool	true	启用捕获统计面板。

来源

字段	类型	默认值	描述
Frame Source Component	MonoBehaviour	(自动发现)	要预览的帧源。留空可自动发现。
回退到当前激活的帧源	bool	true	当已分配的源没有纹理时，会在场景中搜索另一个处于活动状态的帧源。适用于源在预览之后才启动的情况。

覆盖层布局

字段	类型	默认值	描述
覆盖层位置	PreviewPosition	右下角	预览固定到 Game 视图哪个角落。可选项： 左上角, 右上角, 左下角, 右下角.
覆盖层宽度	int （160–640）	320	预览宽度（像素）。高度会根据宽高比自动计算。
X 偏移	int （0–200）	10	相对于所选角落的水平内缩（像素）。
Y 偏移	int （0–200）	10	相对于所选角落的垂直内缩（像素）。

调试预览覆盖层位置控制。

宽高比

字段	类型	默认值	描述
使用源宽高比	bool	true	启用后，将从帧源的 FrameDimensions派生宽高比。禁用时，使用 自定义宽高比.
自定义宽高比	float （1–3）	1.778 (16:9)	当 使用源宽高比 被禁用时使用的宽高比。

统计覆盖层

当 显示统计 启用时，会在预览旁边绘制一个文本框。具体输出：

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

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

显示 FPS 和帧指标的统计面板。

IsCapturing 与 IsPublishing: 统计面板显示 IsCapturing ——帧源是否正在生成帧。这与 ConvaiVisionPublisher.IsPublishing不同，后者表示是否有 WebRTC 视频轨道正在发送到 Convai。这两者可以独立检查；某个源可能正在捕获，但发布已暂停或尚未开始。

脚本访问

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

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

使用 Sample Debug Hub 验证视觉请求

VisionDebugPreview 确认帧源正在本地生成帧。它不能确认 Convai 已接收到这些帧，也不能确认特定视觉请求是否得到了答复。请从 Package Manager 导入 口型同步示例 并打开其场景，以测试这条往返流程。该示例会在其 示例调试中心 ，并传入一个 视觉 面板旁实例化一个 上下文 和 情绪 面板。

打开 视觉 面板以访问这些控件：

控制	操作
文本消息 输入 + 发送文本	通过 ConvaiPlayer.SendTextMessage发送一条纯文本消息。先用它来确认角色是否有响应。
视觉提示词 和 响应模式 输入 + 视觉状态	调用 ConvaiRoomManager.RequestVisionStatus()。当 Convai 响应后，结果文本会报告后端的缓冲结果、当前活动源以及帧的年龄。
视觉提示词 和 响应模式 输入 + 视觉触发	调用 ConvaiRoomManager.TriggerVision() 使用提示词文本和已解析的响应模式。结果文本会报告是否附加了帧，以及请求是否被降级。

该 响应模式 输入接受 silent, auto，或 must_respond。在请求发送前，无法识别的值会被拒绝。结果文本随后会显示 无效的响应模式“<value>”——请使用 silent、auto 或 must_respond.

例如，在一次成功触发后，结果文本会显示：

视觉触发：状态=success，结果=frames_available，attach=attached，frames=5，downgraded=False

若只想在不使用 Hub 的情况下进行场景检查，请添加 DynamicVisionContextSceneTool 到任意 GameObject。它通过 IMGUI 覆盖层和等效的上下文菜单命令（发送文本消息, 请求视觉状态, 触发视觉）提供相同的三个操作。LipSync 示例场景还放置了一个视觉目标装置——位于角色前方的彩色道具——供 视觉触发 请求描述。

已知限制

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

下一步

发布策略排查视觉问题