radioviz.tools.manual_crop_tool

Manual crop tool implementation.

This module provides a complete implementation of a manual cropping workflow for image data. It defines data structures for session results, a dialog for user interaction, a session class that manages the selection and cropping process, a controller that integrates the tool with the application framework, and the tool class itself which registers overlays and exposes the functionality to the rest of the application.

Functions

manual_crop_worker(image, extents, label, ...)

Perform a cropping operation in a background thread.

Classes

`ManualCropSessionResult`(label, image, extents)	Result of a manual crop session.
`ManualCropTool`()	Tool class representing the manual crop functionality.
`ManualCropToolController`(tool_ctx, tool)	Controller for the manual crop tool.
`ManualCropToolDialog`(tool_session[, parent])	Dialog window for configuring manual crop parameters.
`ManualCropToolSession`(tool_controller, ...)	Session class for manual crop tool workflow.

class radioviz.tools.manual_crop_tool.ManualCropSessionResult(label: str, image: ndarray, extents: tuple[float, float, float, float])[source]

Bases: object

Result of a manual crop session.

This dataclass encapsulates the label, cropped image data, and the extents of the region that was selected during a manual cropping operation.

extents: tuple[float, float, float, float]: The (x0, x1, y0, y1) extents of the selected region in image coordinates.

image: ndarray: The NumPy array containing the cropped image data.

label: str: The label assigned to the cropped image.

class radioviz.tools.manual_crop_tool.ManualCropTool[source]

Bases: Tool[ManualCropToolController]

Tool class representing the manual crop functionality.

Provides the UI integration and overlay registration for manual cropping operations.

Initialise the manual crop tool.

create_controller(ctx: ToolContext) → ManualCropToolController[source]

Create and store the ManualCropToolController for this tool.

Parameters:: ctx (ToolContext) – The shared tool context.
Returns:: The newly created controller.
Return type:: ManualCropToolController

description: str = 'A tool to manually select and crop a region of interest': Tooltip or description

name: str = 'Manual Crop': Human-readable name

overlays_to_be_registered: list[OverlaySpec] = [OverlaySpec(overlay_type='crop-with-label', overlay_role=<OverlayRole.Permanent: 'permanent'>, renderer=<function draw_crop_overlay>), OverlaySpec(overlay_type='crop-with-label', overlay_role=<OverlayRole.Highlight: 'highlight'>, renderer=<function draw_highlight_crop_overlay>)]: List of overlay specifications to register

tool_id: str = 'manualcrop': Unique identifier of the tool

class radioviz.tools.manual_crop_tool.ManualCropToolController(tool_ctx: ToolContext, tool: Tool[ManualCropToolController])[source]

Bases: ToolController[ImageWindowController, ManualCropToolSession]

Controller for the manual crop tool.

Handles activation, overlay management, and interaction with the application context. It also provides the menu specifications used by the UI.

Initialise the controller.

Parameters:

tool_ctx (ToolContext) – The shared tool context.
tool (Tool) – The ManualCropTool instance.

_check_for_overlay(new_window_controller: SubWindowController[Any] | None) → bool[source]

Determine whether a crop overlay can be shown for the given window.

Parameters:: new_window_controller (SubWindowController[Any]) – The window to inspect.
Returns:: True if an overlay can be displayed, False otherwise.
Return type:: bool

_check_for_shown_overlays(new_window_controller: SubWindowController[Any] | None) → bool[source]

Check whether any manual‑crop overlays are currently visible.

Parameters:: new_window_controller (SubWindowController[Any]) – The window to inspect.
Returns:: True if at least one overlay is visible.
Return type:: bool

_on_active_image_changed(new_window_controller: SubWindowController[Any] | None) → None[source]

React to a change in the active image window.

Updates the various action descriptors based on the new window.

Parameters:: new_window_controller (SubWindowController[Any]) – The newly active sub‑window controller.

static _overlay_label_for(window_controller: ImageWindowController) → str[source]

Return the overlay label for a derived crop window.

Parameters:: window_controller (ImageWindowController) – The derived image window controller.
Returns:: The short overlay label to use.
Return type:: str

_update_crop_overlay() → None[source]

Update the overlay on the original image when the derived image changes.

This method is connected to the state_changed signal of the derived image window controller.

create_dock(parent_window: QWidget) → None[source]

Manual crop does not provide a dock widget.

Parameters:: parent_window (QWidget) – The parent widget (unused).
Returns:: None.
Return type:: None

create_session(window_controller: ImageWindowController) → ManualCropToolSession[source]

Create a new ManualCropToolSession for the given window.

Parameters:: window_controller (ImageWindowController) – The image window to operate on.
Returns:: A fresh session instance.
Return type:: ManualCropToolSession

hide_all_crops_overlays() → None[source]: Hide every manual‑crop overlay that is currently visible.

menu_specs() → List[ToolMenuSpec][source]

Return the menu specifications for the manual crop tool.

Returns:: A list containing a single ToolMenuSpec with actions.
Return type:: List[ToolMenuSpec]

