radioviz.services.workspace_manager

Module for managing workspace serialization and deserialization.

This module provides functionality for serializing and deserializing workspace states, including image specifications, tool workspaces, and service workspaces. It supports both JSON and HDF5 formats for workspace persistence.

The core components include: - Workspace: The neutral representation of an analysis workspace - WorkspaceSerializer: Abstract base class for workspace serializers - JSONWorkspaceSerializer: JSON-based workspace serializer - HDF5WorkspaceSerializer: HDF5-based workspace serializer - WorkspaceReferenceManager: Runtime context for workspace reconstruction

Functions

`enforce_uuid`(value)	Convert a UUID or string representation to a UUID object.
`workspace_spec_as_mapping`(spec)	Normalize a workspace specification to a mapping.

Classes

`AsyncBarrier`([parent])	A synchronization primitive for managing asynchronous operations.
`HDF5WorkspaceSerializer`()	Full workspace serializer (HDF5).
`ImageWorkspaceSpec`(id, source, storage, ...)	Specification for image workspace components.
`JSONWorkspaceSerializer`()	Light workspace serializer (JSON).
`RadiovizEncoder`(*[, skipkeys, ensure_ascii, ...])	Custom JSON encoder for Radioviz data types.
`SerializerType`(*values)	Enumeration of supported serializer types.
`ServiceWorkspace`(service_id, version, state, ...)	Workspace state for a service component.
`ToolWorkspace`(tool_id, version, items, ...)	Workspace state for a single tool.
`UIWindowState`(window_id, state, z_order)	State information for a single UI window.
`UIWorkspace`(active_window_id, windows)	Workspace state for UI configuration.
`WindowState`(*values)	Enumeration of window states.
`Workspace`(version, images, ...)	Neutral representation of an analysis workspace.
`WorkspaceReferenceManager`()	Runtime context used during workspace reconstruction.
`WorkspaceSerializable`(args, *kwargs)	Protocol for objects that can be serialized to workspace specifications.
`WorkspaceSerializableTool`(args, *kwargs)	Base class for workspace serializable tools.
`WorkspaceSerializer`()	Abstract base class for workspace serializers.
`WorkspaceSpec`(args, *kwargs)	Marker protocol for all workspace specs.

class radioviz.services.workspace_manager.AsyncBarrier(parent: QObject | None = None)[source]

Bases: QObject

A synchronization primitive for managing asynchronous operations.

This class provides a mechanism to track multiple asynchronous operations and emit a signal when all operations are completed. It is designed to work with Qt’s signal-slot mechanism for coordinating asynchronous tasks.

Variables:: completed (Signal) – Signal emitted when all pending operations are finished

Initialize the async barrier.

Parameters:: parent (QObject | None) – Parent QObject for ownership management

add(token: object) → None[source]

Add a token to the barrier.

Parameters:: token (object) – Token representing an asynchronous operation
Raises:: RuntimeError – if the barrier is already closed

done(token: object) → None[source]

Mark an operation as completed.

Parameters:: token (object) – Token representing the completed operation

is_completed() → bool[source]

Check if all operations have completed.

Returns:: True if all operations are completed, False otherwise
Return type:: bool

class radioviz.services.workspace_manager.HDF5WorkspaceSerializer[source]

Bases: WorkspaceSerializer

Full workspace serializer (HDF5).

This serializer implements workspace serialization using HDF5 format, suitable for storing large workspace data efficiently.

Variables:

FORMAT_VERSION (str) – Format version string
serializer_type (SerializerType) – Serializer type (HDF5)

_decode_attr(grp: Group, key: str) → Any[source]

Decode attribute from HDF5 group.

Parameters:

grp (h5py.Group) – HDF5 group to decode from
key (str) – Key for the attribute

Returns:

Decoded attribute value

Return type:

Any

_decode_data_source(grp: Group) → DataSource[source]

Decode data source from HDF5 group.

Parameters:: grp (h5py.Group) – HDF5 group containing data source
Returns:: Decoded data source
Return type:: DataSource

_decode_data_storage(grp: Group) → DataStorage[source]

Decode data storage from HDF5 group.

Parameters:: grp (h5py.Group) – HDF5 group containing data storage
Returns:: Decoded data storage
Return type:: DataStorage

_decode_derivation(grp: Group) → SpatialDerivation[source]

Decode spatial derivation from HDF5 group.

