radioviz.tools.level_tool

Level tool module for image display parameter adjustment.

This module provides functionality for adjusting image display parameters such as level ranges, color maps, and interpolation methods through a dock widget interface. It includes the controller, dock widget, and associated classes for managing image display properties in the application.

Functions

default_scalebar_settings(controller)

Build default scalebar settings for an image controller.

draw_scalebar_overlay(overlay, axes)

Draw a scalebar overlay on Matplotlib axes.

Classes

ColormapArgs

LevelTool()

Tool for adjusting image display levels.

LevelToolController(tool_ctx, tool)

Controller for level adjustment tool.

LevelToolDock(parent, controller)

Dock widget for level adjustment controls.

LevelToolSession(tool_controller, ...[, parent])

Placeholder session for the level tool.

LevelToolTabKey(*values)

Tab identifiers for the level tool dock.

ScaleBarDialog(unit, settings[, parent])

Dialog for configuring scalebar settings.

ScaleBarSettings(visible, length_m, ...)

Serializable scalebar settings.
class radioviz.tools.level_tool.ColormapArgs[source]

Bases: TypedDict

class radioviz.tools.level_tool.LevelTool[source]

Bases: Tool[LevelToolController]

Tool for adjusting image display levels.

Provides functionality to modify image display parameters such as intensity levels, color mapping, and interpolation methods.

create_controller(ctx: ToolContext) → LevelToolController[source]

Create a controller instance for this tool.

Parameters:

ctx (ToolContext) – Tool context

Returns:

LevelToolController instance

Return type:

LevelToolController

from_workspace(spec: ToolWorkspace, context: WorkspaceReferenceManager) → None[source]

Restore the tool state from a workspace specification.

Parameters:
Raises:

RuntimeError – When no controller is available for restore.

restore_phase() → int[source]

Return the restore phase for workspace restore ordering.

Returns:

Restore phase index.

Return type:

int

to_workspace(include_data: bool) → ToolWorkspace[source]

Convert the current tool state to a workspace specification.

Parameters:

include_data (bool) – Flag indicating whether to include data arrays.

Returns:

Workspace specification containing the tool’s state.

Return type:

ToolWorkspace

description: str = 'A tool to change the image display levels'

Tooltip or description

name: str = 'Level Tool'

Human-readable name

overlays_to_be_registered: list[OverlaySpec] = [OverlaySpec(overlay_type='scalebar', overlay_role=<OverlayRole.Permanent: 'permanent'>, renderer=<function draw_scalebar_overlay>)]

List of overlay specifications to register

tool_id: str = 'level'

Unique identifier of the tool

class radioviz.tools.level_tool.LevelToolController(tool_ctx: ToolContext, tool: Tool[LevelToolController])[source]

Bases: ToolController[ImageWindowController, LevelToolSession]

Controller for level adjustment tool.

Manages the interaction between the tool dock widget and image controllers for updating display parameters.

Initialize the level tool controller.

Parameters:
_apply_scalebar_overlay(controller: ImageWindowController) → None[source]

Apply or remove the scalebar overlay on the given image.

Parameters:

controller (ImageWindowController) – Image controller.

_build_display_payload(controller: ImageWindowController) → dict[str, Any][source]

Build payload for dock synchronization.

Parameters:

controller (ImageWindowController) – Image controller.

Returns:

Payload dictionary.

Return type:

dict

static _display_signature_from_payload(payload: dict[str, Any]) → tuple[Any, ...][source]

Build a stable signature for display payload comparisons.

Parameters:

payload (dict) – Display payload dictionary.

Returns:

Tuple signature for payload equality checks.

Return type:

tuple

_edit_scalebar_from_event() → None[source]

Open the scalebar editing dialog for the active image.

static _normalize_tab_key(tab_key: object) → str[source]

Normalize persisted tab keys into strings.

Parameters:

tab_key (object) – Raw tab key value from workspace.

Returns:

Normalized tab key.

Return type:

str

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

Handle changes to the active image controller.

Parameters:

active_image_controller (ImageWindowController) – New active image controller

_on_window_list_changed() → None[source]

Handle window list changes by syncing scalebar overlays.

_remove_scalebar_overlay(controller: ImageWindowController) → None[source]

Remove the scalebar overlay from an image controller.

Parameters:

controller (ImageWindowController) – Image controller.

_resolve_scalebar_settings(controller: ImageWindowController) → ScaleBarSettings | None[source]

Get scalebar settings from the controller or initialize defaults.

Parameters:

controller (ImageWindowController) – Image controller.

Returns:

Scalebar settings or None.

Return type:

ScaleBarSettings | None

_set_axis_label_mode_checked(mode: str, checked: bool) → None[source]

Set axis label mode when a menu action is checked.

Parameters:

  • mode (str) – Axis label mode to set.

  • checked (bool) – Whether the menu action is checked.

_set_axis_label_mode_from_event(payload: dict[str, Any]) → None[source]

