radioviz.tools.region_tool

Region tool module for radioviz application.

This module provides functionality for selecting regions of interest in images, calculating statistics for those regions, and displaying histograms of the selected regions. It includes tools for rectangle, circle, ellipse, and polygon selection types, along with associated UI components and data management.

The module defines controllers, views, models, and utility functions for handling region selection and analysis operations within the radioviz application framework.

Typical Workflow for Region Creation: 1. User clicks “Add Region” button in the tool dock and selects a region type 2. A RegionSelectionDialog appears with options for region type, rotation, and enclosure 3. The RegionToolController creates a RegionToolSession with an ImageWindowController 4. A RegionSelector is initialized on the image canvas based on the selected region type 5. User performs selection on the image canvas (drag for rectangles/ellipses, click for polygons) 6. Once valid selection is made, the RegionSelectionDialog enables the “Done” button 7. User clicks “Done” which triggers RegionToolSession.start_region_computation() 8. A worker is created in a separate thread to compute statistics 9. The worker calculates histogram, mean, std dev, min, max, and area values 10. Results are returned to the RegionToolSession which finalizes the region creation 11. The new RegionData is added to the item store and displayed in the table

Typical Workflow for Region Removal: 1. User selects a region in the table view 2. User clicks the “Delete Region” button 3. RegionToolController.on_delete_clicked() is called 4. The selected RegionData is passed to RegionToolController.remove_item() 5. The item is marked as being removed to prevent re-entrancy 6. Associated overlay elements are removed from the image canvas 7. If a RegionWindowController exists, it is closed 8. The RegionData is removed from the item store

Typical Workflow for Workspace Serialization: 1. The to_workspace method is called to generate a workspace specification. 2. A ToolWorkspace object is created, capturing the current state and items of the tool. 3. The workspace specification includes optional data based on the include_data parameter. 4. The current selected item and all items in the item store are serialized into the workspace.

Typical Workflow for Workspace Restoration: 1. The from_workspace method is invoked with a ToolWorkspace specification. 2. The tool’s state is reconstructed using the workspace specification. 3. Each item in the specification is restored, resolving references using the provided context. 4. The item store is reordered based on the order specified in the workspace. 5. The selected item is restored to match the workspace state.

Key Actors: - ToolDockWidget: Provides UI controls and manages table interactions - RegionToolController: Coordinates between UI and backend logic - RegionSelectionDialog: Handles user configuration of region parameters - RegionToolSession: Manages the lifecycle of a region selection operation - RegionSelector: Handles the actual selection on the image canvas - RegionData: Stores region information and statistics - RegionWindowController: Manages the region detail window

Module Attributes

`region_type_icons`	Dictionary mapping region types to their corresponding icons.
`RegionStore`	Type alias for ItemStore with RegionData elements.

Functions

`assume_complete_region`(region)	Treat a region as complete without runtime checks.
`calculate_histogram`(request)
`draw_highlight_region_overlay`(overlay, axes)	Draw a highlighted region overlay.
`draw_permanent_region_overlay`(overlay, axes)	Draw a permanent region overlay.
`draw_region_label`(overlay, axes)	Draw a region label.h5 overlay.
`draw_region_overlay`(overlay, axes)	Draw a region overlay on matplotlib axes.
`draw_temporary_region_overlay`(overlay, axes)	Draw a temporary region overlay.

Classes

`RegionComputationRequest`(session_id, image, ...)	Request for region computation.
`RegionData`(name, color[, selection_type, ...])	Data class representing a region of interest.
`RegionDataCompleteProtocol`(args, *kwargs)	Protocol describing a region with fully populated histogram data.
`RegionDataWorkspaceSpec`(id, name, ...)
`RegionSelectionDialog`(selection_type[, parent])	Dialog for selecting region parameters.
`RegionSelector`(ax, region_type)	Temporary, editable selector for region selection.
`RegionSubWindow`(controller[, parent])	Sub-window for displaying region histograms.
`RegionTableModel`(store[, parent])	Table model for displaying region data in a table view.
`RegionTool`()
`RegionToolController`(tool_ctx, tool)	Controller for the region tool.
`RegionToolDock`(parent, controller)	Dock widget for the region tool.
`RegionToolSession`(tool_controller, ...[, ...])	Session for region tool operations.
`RegionWindowController`(source, region_data)	Controller for the region sub-window.

class radioviz.tools.region_tool.RegionComputationRequest(session_id: UUID, image: ndarray, mask: ndarray, enclosure: ROIEnclosure, bins: int | str)[source]

Bases: object

Request for region computation.

Contains all the information needed to compute statistics for a region.

bins: int | str: Number of bins or bin specification for histogram.

enclosure: ROIEnclosure: Enclosure type (Inside/Outside).

image: ndarray: Image data.

mask: ndarray: Binary mask of the region.

session_id: UUID: Unique identifier for the session.

Bases: object

Data class representing a region of interest.

Stores information about a selected region including its properties, statistics, and associated controllers.

Initialize a RegionData instance.

Parameters:

name (str) – Name of the region
color (Color) – Color of the region
selection_type (ROIType) – Type of selection (default: RECTANGLE)
region_controller (Optional[RegionWindowController]) – Controller for the region window
image_controller (Optional[ImageWindowController]) – Controller for the image window
mask (Optional[np.ndarray]) – Binary mask of the region
session_id (Optional[UUID]) – Session identifier
region_id (Optional[UUID]) – Unique identifier for the region
enclosure (Optional[ROIEnclosure]) – Enclosure type (Inside/Outside)
histogram (Optional[np.ndarray]) – Histogram data
bin_edges (Optional[np.ndarray]) – Bin edges for histogram
bins (Optional[Union[int, str]]) – Number of bins or bin specification
mean_value (Optional[float]) – Mean value of region
std_dev_value (Optional[float]) – Standard deviation of region
max_value (Optional[float]) – Maximum value in region
min_value (Optional[float]) – Minimum value in region
area (Optional[float]) – Area of the region