This internal method reconstructs a spatial derivation object from an HDF5 group structure. It handles decoding of parent ID, region of interest, and transformation information.

Parameters:: grp (h5py.Group) – HDF5 group containing derivation data
Returns:: Decoded spatial derivation
Return type:: SpatialDerivation

_decode_display_parameters(attrs: AttributeManager) → dict[str, Any][source]

Decode display parameters from HDF5 attributes.

Parameters:: attrs (h5py.AttributeManager) – HDF5 attributes mapping.
Returns:: Display parameters dictionary.
Return type:: dict

_decode_group(grp: Group) → dict[str, Any][source]

Decode entire HDF5 group to dictionary.

Parameters:: grp (h5py.Group) – HDF5 group to decode
Returns:: Decoded dictionary
Return type:: dict[str, Any]

_decode_image_specs(grp: Group) → dict[UUID, ImageWorkspaceSpec][source]

Decode image specifications from HDF5 group.

Parameters:: grp (h5py.Group) – HDF5 group containing image specifications
Returns:: Decoded image specifications dictionary
Return type:: dict[UUID, ImageWorkspaceSpec]

_decode_items(grp: Group) → dict[UUID, Any][source]: Main entry point to decode the workspace.

_decode_roi(grp: Group) → ROI[source]

Decode region of interest from HDF5 group.

This internal method reconstructs a region of interest object from an HDF5 group structure. It handles decoding of ROI type, enclosure type, and geometric data.

Parameters:: grp (h5py.Group) – HDF5 group containing ROI data
Returns:: Decoded region of interest
Return type:: ROI

_decode_services(h5: File) → dict[str, ServiceWorkspace][source]

Decode services from HDF5 file.

Parameters:: h5 (h5py.File) – HDF5 file handle
Returns:: Decoded services dictionary
Return type:: dict[str, ServiceWorkspace]

_decode_single_image_spec(grp: Group) → ImageWorkspaceSpec[source]

Decode single image specification from HDF5 group.

Parameters:: grp (h5py.Group) – HDF5 group containing single image specification
Returns:: Decoded image workspace specification
Return type:: ImageWorkspaceSpec

_decode_specs(grp: Group) → dict[UUID, WorkspaceSpec][source]

Decode workspace specifications from HDF5 group.

Parameters:: grp (h5py.Group) – HDF5 group containing specifications
Returns:: Decoded specifications dictionary
Return type:: dict[UUID, WorkspaceSpec]

_decode_tools(h5: File) → dict[str, ToolWorkspace][source]

Decode tools from HDF5 file.

Parameters:: h5 (h5py.File) – HDF5 file handle
Returns:: Decoded tools dictionary
Return type:: dict[str, ToolWorkspace]

_decode_transform(grp: Group) → Transform[source]

Decode transform from HDF5 group.

This internal method reconstructs a transform object from an HDF5 group structure. It handles decoding of transform type and parameters.

Parameters:: grp (h5py.Group) – HDF5 group containing transform data
Returns:: Decoded transform
Return type:: Transform

_decode_ui(h5: File) → UIWorkspace[source]

Decode UI workspace state from HDF5 group.

This internal method reconstructs the UI workspace state from an HDF5 group structure. It handles decoding of active window ID and all managed windows with their respective state information.

Parameters:: h5 (h5py.File) – HDF5 file handle
Returns:: Decoded UI workspace state
Return type:: UIWorkspace

_decode_value(item: Any) → Any[source]: Recursive helper to decode HDF5 objects (Groups, Datasets, or Attributes) back into Python/NumPy types.

_encode_attr(grp: Group, key: str, value: Any) → None[source]

Encode attribute to HDF5 group.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
key (str) – Key for the attribute
value – Value to encode

_encode_data_source(grp: Group, ds: DataSource) → None[source]

Encode data source to HDF5 group.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
ds (DataSource) – Data source to encode

_encode_data_storage(grp: Group, ds: DataStorage) → None[source]

Encode data storage to HDF5 group.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
ds (DataStorage) – Data storage to encode

_encode_derivation(grp: Group, derivation: SpatialDerivation) → None[source]

Encode spatial derivation to HDF5 group.

This internal method converts a spatial derivation object into an HDF5 group structure suitable for persistent storage. It handles encoding of parent ID, region of interest, and transformation information.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
derivation (SpatialDerivation) – Spatial derivation to encode

