bec_widgets.widgets.plots.roi.image_roi

Classes

BaseROI	Base class for all Region of Interest (ROI) implementations.
CircularROI	Circular Region of Interest with center/diameter tracking and auto-labeling.
EllipticalROI	Elliptical Region of Interest with centre/width/height tracking and auto-labelling.
LabelAdorner	Manages a TextItem label on top of any ROI, keeping it aligned.
ROIController	Manages a collection of ROIs (Regions of Interest) with palette-assigned colors.
RectangularROI	Defines a rectangular Region of Interest (ROI) with additional functionality.

Module Contents

class BaseROI(*, config: bec_widgets.utils.ConnectionConfig | None = None, gui_id: str | None = None, parent_image: bec_widgets.widgets.plots.image.image.Image | None, label: str | None = None, line_color: str | None = None, line_width: int = 5, movable: bool = True, **pg_kwargs)

Bases: bec_widgets.utils.BECConnector

Base class for all Region of Interest (ROI) implementations.

This class serves as a mixin that provides common properties and methods for ROIs, including name, line color, and line width properties. It inherits from BECConnector to enable remote procedure call functionality.

RPC

Flag indicating if remote procedure calls are enabled.

Type:

bool

PLUGIN

Flag indicating if this class is a plugin.

Type:

bool

nameChanged

Signal emitted when the ROI name changes.

Type:

Signal

penChanged

Signal emitted when the ROI pen (color/width) changes.

Type:

Signal

USER_ACCESS

List of methods and properties accessible via RPC.

Type:

list

Base class for all modular ROIs.

Parameters:

• label (str) – Human-readable name shown in ROI Manager and labels.

• line_color (str | None, optional) – Initial pen color. Defaults to None. Controller may override color later.

• line_width (int, optional) – Initial pen width. Defaults to 15. Controller may override width later.

• config (ConnectionConfig | None, optional) – Standard BECConnector argument. Defaults to None.

• gui_id (str | None, optional) – Standard BECConnector argument. Defaults to None.

• parent_image (BECConnector | None, optional) – Standard BECConnector argument. Defaults to None.

add_scale_handle()

Add scale handles to the ROI.

abstractmethod get_coordinates()

Gets the coordinates that define this ROI’s position and shape.

This is an abstract method that must be implemented by subclasses. Implementations should return either a dictionary with descriptive keys or a tuple of coordinates, depending on the value of self.description.

Returns:

The coordinates defining the ROI’s position and shape.

Return type:

dict or tuple

Raises:

NotImplementedError – This method must be implemented by subclasses.

get_data_from_image(image_item: pyqtgraph.ImageItem | None = None, returnMappedCoords: bool = False, **kwargs)

Wrapper around pyqtgraph.ROI.getArrayRegion.

Parameters:

• image_item (pg.ImageItem or None) – The ImageItem to sample. If None, auto-detects the first ImageItem in the same GraphicsScene as this ROI.

• returnMappedCoords (bool) – If True, also returns the coordinate array generated by getArrayRegion.

• **kwargs – Additional keyword arguments passed to getArrayRegion or affineSlice, such as axes, order, shape, etc.

Returns:

Pixel data inside the ROI, or (data, coords) if returnMappedCoords is True.

Return type:

ndarray

parent()

Gets the parent image associated with this ROI.

Returns:

The parent image object, or None if no parent is set.

Return type:

Image

remove()

Cleanup the BECConnector

remove_scale_handles()

Remove all scale handles from the ROI.

set_parent(parent: bec_widgets.widgets.plots.image.image.Image)

Sets the parent image for this ROI.

Parameters:

parent (Image) – The parent image object to associate with this ROI.

set_position(x: float, y: float)

Sets the position of the ROI.

Parameters:

• x (float) – The x-coordinate of the new position.

• y (float) – The y-coordinate of the new position.

PLUGIN = False

RPC = True

