radioviz.models.overlays

Module for managing overlays in radioviz plots.

This module provides functionality for creating, managing, and rendering overlays on matplotlib axes. Overlays can represent various graphical elements such as annotations, shapes, or highlights that are added to plots dynamically.

The module includes: - Overlay models for defining overlay properties - Factory for registering overlay renderers - Manager for handling overlay lifecycle - Renderer for drawing overlays on axes

Module Attributes

RendererFn

Type alias for overlay renderer functions.

Functions

draw_text_overlay(overlay, axes)

Draw a text overlay on the given matplotlib axes.

Classes

OverlayFactory()	Factory for creating and managing overlay renderers.
OverlayKey(owner_id, role)	Key for identifying overlays.
OverlayManager()	Manager for handling overlay lifecycle events.
OverlayModel(id, type, role, label, ...)	Model representing an overlay in the visualization.
OverlayRenderer(canvas, axes, factory)	Renderer for drawing overlays on matplotlib axes.
OverlayRole(*values)	Enumeration of overlay roles.
OverlaySpec(overlay_type, overlay_role, renderer)	Specification for overlay registration.

class radioviz.models.overlays.OverlayFactory

Bases: object

Factory for creating and managing overlay renderers.

This factory maintains a registry of overlay renderers and provides mechanisms to retrieve them based on overlay type and role.

Initialize the overlay factory.

get_renderer(overlay_type: str, overlay_role: OverlayRole) → Callable[[OverlayModel, Axes], list[Artist]]

Get the renderer function for an overlay type and role.

Parameters:

• overlay_type (str) – Type of the overlay

• overlay_role (OverlayRole) – Role of the overlay

Returns:

The renderer function for this overlay type and role

Return type:

RendererFn

Raises:

RuntimeError – if no renderer is registered for the given type and role

register(spec: OverlaySpec | str, overlay_role: OverlayRole | str | None = None, renderer: Callable[[OverlayModel, Axes], list[Artist]] | None = None) → None

Register an overlay specification.

Parameters:

spec (OverlaySpec) – Overlay specification to register

register_default_overlays() → None

Register default overlay specifications.

Registers default overlay specifications for text overlays with all roles. This ensures that basic text overlay functionality is available out-of-the-box.

class radioviz.models.overlays.OverlayKey(owner_id: UUID, role: OverlayRole)

Bases: object

Key for identifying overlays.

Used to uniquely identify overlays based on their owner ID and role.

owner_id: UUID

UUID of the overlay owner.

role: OverlayRole

Role of the overlay.

class radioviz.models.overlays.OverlayManager

Bases: QObject

Manager for handling overlay lifecycle events.

This class manages the addition, removal, and updating of overlays, emitting signals when these operations occur.

Initialize the overlay manager.

add(target_axis_name: str, overlay: OverlayModel) → None

Add an overlay to the manager.

Parameters:

• target_axis_name (str) – Name of the target axis

• overlay (OverlayModel) – Overlay model to add

add_highlight(overlay_id: UUID) → None

Add a highlight overlay for an existing permanent overlay.

Parameters:

overlay_id (UUID) – Unique identifier of the overlay to highlight

Raises:

• RuntimeError – if the permanent overlay does not exist

• ValueError – if the overlay has no target axis assigned

exists(overlay_key: OverlayKey) → bool

Check if an overlay with the given key exists in the manager.

Parameters:

overlay_key (OverlayKey) – The key identifying the overlay to check

Returns:

True if the overlay exists, False otherwise

Return type:

bool

get_overlay(overlay_key: OverlayKey) → OverlayModel | None

Retrieve an overlay by its key.

Parameters:

overlay_key (OverlayKey) – The key identifying the overlay

Returns:

The overlay model if found, None otherwise

Return type:

OverlayModel | None

get_overlay_by_group(group: str) → list[OverlayModel]

Retrieve all overlays belonging to a specific group.

This method filters overlays based on their group attribute and returns a list of overlay models that match the specified group.

Parameters:

group (str) – The group name to filter overlays by

Returns:

List of overlay models belonging to the specified group

Return type:

list[OverlayModel]

get_overlay_by_id(overlay_id: UUID, role: OverlayRole = OverlayRole.Permanent) → OverlayModel | None

Retrieve an overlay by its ID and role.

Parameters:

• overlay_id (UUID) – Unique identifier of the overlay

• role (OverlayRole) – Role of the overlay to retrieve (default: Permanent)

Returns:

The overlay model if found, None otherwise

Return type:

OverlayModel | None

remove(overlay: OverlayModel) → None

Remove an overlay from the manager.

Parameters:

overlay (OverlayModel) – Overlay model to remove

remove_highlight(overlay_id: UUID) → None

Remove a highlight overlay.

Parameters:

overlay_id (UUID) – Unique identifier of the overlay to remove highlight from

remove_id(overlay_id: UUID, role: OverlayRole = OverlayRole.Permanent) → None

Remove an overlay by its ID and role.

Parameters:

• overlay_id (UUID) – Unique identifier of the overlay

• role (OverlayRole) – Role of the overlay to remove (default: Permanent)

set_visibility(overlay_id: UUID, role: OverlayRole, visible: bool) → None

Set the visibility state of an overlay.

Parameters:

• overlay_id (UUID) – Unique identifier of the overlay

• role (OverlayRole) – Role of the overlay to modify

• visible (bool) – New visibility state (True for visible, False for hidden)

toggle_visibility(overlay_key: OverlayKey) → None

Toggle the visibility state of an overlay.

Emits a signal to request toggling the visibility of the overlay identified by the given key.

Parameters:

overlay_key (OverlayKey) – The key identifying the overlay to toggle

update(overlay: OverlayModel) → None

Update an existing overlay.