_encode_display_parameters(grp: Group, params: dict[str, Any]) → None[source]

Encode display parameters to HDF5 group.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
params (dict) – Display parameters to encode

_encode_image_specs(h5: File, name: str, specs: dict[UUID, ImageWorkspaceSpec]) → None[source]

Encode image specifications to HDF5 file.

Parameters:

h5 (h5py.File) – HDF5 file handle
name (str) – Name of the group to create
specs (dict[UUID, ImageWorkspaceSpec]) – Dictionary of image workspace specifications

_encode_order(grp: Group, key: str, value: list[UUID]) → None[source]

Encode execution order to HDF5 group.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
key (str) – Key for the order
value (list[UUID]) – Order list to encode

_encode_roi(grp: Group, roi: ROI) → None[source]

Encode region of interest to HDF5 group.

This internal method converts a region of interest object into an HDF5 group structure suitable for persistent storage. It handles encoding of ROI type, enclosure type, and geometric data.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
roi (ROI) – Region of interest to encode

_encode_services(h5: File, services: dict[str, ServiceWorkspace]) → None[source]

Encode services to HDF5 file.

Parameters:

h5 (h5py.File) – HDF5 file handle
services (dict[str, ServiceWorkspace]) – Dictionary of service workspaces

_encode_single_image_spec(h5: File, spec: ImageWorkspaceSpec) → None[source]

Encode single image specification to HDF5 file.

Parameters:

h5 (h5py.File) – HDF5 file handle
spec (ImageWorkspaceSpec) – Image workspace specification to encode

_encode_tools(h5: File, tools: dict[str, ToolWorkspace]) → None[source]

Encode tools to HDF5 file.

Parameters:

h5 (h5py.File) – HDF5 file handle
tools (dict[str, ToolWorkspace]) – Dictionary of tool workspaces

_encode_transform(grp: Group, transform: Transform) → None[source]

Encode transform to HDF5 group.

This internal method converts a transform object into an HDF5 group structure suitable for persistent storage. It handles encoding of transform type and parameters.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
transform (Transform) – Transform to encode

_encode_ui(h5: File, ui: UIWorkspace) → None[source]

Encode UI workspace state to HDF5 group.

This internal method converts the UI workspace state into an HDF5 group structure suitable for persistent storage. It handles encoding of active window ID and all managed windows with their state information.

Parameters:

h5 (h5py.File) – HDF5 file handle
ui (UIWorkspace) – UI workspace state to encode

_encode_value(grp: Group, key: str, value: Any) → None[source]

Encode a value to HDF5 group.

Parameters:

grp (h5py.Group) – HDF5 group to encode to
key (str) – Key for the value
value – Value to encode

_process_attribute(val: Any) → Any[source]: Handles specific type conversions for attributes.

_save_specs(h5: File, name: str, specs: dict[UUID, WorkspaceSpec]) → None[source]

Save workspace specifications to HDF5 file.

Parameters:

h5 (h5py.File) – HDF5 file handle
name (str) – Name of the group to create
specs (dict[UUID, WorkspaceSpec]) – Dictionary of workspace specifications

_validate(h5: File) → None[source]

Validate HDF5 workspace format.

Parameters:: h5 (h5py.File) – HDF5 file handle
Raises:: ValueError – if the file is not a full workspace file

load(path: Path) → Workspace[source]

Load workspace from HDF5 file.

Parameters:: path (Path) – File path to load from
Returns:: Loaded workspace
Return type:: Workspace

save(workspace: Workspace, path: Path) → None[source]

Save workspace to HDF5 file.

Parameters:

workspace (Workspace) – Workspace to save
path (Path) – File path to save to

class radioviz.services.workspace_manager.ImageWorkspaceSpec(id: UUID, source: DataSource, storage: DataStorage, display_parameters: dict[str, Any], metadata: dict[str, Any], data: ndarray | None = None)[source]

Bases: object

Specification for image workspace components.

This data class represents the specification of an image within a workspace, including its data source, storage, display parameters, and metadata.

Variables:

id (UUID) – Unique identifier for the image specification
source (DataSource) – Data source information for the image
storage (DataStorage) – Data storage information for the image
display_parameters (dict[str, Any]) – Display parameters for the image
metadata (dict[str, Any]) – Metadata associated with the image
data (Optional[np.ndarray]) – Image data array (optional)

