radioviz.controllers.main_controller

Main controller for the RadioViz application.

This module contains the primary controller responsible for managing the application’s main window, handling image loading, managing tool registrations, and coordinating between different components of the RadioViz application.

Typical workflow for workspace save:

1. Save workspace (JSON/HDF5) using save_workspace()

2. For JSON:

   • If there are nonpersistent images, the user is prompted to select which ones to persist on disk before saving

   • Unchecked images are excluded from the JSON workspace

   • Tool items referencing excluded images are pruned

3. For HDF5:

   • All image data are embedded in the workspace file

   • No selection or exclusion is required

Typical workflow for workspace restoration:

1. Load workspace file using load_workspace() method

2. Workspace is deserialized and _restore_workspace() is called

3. Image windows are restored asynchronously:

   • Images are loaded using a dedicated instance ImageLoaderService

   • Each loaded image creates a new window via _on_workspace_image_ready()

   • Failed image loads are recorded and emitted via image_load_failed signal

4. Once all images are processed, _on_workspace_image_complete() is called

5. Analysis tools are restored in phases:

   • Tools are grouped by restore phase

   • Phases are executed sequentially

   • Within each phase, tools are restored concurrently

6. Tool items referencing missing images are skipped with a warning

7. Finally, UI workspace state is restored via _restore_ui_workspace()

Classes

MainController([tool_list])

Main controller for the RadioViz application.

class radioviz.controllers.main_controller.MainController(tool_list: list[ToolProtocol] | None = None)

Bases: QObject

Main controller for the RadioViz application.

This class serves as the central coordinator for the application, managing windows, tools, image loading, and user interactions.

Initialize the MainController.

Parameters:

• tool_list (Optional[list[ToolProtocol]], optional) – List of tools to register, defaults to None

• application_services (Optional[ApplicationServices], optional) – Application services instance, defaults to None

_clear_tool_selection_if_missing(tool_id: str, tool_ws: ToolWorkspace) → None

Clear tool selection state if the selected item was removed.

Parameters:

• tool_id (str) – Tool identifier

• tool_ws (ToolWorkspace) – Tool workspace to update

_collect_tool_dependency_counts() → dict[UUID, dict[str, int]]

Collect counts of tool items per image.

This is used to inform users which tool items will be pruned if an image is excluded from a JSON workspace.

Returns:

Mapping of image_id to tool_id counts

Return type:

dict[UUID, dict[str, int]]

_create_workspace(serializer_type: SerializerType, excluded_image_ids: set[UUID] | None = None) → Workspace

Create a workspace object from the current application state.

This internal method collects all serializable services from the application services and creates a workspace object containing their serialized state. If excluded_image_ids is provided, images with those IDs are omitted and any tool items referencing those images are pruned from the workspace.

Returns:

Workspace object containing the current application state

Return type:

Workspace

Parameters:

• serializer_type (SerializerType) – Type of serializer to use for saving

• excluded_image_ids (set[UUID] | None) – Optional set of image IDs to exclude

_extract_image_controller_id(item: Any) → UUID | None

Extract the image controller ID from a workspace item.

Parameters:

item (Any) – Workspace item spec (dict-like or object with attribute)

Returns:

Image controller UUID or None if not present

Return type:

UUID | None

_filter_tool_items_by_image_ids(tool_workspaces: dict[str, ToolWorkspace], should_keep: Callable[[UUID], bool]) → dict[str, int]

Filter tool items based on the referenced image ID.

Parameters:

• tool_workspaces (dict[str, ToolWorkspace]) – Tool workspace mapping to mutate

• should_keep (Callable[[UUID], bool]) – Predicate that returns True when the image_id is allowed

Returns:

Count of skipped items per tool_id

Return type:

dict[str, int]

_find_nonpersistent_images() → list[ImageWindowController]

Find image windows that have no persistent storage path.

Returns:

List of nonpersistent image controllers

Return type:

list[ImageWindowController]

_on_all_tools_restored() → None

Handle completion of workspace tool restoration.

This internal method is called when all tools have been successfully restored from the workspace. It proceeds to restore the user interface workspace state.

_on_new_window_request(request: WindowRequest) → None

Handle new window requests.

Parameters:

request (WindowRequest) – Window request object

_on_workspace_image_complete() → None

Handle completion of workspace image restoration.

This method processes any failed image loads and continues with the restoration of analysis tools after all images have been processed during workspace restoration.

If there were any failed image loads, they are emitted via the image_load_failed signal. Then it proceeds to restore the analysis tools from the workspace.