assign_kwargs(**kwargs: Any) → None[source]

Assign keyword arguments to instance attributes.

Parameters:: kwargs (dict) – Keyword arguments to assign

require_image_controller() → ImageWindowController[source]

Return the image controller or raise if missing.

Returns:: Associated image window controller
Return type:: ImageWindowController
Raises:: RuntimeError – If no image controller is linked

require_region_controller() → RegionWindowController[source]

Return the region controller or raise if missing.

Returns:: Associated region window controller
Return type:: RegionWindowController
Raises:: RuntimeError – If no region controller is linked

class radioviz.tools.region_tool.RegionDataCompleteProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol describing a region with fully populated histogram data.

This protocol expresses the invariant that histogram arrays are available after a session completes, without adding runtime checks.

class radioviz.tools.region_tool.RegionDataWorkspaceSpec(id: 'UUID', name: 'str', image_controller_id: 'Optional[UUID]' = None, region_controller_id: 'Optional[UUID]' = None, color: 'tuple[float, float, float]' = (0.0, 0.0, 0.0), selection_type: 'str' = 'Rectangle', enclosure: 'str' = 'Inside', bins: 'Optional[Union[int, str]]' = None, region_geometry: 'dict[str, Any]' = <factory>, show_overlay: 'bool' = True, show_label: 'bool' = True, mask: 'Optional[np.ndarray]' = None, histogram: 'Optional[np.ndarray]' = None, bin_edges: 'Optional[np.ndarray]' = None, mean_value: 'Optional[float]' = None, std_dev_value: 'Optional[float]' = None, max_value: 'Optional[float]' = None, min_value: 'Optional[float]' = None, area: 'Optional[float]' = None)[source]: Bases: object

class radioviz.tools.region_tool.RegionSelectionDialog(selection_type: ROIType, parent: QWidget | None = None)[source]

Bases: QDialog

Dialog for selecting region parameters.

Provides UI for configuring region selection parameters like type, rotation, and enclosure.

Initialize the region selection dialog.

Parameters:

selection_type (ROIType) – Initial selection type
parent (QWidget) – Parent widget

is_rotation_meaningful() → bool[source]

Check if rotation is meaningful for the current selection type.

Returns:: True if rotation is meaningful
Return type:: bool

on_parameters_changed() → None[source]: Handle parameter changes.

on_region_changed(region_type: ROIType) → None[source]

Handle region type changes.

Parameters:: region_type (ROIType) – New region type

change_rotation: Signal emitted when rotation is changed.

region_type_changed: Signal emitted when region type is changed.

update_params: Signal emitted when parameters are updated.

class radioviz.tools.region_tool.RegionSelector(ax: Axes, region_type: ROIType)[source]

Bases: QObject

Temporary, editable selector for region selection.

Lives only for the duration of a ToolSession.

Initialize the region selector.

Parameters:

ax (Axes) – Matplotlib axes to draw on
region_type (ROIType) – Type of region to select

_on_polygon_select(verts: list[tuple[float, float]]) → None[source]

Handle polygon selection.

Parameters:: verts (list) – Vertices of the polygon

_on_select(eclick: MouseEvent, erelease: MouseEvent) → None[source]

Handle mouse selection for rectangle and ellipse.

Parameters:

eclick (MouseEvent) – Mouse click event
erelease (MouseEvent) – Mouse release event

_restore_focus() → None[source]: Restore focus to previously focused widget.

activate() → None[source]

Activate the region selector.

Sets up the appropriate matplotlib selector based on region type.

deactivate() → None[source]

Deactivate the region selector.

Cleans up resources and removes the selector from the canvas.

geometry() → tuple[float, float, float, float] | list[tuple[float, float]] | None[source]

Get the geometry of the current selection.

Returns:: Selection geometry
Return type:: Union[tuple, list, None]
Raises:: RuntimeError – If region type is unsupported

on_key_pressed(event: KeyEvent) → None[source]

Handle key press events.

Parameters:: event (KeyEvent) – Key press event

has_valid_selection: Action descriptor for valid selection state.

valid_selection: Signal emitted when selection validity changes.

class radioviz.tools.region_tool.RegionSubWindow(controller: RegionWindowController, parent: QWidget | None = None)[source]

Bases: CanvasWindow[RegionWindowController, SimpleCanvas]

Sub-window for displaying region histograms.

This window shows the histogram of a selected region of interest.

Initialize the region sub-window.

Parameters:

controller (RegionWindowController) – The region window controller
parent (QWidget) – Parent widget

create_canvas() → SimpleCanvas[source]

Create the canvas used for region histograms.

Returns:: A configured SimpleCanvas instance for region plots.
Return type:: SimpleCanvas

export_to_path(path: Path) → None[source]

Export the current image display to a file.

Saves the current figure displayed in the canvas to the specified path using matplotlib’s savefig functionality.

Parameters:: path (pathlib.Path) – The file path where the image should be saved

on_data_state_changed() → None[source]

Update the window title when data state changes.

This method is called when the underlying data state changes, such as when the data is modified or saved. It updates the window title to reflect the current persistence status.