class radioviz.services.workspace_manager.JSONWorkspaceSerializer[source]

Bases: WorkspaceSerializer

Light workspace serializer (JSON).

This serializer implements workspace serialization using JSON format, suitable for lightweight workspace persistence.

Variables:

FORMAT_VERSION (str) – Format version string
serializer_type (SerializerType) – Serializer type (JSON)

_decode_data_source(data: dict[str, Any]) → DataSource[source]

Decode data source from dictionary format.

Parameters:: data (dict[str, Any]) – Data source data dictionary
Returns:: Decoded data source
Return type:: DataSource

_decode_derivation(d: dict[str, Any]) → SpatialDerivation[source]

Decode spatial derivation from dictionary format.

This internal method reconstructs a spatial derivation object from a dictionary representation. It handles decoding of parent ID, region of interest, and transformation information.

Parameters:: d (dict[str, Any]) – Derivation data dictionary
Returns:: Decoded spatial derivation
Return type:: SpatialDerivation
Raises:: ValueError – when the ROI payload is missing

_decode_image_specs(data: dict[str, Any]) → dict[UUID, ImageWorkspaceSpec][source]

Decode image specifications from dictionary format.

Parameters:: data (dict) – Image specifications data dictionary
Returns:: Decoded image specifications dictionary
Return type:: dict[UUID, ImageWorkspaceSpec]

_decode_roi(r: dict[str, Any]) → ROI[source]

Decode region of interest from dictionary format.

This internal method reconstructs a region of interest object from a dictionary representation. It handles decoding of ROI type, enclosure type, and geometric data.

Parameters:: r (dict[str, Any]) – ROI data dictionary
Returns:: Decoded region of interest
Return type:: ROI

_decode_services(data: dict[str, dict[str, Any]]) → dict[str, ServiceWorkspace][source]

Decode services from dictionary format.

Parameters:: data (dict[str, dict]) – Services data dictionary
Returns:: Decoded services dictionary
Return type:: dict[str, ServiceWorkspace]

_decode_single_image_spec(data: dict[str, Any]) → ImageWorkspaceSpec[source]

Decode single image specification from dictionary format.

Parameters:: data (dict) – Single image specification data dictionary
Returns:: Decoded image workspace specification
Return type:: ImageWorkspaceSpec

_decode_specs(raw: dict[str, Any]) → dict[UUID, WorkspaceSpec][source]

Decode workspace specifications from dictionary format.

Parameters:: raw (dict) – Raw specifications dictionary
Returns:: Decoded specifications dictionary
Return type:: dict[UUID, WorkspaceSpec]

_decode_storage(data: dict[str, Any]) → DataStorage[source]

Decode data storage from dictionary format.

Parameters:: data (dict) – Data storage data dictionary
Returns:: Decoded data storage
Return type:: DataStorage

_decode_tools(data: dict[str, dict[str, Any]]) → dict[str, ToolWorkspace][source]

Decode tools from dictionary format.

Parameters:: data (dict[str, dict]) – Tools data dictionary
Returns:: Decoded tools dictionary
Return type:: dict[str, ToolWorkspace]

_decode_transform(t: dict[str, Any] | None) → Transform | None[source]

Decode transform from dictionary format.

This internal method reconstructs a transform object from a dictionary representation. It handles decoding of transform type and parameters.

Parameters:: t (dict[str, Any] | None) – Transform data dictionary
Returns:: Decoded transform
Return type:: Transform

_decode_ui(data: dict[str, Any] | None) → UIWorkspace[source]

Decode UI workspace state from dictionary format.

This internal method reconstructs the UI workspace state from a dictionary representation. It handles decoding of active window ID and all managed windows with their respective state information.

Parameters:: data (dict[str, Any] | None) – UI workspace data dictionary
Returns:: Decoded UI workspace state
Return type:: UIWorkspace

_decode_workspace(data: dict[str, Any]) → Workspace[source]

Decode workspace from dictionary format.

Parameters:: data (dict) – Workspace data dictionary
Returns:: Decoded workspace
Return type:: Workspace

_encode_data_source(data_source: DataSource) → dict[str, Any][source]

Encode data source to dictionary format.

Parameters:: data_source (DataSource) – Data source to encode
Returns:: Encoded data source dictionary
Return type:: dict

_encode_derivation(derivation: SpatialDerivation) → dict[str, Any][source]

