|
| 1 | +""" |
| 2 | +ControllerGroup is used to synchronize in time each canvas. |
| 3 | +""" |
| 4 | + |
| 5 | +from typing import Optional, Sequence, Union |
| 6 | + |
| 7 | +from pygfx import Renderer, Viewport |
| 8 | + |
| 9 | + |
| 10 | +class ControllerGroup: |
| 11 | + """ |
| 12 | + Manages a group of plot controllers and synchronizes them. |
| 13 | +
|
| 14 | + Parameters |
| 15 | + ---------- |
| 16 | + plots : Optional[Sequence] |
| 17 | + A sequence of plot objects (each with a `.controller` and `.renderer` attribute). |
| 18 | + Can be None or empty. |
| 19 | + interval : tuple[float | int, float | int] |
| 20 | + Start and end of the epoch (x-axis range) to show when initializing. |
| 21 | + Must be a 2-tuple with start <= end. |
| 22 | + """ |
| 23 | + |
| 24 | + def __init__(self, plots: Optional[Sequence] = None, interval: tuple[Union[int, float], Union[int, float]] = (0, 10)): |
| 25 | + self._controller_group = dict() |
| 26 | + |
| 27 | + # Validate interval format |
| 28 | + if not isinstance(interval, (tuple, list)): |
| 29 | + raise ValueError("`interval` must be a tuple or list.") |
| 30 | + |
| 31 | + if len(interval) != 2 or not all(isinstance(x, (int, float)) for x in interval): |
| 32 | + raise ValueError("`interval` must be a 2-tuple of int or float values.") |
| 33 | + |
| 34 | + if interval[0] > interval[1]: |
| 35 | + raise ValueError("`interval` start must not be greater than end.") |
| 36 | + |
| 37 | + self.interval = interval |
| 38 | + |
| 39 | + # Initialize controller group from given plots |
| 40 | + if plots is not None: |
| 41 | + for i, plt in enumerate(plots): |
| 42 | + plt.controller._controller_id = i |
| 43 | + self._add_update_handler(plt.renderer) |
| 44 | + plt.controller.set_xlim(*interval) |
| 45 | + self._controller_group[i] = plt.controller |
| 46 | + |
| 47 | + def _add_update_handler(self, viewport_or_renderer: Union[Viewport, Renderer]): |
| 48 | + """ |
| 49 | + Registers a sync event handler on the renderer of the given viewport or renderer. |
| 50 | + """ |
| 51 | + viewport = Viewport.from_viewport_or_renderer(viewport_or_renderer) |
| 52 | + viewport.renderer.add_event_handler(self.sync_controllers, "sync") |
| 53 | + |
| 54 | + def sync_controllers(self, event): |
| 55 | + """ |
| 56 | + Synchronizes all other controllers in the group when a sync event is triggered. |
| 57 | +
|
| 58 | + Parameters |
| 59 | + ---------- |
| 60 | + event : Event |
| 61 | + The sync event that contains `controller_id` and possibly data to sync. |
| 62 | + """ |
| 63 | + for id_other, ctrl in self._controller_group.items(): |
| 64 | + if event.controller_id != id_other and ctrl.enabled: |
| 65 | + ctrl.sync(event) |
| 66 | + |
| 67 | + def add(self, plot, controller_id: int): |
| 68 | + """ |
| 69 | + Adds a plot to the controller group. |
| 70 | +
|
| 71 | + Parameters |
| 72 | + ---------- |
| 73 | + plot : object |
| 74 | + A base or widget plot with a `.controller` and `.renderer` attribute, |
| 75 | + or a wrapper with `.plot.controller` and `.plot.renderer`. |
| 76 | + controller_id : int |
| 77 | + Unique identifier to assign to the plot's controller in the group. |
| 78 | +
|
| 79 | + Raises |
| 80 | + ------ |
| 81 | + RuntimeError |
| 82 | + If the plot doesn't have a controller/renderer or the ID already exists. |
| 83 | + """ |
| 84 | + # Attempt to extract controller and renderer |
| 85 | + if hasattr(plot, "controller") and hasattr(plot, "renderer"): |
| 86 | + controller = plot.controller |
| 87 | + renderer = plot.renderer |
| 88 | + elif hasattr(plot, "plot") and hasattr(plot.plot, "controller") and hasattr(plot.plot, "renderer"): |
| 89 | + controller = plot.plot.controller |
| 90 | + renderer = plot.plot.renderer |
| 91 | + else: |
| 92 | + raise RuntimeError("Plot object must have a controller and renderer.") |
| 93 | + |
| 94 | + # Prevent duplicate controller IDs |
| 95 | + if controller_id in self._controller_group: |
| 96 | + raise RuntimeError(f"Controller ID {controller_id} already exists in the group.") |
| 97 | + |
| 98 | + # Assign ID if not already assigned |
| 99 | + if controller.controller_id is None: |
| 100 | + controller.controller_id = controller_id |
| 101 | + |
| 102 | + self._controller_group[controller_id] = controller |
| 103 | + self._add_update_handler(renderer) |
| 104 | + |
| 105 | + def remove(self, controller_id: int): |
| 106 | + """ |
| 107 | + Removes a controller from the group by its ID. |
| 108 | +
|
| 109 | + Parameters |
| 110 | + ---------- |
| 111 | + controller_id : int |
| 112 | + The ID of the controller to remove. |
| 113 | +
|
| 114 | + Raises |
| 115 | + ------ |
| 116 | + KeyError |
| 117 | + If the controller_id is not found in the group. |
| 118 | + """ |
| 119 | + if controller_id not in self._controller_group: |
| 120 | + raise KeyError(f"Controller ID {controller_id} not found in the group.") |
| 121 | + |
| 122 | + controller = self._controller_group.pop(controller_id) |
| 123 | + |
| 124 | + # Optional: remove event handler if needed |
| 125 | + # This assumes controller has a reference to its renderer |
| 126 | + try: |
| 127 | + viewport = Viewport.from_viewport_or_renderer(controller.renderer) |
| 128 | + viewport.renderer.remove_event_handler(self.sync_controllers, "sync") |
| 129 | + except Exception: |
| 130 | + # Fallback: skip if removal fails (e.g., missing references) |
| 131 | + pass |
0 commit comments