Handle axis label change from dock events.

Parameters:

payload (dict) – Event payload.

_set_scalebar_visible_checked(checked: bool) → None[source]

Handle scalebar menu toggles.

Parameters:

checked (bool) – Whether scalebar should be visible.

_set_scalebar_visible_for_active(visible: bool) → None[source]

Set scalebar visibility for the active image.

Parameters:

visible (bool) – Whether to show the scalebar.

_set_scalebar_visible_from_event(payload: dict[str, Any]) → None[source]

Handle scalebar toggle from dock.

Parameters:

payload (dict) – Event payload.

_sync_dock_state(controller: ImageWindowController) → None[source]

Sync dock widget state with the current controller.

Parameters:

controller (ImageWindowController) – Image controller.

_sync_menu_state(controller: ImageWindowController) → None[source]

Sync menu check states to the active image.

Parameters:

controller (ImageWindowController) – Image controller.

apply_dock_state(state: dict[str, str]) → None[source]

Apply a previously saved dock state.

Parameters:

state (dict) – Dock state payload.

create_dock(parent_window: QWidget) → LevelToolDock[source]

Create a dock widget for this tool.

Parameters:

parent_window (QWidget) – Parent window for the dock

Returns:

LevelToolDock instance

Return type:

LevelToolDock

create_session(window_controller: ImageWindowController) → LevelToolSession[source]

Create a tool session for the given window controller.

Parameters:

window_controller (SubWindowController) – Window controller to create session for

Returns:

BaseToolSession instance

Return type:

BaseToolSession

dock_state() → dict[str, str][source]

Return the dock state for workspace persistence.

Returns:

Dock state payload.

Return type:

dict

get_initial_levels() → Tuple[int, int][source]

Get initial level values for the active image.

Returns:

Tuple of (vmin, vmax) initial values

Return type:

Tuple[int, int]

menu_specs() → list[ToolMenuSpec][source]

Provide menu specifications for axis labels and scalebar.

Returns:

List of menu specifications.

Return type:

list[ToolMenuSpec]

on_dock_event(event: ToolEvent) → None[source]

Handle events emitted from the dock widget.

Parameters:

event (ToolEvent) – Tool event from dock

sync_menu_state_for(window_controller: SubWindowController[Any]) → None[source]

Sync menu state for the provided window controller.

Parameters:

window_controller (SubWindowController) – Active window controller

class radioviz.tools.level_tool.LevelToolDock(parent: QWidget, controller: LevelToolController)[source]

Bases: ToolDockWidget[LevelToolController]

Dock widget for level adjustment controls.

This dock widget provides controls for adjusting image display parameters including level ranges, color maps, and interpolation settings.

Variables:

  • initial_visibility (bool) – Whether the dock is initially visible

  • enable_for_window_type (SubWindowEnum) – Window type this dock is enabled for

Initialize the level tool dock widget.

Parameters:

  • parent (QWidget) – Parent widget

  • controller (LevelToolController) – Level tool controller instance

_apply_content_enabled_state() → None[source]

Apply enabled state to the dock contents while leaving tabs available.

_build_levels_tab() → QWidget[source]

Build the levels tab widget.

Returns:

Levels tab widget.

Return type:

QWidget

_build_scale_tab(axis_group: QGroupBox) → QWidget[source]

Build the scale tab widget.

Parameters:

axis_group (QGroupBox) – Axis label group widget.

Returns:

Scale tab widget.

Return type:

QWidget

_emit_axis_mode(mode: str, checked: bool) → None[source]

Emit axis label mode change event.

Parameters:

  • mode (str) – Axis label mode.

  • checked (bool) – Whether the radio button is checked.

_emit_scalebar_edit() → None[source]

Emit scalebar edit event.

_emit_scalebar_toggle(checked: bool) → None[source]

Emit scalebar visibility change event.

Parameters:

checked (bool) – Whether scalebar is visible.

_normalize_tab_key(tab_key: object) → LevelToolTabKey[source]

Normalize persisted tab keys into strings.

Parameters:

tab_key (object) – Raw tab key value from workspace.

Returns:

Normalized tab key.

Return type:

LevelToolTabKey

_on_tab_bar_clicked(index: int) → None[source]

Preserve the current active image while switching tabs.

Parameters:

index (int) – Index of the clicked tab.

_on_tab_changed(index: int) → None[source]

Restore the active image after a tab change.

Parameters:

index (int) – Index of the new tab.

_tab_index(tab_key: LevelToolTabKey) → int[source]

Resolve the tab index for a key.

Parameters:

tab_key (LevelToolTabKey) – Tab key.

Returns:

Tab index.

Return type:

int

_tab_key(index: int) → LevelToolTabKey[source]

Resolve the tab key for an index.

Parameters:

index (int) – Tab index.

Returns:

Tab key.

Return type:

LevelToolTabKey

apply_dock_state(state: dict[str, str]) → None[source]

Apply a previously saved dock state.