Encode spatial derivation to dictionary format.

This internal method converts a spatial derivation object into a dictionary representation suitable for serialization. It handles encoding of parent ID, region of interest, and transformation information.

Parameters:: derivation (SpatialDerivation) – Spatial derivation to encode
Returns:: Encoded derivation dictionary
Return type:: dict

_encode_display_paramters(params: dict[str, Any]) → dict[str, Any][source]

Encode display parameters to dictionary format.

Parameters:: params (dict) – Display parameters dictionary
Returns:: Encoded display parameters dictionary
Return type:: dict

_encode_image_spec(spec_dict: dict[UUID, ImageWorkspaceSpec]) → dict[str, Any][source]

Encode image specifications dictionary to dictionary format.

Parameters:: spec_dict (dict[UUID, ImageWorkspaceSpec]) – Dictionary of image workspace specifications
Returns:: Encoded image specifications dictionary
Return type:: dict

_encode_roi(roi: ROI) → dict[str, Any][source]

Encode region of interest to dictionary format.

This internal method converts a region of interest object into a dictionary representation suitable for serialization. It handles encoding of ROI type, enclosure type, and geometric data.

Parameters:: roi (ROI) – Region of interest to encode
Returns:: Encoded ROI dictionary
Return type:: dict

_encode_services(services: dict[str, ServiceWorkspace]) → dict[str, Any][source]

Encode services to dictionary format.

Parameters:: services (dict[str, ServiceWorkspace]) – Dictionary of service workspaces
Returns:: Encoded services dictionary
Return type:: dict

_encode_single_image_spec(spec: ImageWorkspaceSpec) → dict[str, Any][source]

Encode single image specification to dictionary format.

Parameters:: spec (ImageWorkspaceSpec) – Image workspace specification to encode
Returns:: Encoded image specification dictionary
Return type:: dict

_encode_specs(specs: dict[UUID, WorkspaceSpec]) → dict[str, Any][source]

Encode workspace specifications to dictionary format.

Parameters:: specs (dict[UUID, WorkspaceSpec]) – Dictionary of workspace specifications
Returns:: Encoded specifications dictionary
Return type:: dict

_encode_storage(storage: DataStorage) → dict[str, Any][source]

Encode data storage to dictionary format.

Parameters:: storage (DataStorage) – Data storage to encode
Returns:: Encoded data storage dictionary
Return type:: dict

_encode_tools(tools: dict[str, ToolWorkspace]) → dict[str, Any][source]

Encode tools to dictionary format.

Parameters:: tools (dict[str, ToolWorkspace]) – Dictionary of tool workspaces
Returns:: Encoded tools dictionary
Return type:: dict

_encode_transform(transform: Transform | None) → dict[str, Any][source]

Encode transform to dictionary format.

This internal method converts a transform object into a dictionary representation suitable for serialization. It handles encoding of transform type and parameters.

Parameters:: transform (Transform) – Transform to encode
Returns:: Encoded transform dictionary
Return type:: dict

_encode_ui(ui_ws: UIWorkspace) → dict[str, Any][source]

Encode UI workspace state to dictionary format.

This internal method converts the UI workspace state into a dictionary representation suitable for serialization. It handles encoding of active window ID and all managed windows with their state information.

Parameters:: ui_ws (UIWorkspace) – UI workspace state to encode
Returns:: Encoded UI workspace dictionary
Return type:: dict

_encode_workspace(ws: Workspace) → dict[str, Any][source]

Encode workspace to dictionary format.

Parameters:: ws (Workspace) – Workspace to encode
Returns:: Encoded workspace dictionary
Return type:: dict

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

Validate workspace payload format.

Parameters:: payload (dict) – Workspace payload to validate
Raises:: ValueError – if the payload is not a light workspace file

load(path: Path) → Workspace[source]

Load workspace from JSON file.

Parameters:: path (Path) – File path to load from
Returns:: Loaded workspace
Return type:: Workspace
Raises:: ValueError – if the file is not a light workspace file

save(workspace: Workspace, path: Path) → None[source]

Save workspace to JSON file.

Parameters:

workspace (Workspace) – Workspace to save
path (Path) – File path to save to

class radioviz.services.workspace_manager.RadiovizEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: JSONEncoder

Custom JSON encoder for Radioviz data types.

