Debug Preview

Verify Vision capture in the Unity Editor with a live overlay showing the active frame source, capture statistics, and source state.

Visualising Vision Capture with Debug Preview

VisionDebugPreview renders the active frame source's output as an on-screen overlay inside the Unity Editor, giving you immediate visual confirmation that capture is working correctly. It also displays a live statistics panel showing frame rate, total frame count, and source state. Because this component is designed for development use, it automatically disables itself in player builds — it has zero runtime cost when you ship your project.

Adding Debug Preview to Your Scene

1

Add the Component

Select any GameObject in the scene — the same one as your frame source, or a dedicated debug object. Click Add ComponentConvai/Vision/Vision Debug Preview (Editor Only).

2

Assign a Frame Source (Optional)

In the Frame Source Component field, drag in the IVisionFrameSource component you want to preview. If you leave this blank and Fallback to Active Frame Source is enabled, the component automatically selects the first capturing source in the scene.

3

Enter Play Mode

Press Play. An overlay appears in the Game view showing the live texture and a statistics panel. Adjust position and size using the Inspector fields described below.


Inspector Reference

Frame Source

Field
Type
Default
Description

Frame Source Component

MonoBehaviour

(auto-resolved)

The frame source to preview. Leave blank to use fallback auto-discovery.

Fallback to Active Frame Source

bool

true

When the assigned source is idle or unassigned, automatically find and display the first actively capturing source in the scene.

Overlay Layout

Field
Type
Default
Description

Overlay Position

PreviewPosition

BottomRight

Corner of the Game view where the overlay is anchored.

Overlay Width

int (160–640)

320

Width of the preview overlay in pixels.

Offset X

int (0–200)

10

Horizontal distance in pixels between the overlay edge and the screen edge.

Offset Y

int (0–200)

10

Vertical distance in pixels between the overlay edge and the screen edge.

Aspect Ratio

Field
Type
Default
Description

Use Source Aspect Ratio

bool

true

Derives the overlay height from the frame source's actual capture dimensions.

Custom Aspect Ratio

float (1–3)

1.778 (16:9)

The aspect ratio used to calculate overlay height when Use Source Aspect Ratio is disabled.

Preview Settings

Field
Type
Default
Description

Show Preview

bool

true

Enables or disables the image overlay. Can be toggled at runtime.

Show Stats

bool

true

Enables or disables the statistics overlay. Can be toggled at runtime.

PreviewPosition Values

Value
Overlay anchor

TopLeft

Upper-left corner of the Game view

TopRight

Upper-right corner

BottomLeft

Lower-left corner

BottomRight

Lower-right corner (default)


Statistics Overlay

When Show Stats is enabled, the overlay displays the following live values:

Statistic
Description

FPS

Frames per second currently being produced by the frame source

Frame count

Total frames captured since capture started

State

Current VisionSourceState of the frame source (e.g., Ready, Degraded)

Dimensions

Capture resolution in pixels


Runtime Scripting

VisionDebugPreview exposes a small scripting API for toggling the overlay and reading current statistics:


Known Limitations

If no frame source is active and Fallback to Active Frame Source is false, the overlay shows a placeholder indicating that no capturing source was found. Enable fallback or assign the frame source explicitly to resolve this.


Conclusion

VisionDebugPreview gives you a live view of exactly what the character sees, along with capture statistics, at zero cost to your production build. Use it throughout development to verify frame source health, confirm capture is running at the expected frame rate, and catch issues before they reach players. For worked implementation examples, see Usage Examples. For production scripting patterns, see Advanced Topics.

Last updated

Was this helpful?