Parameters:

overlay (OverlayModel) – Overlay model to update

request_to_add_overlay

Signal emitted when an overlay is added. Parameters: axis name, overlay model.

request_to_change_overlay_visibility

Signal emitted to change the visibility of an overlay.

request_to_remove_overlay

Signal emitted when an overlay is removed. Parameter: overlay model.

request_to_toggle_overlay_visibility

Signal emitted to toggle the visibility of an overlay

request_to_update_overlay

Signal emitted when an overlay is updated. Parameter: overlay model.

class radioviz.models.overlays.OverlayModel(id: ~uuid.UUID, type: str | None = '', role: ~radioviz.models.overlays.OverlayRole = OverlayRole.Permanent, label: str | None = None, geometry: dict[str, ~typing.Any] = <factory>, style: dict[str, ~typing.Any] = <factory>, extra_props: dict[str, ~typing.Any] = <factory>, target_axis: str | None = None, group: str | None = None, visible: bool = True)

Bases: object

Model representing an overlay in the visualization.

This class defines the properties of an overlay including its type, role, geometry, style, and target axis.

change_role_to(new_role: OverlayRole) → OverlayModel

Create a copy of this overlay with a different role.

Parameters:

new_role (OverlayRole) – The new role for the overlay

Returns:

A new overlay model with the specified role

Return type:

OverlayModel

extra_props: dict[str, Any]

Additional properties for the overlay.

geometry: dict[str, Any]

Geometry properties of the overlay.

group: str | None = None

The group to which the overlay belongs

id: UUID

Unique identifier for the overlay.

property key: OverlayKey

Get the overlay key.

Returns:

Overlay key composed of owner ID and role

Return type:

OverlayKey

label: str | None = None

Label for the overlay.

role: OverlayRole = 'permanent'

Role of the overlay.

style: dict[str, Any]

Style properties of the overlay.

target_axis: str | None = None

Target axis name where the overlay should be rendered.

type: str | None = ''

Type of the overlay for renderer selection.

visible: bool = True

Whether the overlay is visible or not

class radioviz.models.overlays.OverlayRenderer(canvas: FigureCanvasQTAgg, axes: list[Axes], factory: OverlayFactory)

Bases: QObject

Renderer for drawing overlays on matplotlib axes.

This class handles the actual rendering of overlays onto matplotlib axes using registered renderer functions.

Initialize the overlay renderer.

Parameters:

• canvas (FigureCanvasQTAgg) – Matplotlib figure canvas

• axes (list[plt.Axes]) – List of matplotlib axes

• factory (OverlayFactory) – Overlay factory for retrieving renderers

on_overlay_add(axis_name: str, overlay: OverlayModel, override_role: OverlayRole | None = None) → None

Handle adding an overlay to the plot.

Parameters:

• axis_name (str) – Name of the target axis

• overlay (OverlayModel) – Overlay model to add

• override_role (Optional[OverlayRole]) – Override role for the overlay (optional)

on_overlay_remove(overlay: OverlayModel, override_role: OverlayRole | None = None) → None

Handle removing an overlay from the plot.

Parameters:

• overlay (OverlayModel) – Overlay model to remove

• override_role (Optional[OverlayRole]) – Override role for the overlay (optional)

on_overlay_update(overlay: OverlayModel) → None

Handle updating an overlay in the plot.

Parameters:

overlay (OverlayModel) – Overlay model to update

Raises:

RuntimeError – if the overlay is not found in existing overlays

on_overlay_visibility_change(overlay: OverlayModel, visibility: bool) → None

Handle changing the visibility state of an overlay.

This method updates the visibility of all artists associated with the given overlay. If the overlay is not found in the registered artists, the method returns without making changes.

Parameters:

• overlay (OverlayModel) – The overlay model whose visibility needs to be changed

• visibility (bool) – New visibility state (True for visible, False for hidden)

on_overlay_visibility_toggle(overlay: OverlayModel) → None

Handle toggling the visibility state of an overlay.

This method toggles the visibility of all artists associated with the given overlay. If the overlay is not found in the registered artists, the method returns without making changes.

Parameters:

overlay (OverlayModel) – The overlay model whose visibility needs to be toggled

class radioviz.models.overlays.OverlayRole(*values)

Bases: StrEnum

Enumeration of overlay roles.

Defines different roles that overlays can have in the visualization system.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

Highlight = 'highlight'

Highlight overlay used to emphasize specific elements.

Label = 'label'

Label overlay used to display the name of a specific elements

Permanent = 'permanent'

Permanent overlay that remains visible by default.

Temporary = 'temporary'

Temporary overlay that may be removed after some time.

class radioviz.models.overlays.OverlaySpec(overlay_type: str, overlay_role: OverlayRole, renderer: Callable[[OverlayModel, Axes], list[Artist]])

Bases: object

Specification for overlay registration.

Contains the information needed to register an overlay type with its renderer.

overlay_role: OverlayRole

Role of the overlay.

overlay_type: str

Type identifier for the overlay.

renderer: Callable[[OverlayModel, Axes], list[Artist]]

Renderer function for this overlay type and role.

radioviz.models.overlays.draw_text_overlay(overlay: OverlayModel, axes: Axes) → list[Artist]

Draw a text overlay on the given matplotlib axes.

This function creates a matplotlib Text object using the geometry and style properties from the overlay model and adds it to the specified axes.

Parameters:

• overlay (OverlayModel) – The overlay model containing text properties

• axes (plt.Axes) – The matplotlib axes to draw the text on

Returns:

List containing the created Text artist

Return type:

list[plt.Artist]

radioviz.models.overlays.RendererFn

Type alias for overlay renderer functions.

alias of Callable[[OverlayModel, Axes], list[Artist]]