This encoder handles serialization of custom data types like NumPy arrays, UUIDs, and other non-standard JSON types.

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float, bool or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII and non-printable characters escaped. If ensure_ascii is false, the output can contain non-ASCII and non-printable characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(obj: Any) → Any[source]

Encode objects to JSON-serializable format.

Parameters:: obj – Object to encode
Returns:: JSON-serializable representation

class radioviz.services.workspace_manager.SerializerType(*values)[source]

Bases: StrEnum

Enumeration of supported serializer types.

This enum defines the available serialization formats for workspace data.

static _generate_next_value_(name, start, count, last_values): Return the lower-cased version of the member name.

class radioviz.services.workspace_manager.ServiceWorkspace(service_id: str, version: str | None = None, state: dict[str, ~typing.Any] = <factory>)[source]

Bases: object

Workspace state for a service component.

This data class represents the workspace state for a specific service, including its identifier, version, and state information.

Variables:

service_id (str) – Identifier for the service
version (str | None) – Version of the service (optional)
state (dict[str, Any]) – State information for the service

class radioviz.services.workspace_manager.ToolWorkspace(tool_id: str, version: str | None = None, items: dict[~uuid.UUID, ~radioviz.services.workspace_manager.WorkspaceSpec] = <factory>, order: list[~uuid.UUID] = <factory>, state: dict[str, ~typing.Any] = <factory>)[source]

Bases: object

Workspace state for a single tool.

This data class represents the workspace state for a specific tool, including its identifier, version, items, execution order, and state information.

Variables:

tool_id (str) – Identifier for the tool
version (str | None) – Version of the tool (optional)
items (dict[UUID, WorkspaceSpec]) – Dictionary mapping UUIDs to workspace specifications
order (list[UUID]) – Execution order of items
state (dict[str, Any]) – State information for the tool

class radioviz.services.workspace_manager.UIWindowState(window_id: UUID, state: WindowState, z_order: int)[source]

Bases: object

State information for a single UI window.

This data class represents the state of a specific UI window within the workspace, including its unique identifier, current state, and z-order for layering.

Variables:

window_id (UUID) – Unique identifier for the window
state (WindowState) – Current state of the window (normal, minimized, maximized, etc.)
z_order (int) – Z-order value for window layering (higher values appear on top)

class radioviz.services.workspace_manager.UIWorkspace(active_window_id: ~uuid.UUID | None = None, windows: list[~radioviz.services.workspace_manager.UIWindowState] = <factory>)[source]

Bases: object

Workspace state for UI configuration.

This data class represents the complete UI workspace state, including information about the active window and all managed windows.

Variables:

active_window_id (Optional[UUID]) – Unique identifier of the currently active window (optional)
windows (list[UIWindowState]) – List of window state configurations

class radioviz.services.workspace_manager.WindowState(*values)[source]

Bases: StrEnum

Enumeration of window states.

This enum defines the possible states a window can be in within the UI workspace. These states control how windows are displayed and managed in the application interface.

Variables:

Normal (str) – Window is in normal size and position
Minimized (str) – Window is minimized to the taskbar/system tray
Maximized (str) – Window is maximized to fill the screen
FullScreen (str) – Window is in full-screen mode

static _generate_next_value_(name, start, count, last_values): Return the lower-cased version of the member name.

class radioviz.services.workspace_manager.Workspace(version: str, images: dict[~uuid.UUID, ~radioviz.services.workspace_manager.ImageWorkspaceSpec] = <factory>, tools: dict[str, ~radioviz.services.workspace_manager.ToolWorkspace] = <factory>, services: dict[str, ~radioviz.services.workspace_manager.ServiceWorkspace] = <factory>, ui: ~radioviz.services.workspace_manager.UIWorkspace | None = None)[source]

Bases: object

Neutral representation of an analysis workspace.

This data class represents the complete workspace state, including images, tools, services, and UI configuration.

Variables:

version (str) – Version of the workspace format
images (dict[UUID, ImageWorkspaceSpec]) – Dictionary mapping UUIDs to image workspace specifications
tools (dict[str, ToolWorkspace]) – Dictionary mapping tool IDs to tool workspace states
services (dict[str, ServiceWorkspace]) – Dictionary mapping service IDs to service workspace states
ui (dict[str, Any] | None) – UI configuration (optional)

class radioviz.services.workspace_manager.WorkspaceReferenceManager[source]