USER_ACCESS = ['label', 'label.setter', 'movable', 'movable.setter', 'line_color', 'line_color.setter',...

config = None

property description: bool

Gets whether ROI coordinates should be emitted with descriptive keys by default.

Returns:

True if coordinates should include descriptive keys, False otherwise.

Return type:

bool

property label: str

Gets the display name of this ROI.

Returns:

The current name of the ROI.

Return type:

str

property line_color: str

Gets the current line color of the ROI.

Returns:

The current line color as a string (e.g., hex color code).

Return type:

str

property line_width: int

Gets the current line width of the ROI.

Returns:

The current line width in pixels.

Return type:

int

property movable: bool

Gets whether this ROI is movable.

Returns:

True if the ROI can be moved, False otherwise.

Return type:

bool

movableChanged

nameChanged

parent_plot_item

penChanged

class CircularROI(*, pos, size, pen=None, config: bec_widgets.utils.ConnectionConfig | None = None, gui_id: str | None = None, parent_image: bec_widgets.widgets.plots.image.image.Image | None = None, label: str | None = None, line_color: str | None = None, line_width: int = 5, movable: bool = True, **extra_pg)

Bases: BaseROI, pyqtgraph.CircleROI

Circular Region of Interest with center/diameter tracking and auto-labeling.

This class extends the BaseROI and pg.CircleROI classes to provide a circular ROI that emits signals when its center or diameter changes, and includes an auto-aligning label for visual identification.

centerChanged

Signal emitted when the ROI center or diameter changes, providing the new (center_x, center_y, diameter) values.

Type:

Signal

centerReleased

Signal emitted when the ROI is released after dragging, providing the final (center_x, center_y, diameter) values.

Type:

Signal

Initializes a circular ROI with the specified properties.

Creates a circular ROI at the given position and with the given size, connects signals for tracking changes, and attaches an auto-aligning label.

Parameters:

• pos – Initial position of the ROI as [x, y].

• size – Initial size of the ROI as [diameter, diameter].

• pen – Defines the border appearance; can be color or style.

• config (ConnectionConfig | None, optional) – Configuration for BECConnector. Defaults to None.

• gui_id (str | None, optional) – Identifier for the GUI element. Defaults to None.

• parent_image (BECConnector | None, optional) – Parent image object. Defaults to None.

• label (str | None, optional) – Display name for the ROI. Defaults to None.

• line_color (str | None, optional) – Color of the ROI outline. Defaults to None.

• line_width (int, optional) – Width of the ROI outline in pixels. Defaults to 3.

• parent_plot_item – The plot item this ROI belongs to.

• **extra_pg – Additional keyword arguments for pg.CircleROI.

_lookup_scene_image() → pyqtgraph.ImageItem | None

Retrieves an image from the scene items if available.

Iterates over all items in the scene and checks if any of them are of type pg.ImageItem and have a non-None image. If such an item is found, its image is returned.

Returns:

The first found ImageItem with a non-None image, or None if no suitable image is found.

Return type:

pg.ImageItem or None

_on_region_changed()

Handles ROI region change events.

This method is called whenever the ROI’s position or size changes. It calculates the center coordinates and diameter of the circle and emits the centerChanged signal with these values.

add_scale_handle()

Adds scale handles to the circular ROI.

get_coordinates(typed: bool | None = None) → dict | tuple

Calculates and returns the coordinates and size of an object, either as a typed dictionary or as a tuple.

Parameters:

typed (bool | None) – If True, returns coordinates as a dictionary. Defaults to None, which utilizes the object’s description value.

Returns:

A dictionary with keys ‘center_x’, ‘center_y’, ‘diameter’, and ‘radius’

if typed is True.

tuple: A tuple containing (center_x, center_y, diameter, radius) if typed is False.

Return type:

dict

mouseDragEvent(ev)

Handles mouse drag events on the ROI.

This method extends the parent class implementation to emit the centerReleased signal when the mouse drag is finished, providing the final center coordinates and diameter of the circular ROI.

Parameters:

ev – The mouse event object containing information about the drag operation.

centerChanged

centerReleased

handleHoverPen

hoverPen

class EllipticalROI(*, pos, size, pen=None, config: bec_widgets.utils.ConnectionConfig | None = None, gui_id: str | None = None, parent_image: bec_widgets.widgets.plots.image.image.Image | None = None, label: str | None = None, line_color: str | None = None, line_width: int = 5, movable: bool = True, **extra_pg)

Bases: BaseROI, pyqtgraph.EllipseROI

Elliptical Region of Interest with centre/width/height tracking and auto-labelling.

Mirrors the behaviour of CircularROI but supports independent horizontal and vertical radii.

Base class for all modular ROIs.

Parameters:

• label (str) – Human-readable name shown in ROI Manager and labels.

• line_color (str | None, optional) – Initial pen color. Defaults to None. Controller may override color later.

• line_width (int, optional) – Initial pen width. Defaults to 15. Controller may override width later.

• config (ConnectionConfig | None, optional) – Standard BECConnector argument. Defaults to None.

• gui_id (str | None, optional) – Standard BECConnector argument. Defaults to None.

• parent_image (BECConnector | None, optional) – Standard BECConnector argument. Defaults to None.

_on_region_changed()

add_scale_handle()

Add scale handles to the elliptical ROI.

get_coordinates(typed: bool | None = None) → dict | tuple

Return the ellipse’s centre and size.

Parameters:

typed (bool | None) – If True returns dict; otherwise tuple.

mouseDragEvent(ev)

centerChanged

centerReleased

handleHoverPen

hoverPen

class LabelAdorner(roi: BaseROI, anchor: tuple[int, int] = (0, 1), padding: int = 2, bg_color: str | tuple[int, int, int, int] = (0, 0, 0, 100), text_color: str | tuple[int, int, int, int] = 'white')

Manages a TextItem label on top of any ROI, keeping it aligned.

Initializes a label overlay for a given region of interest (ROI), allowing for customization of text placement, padding, background color, and text color. Automatically attaches the label to the ROI and updates its position and content based on ROI changes.

Parameters:

• roi – The region of interest to which the label will be attached.

• anchor – Tuple specifying the label’s anchor relative to the ROI. Default is (0, 1).

• padding – Integer specifying the padding around the label’s text. Default is 2.

• bg_color – RGBA tuple for the label’s background color. Default is (0, 0, 0, 100).

• text_color – String specifying the color of the label’s text. Default is “white”.

_reposition()

Repositions the label to align with the ROI’s current position.

This method is called whenever the ROI’s position or size changes. It places the label at the bottom-left corner of the ROI’s bounding rectangle.

_update_html(text: str)

Updates the HTML content of the label with the given text.

Creates an HTML div with the configured background color, text color, and padding, then sets this HTML as the content of the label.

Parameters:

text (str) – The text to display in the label.

bg_rgba = (0, 0, 0, 100)

label

padding = 2

roi

text_color = 'white'

class ROIController(colormap='viridis')

Bases: qtpy.QtCore.QObject

Manages a collection of ROIs (Regions of Interest) with palette-assigned colors.

Handles creating, adding, removing, and managing ROI instances. Supports color assignment from a colormap, and provides utility methods to access and manipulate ROIs.

roiAdded

Emits the new ROI instance when added.

Type:

Signal

roiRemoved

Emits the removed ROI instance when deleted.

Type:

Signal

cleared

Emits when all ROIs are removed.

Type:

Signal

paletteChanged

Emits the new colormap name when updated.

Type:

Signal

_colormap

Name of the colormap used for ROI colors.

Type:

str

_rois

Internal list storing currently managed ROIs.

Type:

list[BaseROI]

_colors

Internal list of colors for the ROIs.

Type:

list[str]

Initializes the ROI controller with the specified colormap.

Sets up internal data structures for managing ROIs and their colors.

Parameters:

colormap (str, optional) – The name of the colormap to use for ROI colors. Defaults to “viridis”.

_rebuild_color_buffer()

Regenerates the color buffer for ROIs.

This internal method creates a new list of colors based on the current colormap and the number of ROIs. It ensures there’s always one more color than the number of ROIs to allow for adding a new ROI without regenerating the colors.

add_roi(roi: BaseROI)

Registers an externally created ROI with this controller.

Adds the ROI to the internal list, assigns it a color from the color buffer, ensures it has an appropriate line width, and emits the roiAdded signal.

Parameters:

roi (BaseROI) – The ROI instance to register. Can be any subclass of BaseROI, such as RectangularROI or CircularROI.

cleanup()

clear()

Removes all ROIs from this controller.

Iterates through all ROIs and removes them one by one, then emits the cleared signal to notify listeners that all ROIs have been removed.

colormap()

Gets the name of the colormap used for ROI colors.

Returns:

The name of the colormap.

Return type:

str

get_roi(index: int) → BaseROI | None

Returns the ROI at the specified index.

Parameters:

index (int) – The index of the ROI to retrieve.

Returns:

The ROI at the specified index, or None if the index

is out of range.

Return type:

BaseROI or None

get_roi_by_name(name: str) → BaseROI | None

Returns the first ROI with the specified name.

Parameters:

name (str) – The name to search for (case-sensitive).

Returns:

The first ROI with a matching name, or None if no

matching ROI is found.

Return type:

BaseROI or None

remove_roi(roi: BaseROI)

Removes an ROI from this controller.

If the ROI is found in the internal list, it is removed, the color buffer is regenerated, and the roiRemoved signal is emitted.

Parameters:

roi (BaseROI) – The ROI instance to remove.

remove_roi_by_index(index: int)

Removes the ROI at the specified index.

Parameters:

index (int) – The index of the ROI to remove.

remove_roi_by_name(name: str)

Removes the first ROI with the specified name.

Parameters:

name (str) – The name of the ROI to remove (case-sensitive).

renormalize_colors()

Reassigns palette colors to all ROIs in order.

Regenerates the color buffer based on the current colormap and number of ROIs, then assigns each ROI a color from the buffer in the order they were added. This is useful after changing the colormap or when ROIs need to be visually distinguished from each other.

set_colormap(cmap: str)

cleared

paletteChanged

roiAdded

roiRemoved

property rois: list[BaseROI]

Gets a copy of the list of ROIs managed by this controller.

Returns a new list containing all the ROIs currently managed by this controller. The list is a copy, so modifying it won’t affect the controller’s internal list.

Returns:

A list of all ROIs currently managed by this controller.

Return type:

list[BaseROI]

class RectangularROI(*, pos: tuple[float, float], size: tuple[float, float], pen=None, config: bec_widgets.utils.ConnectionConfig | None = None, gui_id: str | None = None, parent_image: bec_widgets.widgets.plots.image.image.Image | None = None, label: str | None = None, line_color: str | None = None, line_width: int = 5, movable: bool = True, resize_handles: bool = True, **extra_pg)

Bases: BaseROI, pyqtgraph.RectROI

Defines a rectangular Region of Interest (ROI) with additional functionality.

Provides tools for manipulating and extracting data from rectangular areas on images, includes support for GUI features and event-driven signaling.

edgesChanged

Signal emitted when the ROI edges change, providing the new (“top_left”, “top_right”, “bottom_left”,”bottom_right”) coordinates.

Type:

Signal

edgesReleased

Signal emitted when the ROI edges are released, providing the new (“top_left”, “top_right”, “bottom_left”,”bottom_right”) coordinates.

Type:

Signal

Initializes an instance with properties for defining a rectangular ROI with handles, configurations, and an auto-aligning label. Also connects a signal for region updates.

Parameters:

• pos – Initial position of the ROI.

• size – Initial size of the ROI.

• pen – Defines the border appearance; can be color or style.

• config – Optional configuration details for the connection.

• gui_id – Optional identifier for the associated GUI element.

• parent_image – Optional parent object the ROI is related to.

• label – Optional label for identification within the context.

• line_color – Optional color of the ROI outline.

• line_width – Width of the ROI’s outline in pixels.

• parent_plot_item – The plot item this ROI belongs to.

• **extra_pg – Additional keyword arguments specific to pg.RectROI.

_lookup_scene_image()

Searches for an image in the current scene.

This helper method iterates through all items in the scene and returns the first pg.ImageItem that has a non-None image property.

Returns:

The image from the first found ImageItem, or None if no suitable image is found.

Return type:

numpy.ndarray or None

_normalized_edges() → tuple[float, float, float, float]

Return rectangle edges as (left, bottom, right, top) with consistent ordering even when the ROI has been inverted by its scale handles.

Returns:

A tuple containing the left, bottom, right, and top edges

of the ROI rectangle in normalized coordinates.

Return type:

tuple

_on_region_changed()

Handles changes to the ROI’s region.

This method is called whenever the ROI’s position or size changes. It calculates the new corner coordinates and emits the edgesChanged signal with the updated coordinates.

add_scale_handle()

Add scale handles at every corner and edge of the ROI.

Corner handles are anchored to the centre for two-axis scaling. Edge handles are anchored to the midpoint of the opposite edge for single-axis scaling.

get_coordinates(typed: bool | None = None) → dict | tuple

Returns the coordinates of a rectangle’s corners, rectangle center and dimensions. Supports returning them as either a dictionary with descriptive keys or a tuple of coordinates.

Parameters:

typed (bool | None) – If True, returns coordinates as a dictionary with descriptive keys. If False, returns them as a tuple. Defaults to the value of self.description.

Returns:

The rectangle’s corner coordinates, rectangle center and dimensions, where the format

depends on the typed parameter.

Return type:

dict | tuple

mouseDragEvent(ev)

Handles mouse drag events on the ROI.

This method extends the parent class implementation to emit the edgesReleased signal when the mouse drag is finished, providing the final coordinates of the ROI.

Parameters:

ev – The mouse event object containing information about the drag operation.

adorner

edgesChanged

edgesReleased

handleHoverPen

hoverPen