Image on LabBench, Version 6.0

Image Canvas

Mon, 01 Jan 0001 00:00:00 +0000

ImageCanvas is a lightweight, stateful 2D drawing surface used in LabBench protocols to construct precise and reproducible visual stimuli. It provides an immediate-mode graphics API that separates styling, geometry, text, and image export, allowing complex stimuli to be built procedurally with clear intent. The canvas maintains an internal drawing state that applies consistently across operations and can be exported seamlessly as image data or LabBench assets.

An ImageCanvas can be created with one of the GetCanvas() functions in the Image toolkit. Below is an example, where an ImageCanvas is created to generate and display a visual stimulus for the Stroop Task:

Image Engine

Mon, 01 Jan 0001 00:00:00 +0000

The ImageEngine class provides a fluent, in-memory image processing pipeline for modifying bitmap images using masks, color transformations, and compositing operations. It allows loading an image, selectively replacing or isolating colors, overlaying additional images, and finally exporting the result as a LabBench image asset, all while operating directly on pixel data for efficient, repeatable transformations.

An ImageEngine is created with the GetImageEngine(image) function in the Image toolkit. In the example below, two ImageEngine objects are created; one in the constructor __init__ of the TimeSlotInstruction class that creates image masks that can later be used to replace colors in the image, and one in the Generate() function which is used to inform the operator where to apply a cream and where to perform an assessment:

Image Path

Mon, 01 Jan 0001 00:00:00 +0000

ImagePath represents a mutable vector path used to construct complex geometric shapes, trajectories, and outlines that can later be rendered onto an ImageCanvas. It is a thin, controlled wrapper around Skia’s path primitive, exposed to Python in a way that supports deterministic stimulus construction and safe resource management.

An ImagePath does not draw anything by itself. Instead, it records a sequence of path commands (moves and lines) that define geometry. The completed path is rendered explicitly using ImageCanvas.Draw(path). This makes ImagePath particularly suitable for trajectories, contours, outlines, and stimuli defined algorithmically rather than as simple primitives.

Font Metrics

Mon, 01 Jan 0001 00:00:00 +0000

FontMetrics provides detailed, read-only measurements describing the vertical geometry of the currently active font on an ImageCanvas. These metrics define how text is positioned relative to its baseline and how much vertical space glyphs occupy above and below it.

The metrics reflect the currently selected font and text size and are updated automatically whenever font-related properties change. They are primarily used for precise text layout, vertical alignment, and advanced positioning scenarios where semantic alignment alone is not sufficient.

ImageRectangle

Mon, 01 Jan 0001 00:00:00 +0000

Represents a rectangular region in pixel coordinates, typically returned from drawing operations (e.g. Sprite) to describe the rendered bounds.

Availability:

rect = canvas.Sprite(...)

Properties

Name	Type	Description
`Left`	`float`	Left edge of the rectangle (pixels).
`Top`	`float`	Top edge of the rectangle (pixels).
`Right`	`float`	Right edge of the rectangle (pixels).
`Bottom`	`float`	Bottom edge of the rectangle (pixels).
`Width`	`float`	Width of the rectangle (`Right - Left`).
`Height`	`float`	Height of the rectangle (`Bottom - Top`).
`CenterX`	`float`	Horizontal center of the rectangle.
`CenterY`	`float`	Vertical center of the rectangle.
`TopLeft`	`ImagePoint`	Top-left corner as a point.
`BottomRight`	`ImagePoint`	Bottom-right corner as a point.

Methods

Name	Signature	Description
`ToString`	`ToString() -> str`	Returns a string representation `[left, top, right, bottom] (W=..., H=...)`.

Typical usage example

rect = canvas.Sprite(400, 300, image_bytes, width=200)

# Use geometry for layout or alignment
cx = rect.CenterX
cy = rect.CenterY

canvas.Color("#FF0000")
canvas.Circle(cx, cy, 10)

Notes / gotchas

Coordinates are in canvas pixel space (origin at top-left).
Rectangle values reflect the final rendered position, including alignment and scaling.
Useful for layout calculations after drawing operations (e.g. centering overlays, hit-testing).
Implicit conversion to underlying drawing types is handled internally; not exposed in Python.

ImagePoint

Mon, 01 Jan 0001 00:00:00 +0000

Represents a 2D point in pixel coordinates, typically used for positions, geometry, and layout calculations in drawing operations.

Availability:

point = rect.TopLeft

Properties

Name	Type	Description
`X`	`float`	Horizontal coordinate in pixels.
`Y`	`float`	Vertical coordinate in pixels.

Methods

Name	Signature	Description
`From`	`From(x: float, y: float) -> ImagePoint`	Creates a point from numeric coordinates.
`ToString`	`ToString() -> str`	Returns a string representation `(x, y)`.

Typical usage example

rect = canvas.Sprite(400, 300, image_bytes)

p = rect.TopLeft

canvas.Color("#00FF00")
canvas.Point(p.X, p.Y)

Notes / gotchas

Coordinates are in canvas pixel space (origin at top-left).
Primarily used as a convenience wrapper for geometry returned from other APIs.
Can be constructed directly or obtained from objects such as ImageRectangle.
Internal conversions to underlying drawing types are handled automatically.