Bases: object

Runtime context used during workspace reconstruction.

This manager keeps track of objects during workspace reconstruction to resolve references between different workspace components.

Variables:: _objects (dict[UUID, object]) – Dictionary mapping UUIDs to registered objects

Initialize the workspace reference manager.

register(obj_id: UUID | str, obj: object) → None[source]

Register an object with a given ID.

Parameters:

obj_id (UUID | str) – Unique identifier for the object (UUID or string)
obj (object) – Object to register

reset() → None[source]: Clear all registered objects.

resolve(obj_id: UUID | str) → object[source]

Resolve an object by its ID.

Parameters:: obj_id (UUID | str) – Unique identifier for the object (UUID or string)
Returns:: Registered object
Return type:: object
Raises:: KeyError – if the object ID is not found

class radioviz.services.workspace_manager.WorkspaceSerializable(*args, **kwargs)[source]

Bases: Protocol[SpecT]

Protocol for objects that can be serialized to workspace specifications.

Objects implementing this protocol can be converted to and from workspace specifications, enabling persistence and reconstruction of workspace state.

Parameters:: SpecT – Type parameter representing the workspace specification type

classmethod from_workspace(spec: SpecT, context: WorkspaceReferenceManager) → object[source]

Create an instance from a workspace specification.

Parameters:

spec (SpecT) – Workspace specification to reconstruct from
context (WorkspaceReferenceManager) – Runtime context for workspace reconstruction

Returns:

Reconstructed object instance

Return type:

object

to_workspace(*args: Any, **kwargs: Any) → SpecT[source]

Convert this object to a workspace specification.

Parameters:

args – Additional positional arguments
kwargs – Additional keyword arguments

Returns:

Workspace specification representation

Return type:

SpecT

class radioviz.services.workspace_manager.WorkspaceSerializableTool(*args, **kwargs)[source]

Bases: Protocol[SpecT]

Base class for workspace serializable tools.

This class extends the WorkspaceSerializable protocol to provide a base implementation for tools that need to be serialized to workspace format.

classmethod from_workspace(spec: SpecT, context: WorkspaceReferenceManager) → object[source]

Create an instance from a workspace specification.

Parameters:

spec (SpecT) – Workspace specification to reconstruct from
context (WorkspaceReferenceManager) – Runtime context for workspace reconstruction

Returns:

Reconstructed object instance

Return type:

object

restore_phase() → int[source]

The phase in which this tool should be restored.

This method returns an integer value defining the order in which different tools should be restored. Tools having the same restore phase number will be restored in parallel.

If your tool needs to have the output of another tool available in order to be restored, just make this method returning a value that is greater than the dependant tool.

to_workspace(*args: Any, **kwargs: Any) → SpecT[source]

Convert this object to a workspace specification.

Parameters:

args – Additional positional arguments
kwargs – Additional keyword arguments

Returns:

Workspace specification representation

Return type:

SpecT

class radioviz.services.workspace_manager.WorkspaceSerializer[source]

Bases: ABC

Abstract base class for workspace serializers.

This abstract base class defines the interface for workspace serializers that can save and load workspace state to/from various formats.

Variables:: serializer_type (SerializerType) – The type of serializer (JSON or HDF5)

abstract load(path: Path) → Workspace[source]

Load workspace from a file.

Parameters:: path (Path) – File path to load from
Returns:: Loaded workspace
Return type:: Workspace

abstract save(workspace: Workspace, path: Path) → None[source]

Save workspace to a file.

Parameters:

workspace (Workspace) – Workspace to save
path (Path) – File path to save to

class radioviz.services.workspace_manager.WorkspaceSpec(*args, **kwargs)[source]

Bases: Protocol

Marker protocol for all workspace specs.

This protocol serves as a marker interface for workspace specification objects that can be serialized and deserialized within the workspace management system.

radioviz.services.workspace_manager.enforce_uuid(value: UUID | str) → UUID[source]

Convert a UUID or string representation to a UUID object.

This utility function ensures that a given value is returned as a UUID object, converting from string representation if necessary.

Parameters:: value (UUID | str) – UUID object or string representation of a UUID
Returns:: UUID object
Return type:: UUID

radioviz.services.workspace_manager.workspace_spec_as_mapping(spec: WorkspaceSpec) → Mapping[str, Any][source]: Normalize a workspace specification to a mapping.