_on_workspace_image_load_failed(path: Path, error: Exception) → None

Handle failed loading of an image during workspace restoration.

This method records the loading failure for the specified path and removes the corresponding image from the pending loading operations. If all images have been processed, it triggers the completion handler.

Parameters:

• path (Path) – Path to the image file that failed to load

• error (Exception) – Exception that occurred during image loading

_on_workspace_image_loaded(path: Path, data: ndarray, metadata: dict[str, Any]) → None

Handle successful loading of an image during workspace restoration.

This method retrieves the corresponding image specification using the provided path and passes it along with the loaded data to the ready handler for further processing.

Parameters:

• path (Path) – Path to the loaded image file

• data (np.ndarray) – NumPy array containing the loaded image data

• metadata (dict[str, Any]) – Metadata associated with the image

_on_workspace_image_ready(spec: ImageWorkspaceSpec, data: ndarray, metadata: dict[str, Any] | None = None) → None

Process an image that has been successfully loaded during workspace restoration.

This method creates an image controller using the provided specification and image data, sets up the display properties, creates the corresponding view, and registers it with the application. It also handles cleanup of pending image loading operations.

Parameters:

• spec (ImageWorkspaceSpec) – Specification for the image to be created

• data (np.ndarray) – NumPy array containing the image data

• metadata (dict[str, Any] | None) – Optional metadata associated with the image

_prune_tool_items_missing_images() → None

Prune tool items referencing images that were not restored.

This prevents dangling tool items from causing errors during restoration when images are missing or skipped.

Returns:

None

Return type:

None

_restore_analysis_tool() → None

Restore analysis tools from the workspace.

This method processes the tools stored in the workspace by grouping them according to their restore phase, sorting the phases, and then restoring tools in each phase sequentially. It manages the restoration process through phase-based execution to ensure proper initialization order.

The method initializes the restoration process by: 1. Grouping tools by their restore phase 2. Sorting phases numerically 3. Starting the first phase of restoration

_restore_next_phase() → None

Restore the next phase of tools in the workspace restoration process.

This method handles the sequential restoration of tools by: 1. Checking if all phases have been processed 2. Creating an asynchronous barrier for the current phase 3. Adding all tools in the current phase to the barrier 4. Connecting tool restoration completion to the barrier 5. Starting the restoration of tools in the current phase

The method ensures that tools within the same phase are restored concurrently while maintaining proper sequencing between phases.

_restore_ui_workspace() → None

Restore the user interface workspace state.

This internal method restores the application’s user interface layout and state from the workspace, including window positions, sizes, and dock widget configurations.

_restore_workspace(workspace: Workspace) → None

Restore the application state from a workspace object.

This internal method takes a workspace object and restores the application state by deserializing each service and applying it to the corresponding service in the application services. Images with missing storage paths are skipped with a warning, and tool items referencing missing images are pruned before tool restoration.

Parameters:

workspace (Workspace) – Workspace object containing the state to restore

add_recent_file(path: Path) → None

Add a file to recent files list.

Parameters:

path (Path) – Path to the file to add

cancel_loading(path: Path) → None

Cancel image loading for a specific path.

Parameters:

path (Path) – Path for which to cancel loading

clear_recent_files() → None

Clear the recent files list.

context_menu_specs_for(window_controller: 'SubWindowController[T_SubWindow]' | None) → List[ToolMenuSpec]

Get merged context menu specifications for the given window controller.

Combines tool-contributed menus with window-specific built-in menus. Tool menus are filtered by window type, while window menus are always included for the active window.

Parameters:

window_controller (Optional[SubWindowController]) – Active window controller or None

Returns:

List of menu specifications

Return type:

List[ToolMenuSpec]

create_new_image_view(path: Path, image_data: ndarray, metadata: dict[str, Any]) → None

Create a new image view for the loaded image.

Parameters:

• path (Path) – Path to the image file

• image_data (np.ndarray) – NumPy array containing image data

• metadata (dict[str, Any]) – Metadata associated with the image

get_recent_files() → list[Path]

Get the list of recent files.

Returns:

List of recent file paths

Return type:

list[Path]

load_workspace(path: Path, serializer_type: SerializerType) → None

Load a workspace from a file.

This method reads and deserializes a workspace from the specified file using the given serializer type, then restores the application state from the loaded workspace.

Parameters:

• path (Path) – Path to the file from which the workspace will be loaded

• serializer_type (SerializerType) – Type of serializer to use for loading