on_manual_crop_start() → None[source]

Entry point for the Start manual crop menu action.

Activates the tool, which in turn creates a new session.

on_overlay_request() → None[source]

Toggle the visibility of the ROI overlay on the original image.

If the overlay does not exist, it is created; otherwise its visibility is toggled.

procedure_can_start: Action descriptor for determining if the procedure can start.

procedure_start_enable: Signal emitted to enable/disable the procedure start action.

class radioviz.tools.manual_crop_tool.ManualCropToolDialog(tool_session: ManualCropToolSession, parent: QWidget | None = None)[source]

Bases: QDialog

Dialog window for configuring manual crop parameters.

The dialog displays spin boxes for the top‑left corner, width, height, and aspect ratio of the selection. It stays synchronised with the RectangleSelector used on the image canvas.

Initialise the dialog.

Parameters:

tool_session (ManualCropToolSession) – The active ManualCropToolSession.
parent (QWidget or None) – Optional parent widget.

_connect_signals() → None[source]: Connect spin box value changes to the internal synchronisation handler.

_on_values_changed() → None[source]

Propagate spin box changes to the selector.

This method is called whenever any of the spin boxes emits a valueChanged signal, unless the dialog is currently synchronising values from the selector.

_setup_spinboxes() → None[source]

Configure the spin boxes limits and steps based on the image size.

The maximum values correspond to the image dimensions, while the step size is set to 1.0 pixel.

_update_aspect_ratio(width: float, height: float) → None[source]

Compute and display the aspect ratio of the current selection.

Parameters:

width (float) – Width of the selection in pixels.
height (float) – Height of the selection in pixels.

set_values_from_extent(extents: tuple[float, float, float, float]) → None[source]

Update the spin boxes to reflect a new selector extent.

Parameters:: extents (tuple[float, float, float, float]) – The (x0, x1, y0, y1) extents to display.

class radioviz.tools.manual_crop_tool.ManualCropToolSession(tool_controller: ManualCropToolController, window_controller: ImageWindowController)[source]

Bases: BaseToolSession[ManualCropToolController, ImageWindowController]

Session class for manual crop tool workflow.

Manages the lifecycle of a manual cropping operation, including the creation of the selector, synchronisation with the dialog, and the background cropping task.

Initialise a new session.

Parameters:

tool_controller (ManualCropToolController) – The controller that created this session.
window_controller (ImageWindowController) – The image window on which cropping is performed.

_normalize_extents(x: float, y: float, w: float, h: float) → RectangleExtent[source]

Clamp and normalise the user‑provided extents to the image bounds.

Parameters:

x (float) – Desired top‑left X coordinate.
y (float) – Desired top‑left Y coordinate.
w (float) – Desired width.
h (float) – Desired height.

Returns:

A RectangleExtent representing the normalised region.

Return type:

RectangleExtent

_on_crop_ready(crop: CropResult) → None[source]

Handle the result of the background cropping operation.

Creates a new ImageWindowController for the cropped image, registers the overlay, and finalises the session.

Parameters:: crop (CropResult) – The result produced by manual_crop_worker().

_setup_selector() → None[source]

Initialise the RectangleSelector on the image canvas.

The selector is centred on the image and occupies half of its width and height by default.

_teardown_selector() → None[source]: Remove the selector from the canvas and release its resources.

cleanup() → None[source]: Remove the selector and any associated visual artefacts.

on_cancel(reason: str) → None[source]

Cancel the session and clean up resources.

Parameters:: reason (str) – Reason for cancellation (e.g., user action).

on_finish() → None[source]: Finish the session and clean up resources.

on_selector_change(click: MouseEvent, release: MouseEvent) → None[source]

Callback invoked when the selector geometry changes.

Updates the dialog spin boxes to reflect the new extents.

Parameters:

click (MouseEvent) – Mouse event at the start of the selection.
release (MouseEvent) – Mouse event at the end of the selection.

on_start() → None[source]: Start the session by showing the configuration dialog and the selector.

request_cropping() → None[source]: Trigger the background cropping operation using the current selector extents.

update_selector_from_values(x: float, y: float, w: float, h: float) → None[source]

Update the selector geometry based on spin box values.

Parameters:

x (float) – Top‑left X coordinate.
y (float) – Top‑left Y coordinate.
w (float) – Width of the selection.
h (float) – Height of the selection.

radioviz.tools.manual_crop_tool.manual_crop_worker(image: ndarray, extents: tuple[float, float, float, float], label: str, overlay_label: str) → CropResult[source]

Perform a cropping operation in a background thread.

The worker normalises the supplied extents to the image dimensions, extracts the corresponding sub‑array, and returns a CropResult.

Parameters:

image (numpy.ndarray) – The source image data.
extents (tuple[float, float, float, float]) – The raw (x0, x1, y0, y1) extents supplied by the selector.
label (str) – The label to assign to the resulting cropped image.
overlay_label (str) – Short label to use for overlay annotations.

Returns:

A CropResult containing the cropped image and its extents.

Return type:

CropResult