Parameters:

state (dict) – Dock state payload.

dock_state() → dict[str, str][source]

Return the dock state for workspace persistence.

Returns:

Dock state payload.

Return type:

dict

handle_event(event: ToolEvent) → None[source]

Handle tool events from the controller.

Parameters:

event (ToolEvent) – Tool event to process

reset_levels() → None[source]

Reset level values to initial state.

Resets the level slider values to the initial range defined by the controller’s get_initial_levels method.

setEnabled(enabled: bool) → None[source]

Override enabled state to keep tab switching available.

Parameters:

enabled (bool) – Whether to enable the dock content.

update_parameters() → None[source]

Update image display parameters based on widget values.

Collects current values from sliders and comboboxes and emits an event to update image parameters.

update_widget_from_image(display_params: dict[str, Any]) → None[source]

Update widget values based on image display parameters.

Parameters:

display_params (dict) – Dictionary containing display parameters

class radioviz.tools.level_tool.LevelToolSession(tool_controller: T_Tool_Controller, window_controller: T_SubWindowController, parent: QObject | None = None)[source]

Bases: BaseToolSession[LevelToolController, ImageWindowController]

Placeholder session for the level tool.

Initialize a new tool session.

Parameters:

  • tool_controller (ToolController) – The controller managing this tool session

  • window_controller (SubWindowController[Any]) – The window controller associated with this session

  • parent (QObject, optional) – Parent QObject for Qt ownership management

on_cancel(reason: str) → None[source]

Cancel the session.

Parameters:

reason (str) – Cancellation reason.

on_finish() → None[source]

Finish the session.

on_start() → None[source]

Start the session.

class radioviz.tools.level_tool.LevelToolTabKey(*values)[source]

Bases: StrEnum

Tab identifiers for the level tool dock.

class radioviz.tools.level_tool.ScaleBarDialog(unit: DistanceUnit, settings: ScaleBarSettings, parent: QWidget | None = None)[source]

Bases: QDialog

Dialog for configuring scalebar settings.

Initialize the scalebar dialog.

Parameters:

  • unit (DistanceUnit) – Distance unit for display.

  • settings (ScaleBarSettings) – Current scalebar settings.

  • parent (QWidget, optional) – Parent widget.

settings() → ScaleBarSettings[source]

Return dialog settings.

Returns:

Updated scalebar settings.

Return type:

ScaleBarSettings

class radioviz.tools.level_tool.ScaleBarSettings(visible: bool, length_m: float, height_m: float, bar_color: tuple[float, float, float], text_color: tuple[float, float, float], background_color: tuple[float, float, float] | None, background_alpha: float, location: str)[source]

Bases: object

Serializable scalebar settings.

Parameters:

  • visible (bool) – Whether the scalebar is visible.

  • length_m (float) – Scalebar length in meters.

  • height_m (float) – Scalebar height in meters.

  • bar_color (tuple[float, float, float]) – RGB color for the bar.

  • text_color (tuple[float, float, float]) – RGB color for the text.

  • background_color (tuple[float, float, float] | None) – Optional RGB background color.

  • background_alpha (float) – Background alpha value.

  • location (str) – Matplotlib anchor location.

classmethod from_dict(payload: dict[str, Any]) → ScaleBarSettings[source]

Deserialize settings from a dictionary.

Parameters:

payload (dict) – Serialized settings.

Returns:

Parsed settings.

Return type:

ScaleBarSettings

to_dict() → dict[str, Any][source]

Serialize settings to a dictionary.

Returns:

Serialized settings.

Return type:

dict

radioviz.tools.level_tool._qcolor_to_rgb(color: QColor | None) → tuple[float, float, float][source]

Convert QColor to RGB tuple in [0, 1].

Parameters:

color (QColor | None) – QColor instance.

Returns:

RGB tuple.

Return type:

tuple[float, float, float]

radioviz.tools.level_tool._set_scalebar_text_color(scalebar: AnchoredSizeBar, color: tuple[float, float, float]) → None[source]

Set scalebar label text color across Matplotlib versions.

Parameters:

  • scalebar (AnchoredSizeBar) – AnchoredSizeBar instance.

  • color (tuple[float, float, float]) – RGB color tuple.

radioviz.tools.level_tool.default_scalebar_settings(controller: ImageWindowController) → ScaleBarSettings | None[source]

Build default scalebar settings for an image controller.

Parameters:

controller (ImageWindowController) – Image window controller.

Returns:

Default scalebar settings or None when unavailable.

Return type:

ScaleBarSettings | None

radioviz.tools.level_tool.draw_scalebar_overlay(overlay: OverlayModel, axes: Axes) → list[Artist][source]

Draw a scalebar overlay on Matplotlib axes.

Parameters:

  • overlay (OverlayModel) – Overlay model with scalebar geometry and style.

  • axes (matplotlib.axes.Axes) – Target matplotlib axes.

Returns:

List of created artists.

Return type:

list