on_nonpersistent_image_selection(accepted: bool, excluded_ids: list[UUID]) → None

Handle the result of the non‑persistent image selection dialog.

This method is called after the user has been prompted to choose which non‑persistent images to keep when saving a JSON workspace. If the user accepts the selection, a new workspace is created excluding the images whose identifiers are provided in excluded_ids and the workspace is saved using the serializer that was originally requested. If the user cancels, the pending save operation is cleared.

Parameters:

• accepted (bool) – True if the user confirmed the selection, False otherwise.

• excluded_ids (list[UUID]) – List of image UUIDs to exclude from the workspace.

open_image(path: Path) → None

Open an image file.

High-level use case: open an image.

Parameters:

path (Path) – Path to the image file

open_recent(path: Path) → None

Open a recently accessed file.

Parameters:

path (Path) – Path to the recent file

open_xyz_with_dat(xyz_path: Path, dat_path: Path | None) → None

Open a XYZ image, optionally using a DAT sidecar for metadata.

Parameters:

• xyz_path (Path) – Path to the XYZ file.

• dat_path (Path | None) – Optional path to the DAT sidecar file.

register_global_dock(dock_id: str, dock: ToolDockWidget[Any]) → None

Register a global dock widget.

Parameters:

• dock_id (str) – Identifier for the dock widget

• dock (ToolDockWidget[Any]) – Tool dock widget to register

register_overlay_factory() → None

Register overlay factories for all registered tools.

This method iterates through all registered tools and registers their overlay specifications with the overlay factory.

register_tool_controllers() → list[ToolController[Any, Any]]

Register tool controllers for all registered tools.

Returns:

List of registered tool controllers

Return type:

list

register_window(window_controller: SubWindowController[T_SubWindow]) → None

Register a window controller.

Parameters:

window_controller (SubWindowController) – Controller for the window to register

register_window_factory() → None

Register window factories for all registered tools.

This method iterates through all registered tools and registers their window specifications with the window factory.

save_workspace(path: Path, serializer_type: SerializerType) → None

Save the current workspace to a file.

This method serializes the current application state and saves it to the specified file using the given serializer type.

For JSON workspaces, if nonpersistent images are detected, the method immediately emits a selection request and returns without writing the workspace file. The UI will prompt the user to choose which images to persist on disk. Once the selection completes, on_nonpersistent_image_selection continues the save by persisting the selected images, excluding unchecked images from the workspace, and pruning dependent tool items.

Parameters:

• path (Path) – Path to the file where the workspace will be saved

• serializer_type (SerializerType) – Type of serializer to use for saving

set_active_window(window_controller: SubWindowController[T_SubWindow]) → None

Set the active window controller.

Parameters:

window_controller (SubWindowController) – Controller for the active window

set_tool_register(tool_list: list[ToolProtocol]) → None

Set the tool register with a new list of tools.

Parameters:

tool_list (list[ToolProtocol]) – List of tools to register

show_image_metadata_window() → None

Show a metadata window for the active image.

sync_tool_menu_state(window_controller: 'SubWindowController[T_SubWindow]' | None = None) → None

Emit current tool menu states so on-demand menus reflect availability.

Only tools compatible with the active window type are synchronized.

tool_menu_specs() → List[ToolMenuSpec]

Get menu specifications for all registered tools.

Returns:

List of tool menu specifications

Return type:

List[ToolMenuSpec]

tool_menu_specs_for(window_controller: 'SubWindowController[T_SubWindow]' | None) → List[ToolMenuSpec]

Get tool menu specifications filtered for the given window controller.

Tool menus are only included when the tool declares compatibility with the active window type via radioviz.tools.base_controller.ToolController.enable_for_window_type.

Parameters:

window_controller (Optional[SubWindowController]) – Active window controller or None

Returns:

List of tool menu specifications

Return type:

List[ToolMenuSpec]

unregister_window(window_controller: SubWindowController[T_SubWindow]) → None

Unregister a window controller.

Parameters:

window_controller (SubWindowController) – Controller for the window to unregister

context_menu_requested

Signal emitted when context menu is requested

image_load_failed

Signal emitted when image loading fails

message_requested

Signal emitted when a user-facing message is requested

request_new_window_view

Signal emitted when a new window view is requested

request_nonpersistent_image_selection

Signal emitted when JSON workspace save requires user selection

request_xyz_metadata

Signal emitted when a XYZ DAT sidecar is missing

tools_changed

Signal emitted when tools are changed