add v2 event bus (#56)

Author: kevinyamauchi

docs/cellier_v2_event_bus_design.md

@@ -17,6 +17,7 @@
 --------
 Mouse                  — orbit / zoom at any time
 Update btn             — freeze camera, plan, submit async commit task
+Colormap btn           — toggle between viridis and gray (live, no Update needed)
 Frustum cull checkbox  — enable / disable brick culling
 Show frustum checkbox  — toggle wireframe visibility (no pipeline re-run)
 Auto / 1 / 2 / 3 radio — select force-level
@@ -32,6 +33,7 @@
 import pathlib
 import sys
 import time
+from typing import ClassVar
 
 import numpy as np
 import pygfx as gfx
@@ -149,11 +151,14 @@ def make_frustum_wireframe(corners: np.ndarray, color: str = "#00cc44") -> gfx.L
 class MainWindow(QMainWindow):
     """PySide6 main window using CellierController."""
 
+    _COLORMAPS: ClassVar[list[str]] = ["viridis", "gray"]
+
     def __init__(self, data_store: MultiscaleZarrDataStore) -> None:
         super().__init__()
         self._frustum_line: gfx.Line | None = None
         self._update_count = 0
         self._force_level: int | None = None
+        self._colormap_index: int = 0  # index into _COLORMAPS
 
         self._controller = CellierController(widget_parent=self)
         cs = CoordinateSystem(name="world", axis_labels=("z", "y", "x"))
@@ -209,6 +214,12 @@ def _setup_ui(self, canvas_widget: QWidget) -> None:
         )
         panel_layout.addWidget(self._update_btn)
 
+        self._colormap_btn = QPushButton(
+            f"Colormap: {self._COLORMAPS[self._colormap_index]}"
+        )
+        self._colormap_btn.clicked.connect(self._on_toggle_colormap)
+        panel_layout.addWidget(self._colormap_btn)
+
         self._frustum_cull_cb = QCheckBox("Frustum cull")
         self._frustum_cull_cb.setChecked(True)
         panel_layout.addWidget(self._frustum_cull_cb)
@@ -270,6 +281,13 @@ def _on_far_plane_changed(self, value: float) -> None:
             depth_range=(1.0, value),
         )
 
+    def _on_toggle_colormap(self) -> None:
+        self._colormap_index = (self._colormap_index + 1) % len(self._COLORMAPS)
+        new_cmap = self._COLORMAPS[self._colormap_index]
+        self._visual.appearance.color_map = new_cmap
+        self._colormap_btn.setText(f"Colormap: {new_cmap}")
+        print(f"[colormap] switched to '{new_cmap}'")
+
     # ── Update button handler ───────────────────────────────────────────
 
     async def _on_update_clicked(self) -> None:

docs/cellier_v2_eventbus_implementation_plan.md

@@ -0,0 +1,25 @@
+"""Shared immutable state snapshots — used by events and render layer."""
+
+from __future__ import annotations
+
+from typing import Literal, NamedTuple
+
+
+class DimsState(NamedTuple):
+    """Current dimension display state for a scene."""
+
+    displayed_axes: tuple[int, ...]
+    slice_indices: tuple[int, ...]
+
+
+class CameraState(NamedTuple):
+    """Immutable snapshot of the active camera's logical state."""
+
+    camera_type: Literal["perspective", "orthographic"]
+    position: tuple[float, float, float]
+    rotation: tuple[float, float, float, float]
+    up: tuple[float, float, float]
+    fov: float
+    zoom: float
+    extent: tuple[float, float]
+    depth_range: tuple[float, float]

scripts/v2/lut_texture_multiscale_frustum_async_cellier/example_cellier.py

@@ -2,10 +2,20 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Callable
 from uuid import UUID, uuid4
 
-from cellier.v2.render._requests import DimsState
+from cellier.v2._state import DimsState
+from cellier.v2.events import (
+    AppearanceChangedEvent,
+    CameraChangedEvent,
+    DimsChangedEvent,
+    EventBus,
+    SceneAddedEvent,
+    SubscriptionHandle,
+    VisualAddedEvent,
+    VisualVisibilityChangedEvent,
+)
 from cellier.v2.render._scene_config import VisualRenderConfig
 from cellier.v2.render.render_manager import RenderManager
 from cellier.v2.render.visuals._image import GFXMultiscaleImageVisual
@@ -19,12 +29,18 @@
 if TYPE_CHECKING:
     import pathlib
 
+    from psygnal import EmissionInfo
     from PySide6.QtWidgets import QWidget
 
+    from cellier.v2._state import CameraState
     from cellier.v2.data._base_data_store import BaseDataStore
     from cellier.v2.visuals._image import ImageAppearance
 
 
+# Appearance fields that require a reslice (not just a GPU material update).
+_RESLICE_FIELDS: frozenset[str] = frozenset({"lod_bias", "force_level", "frustum_cull"})
+
+
 class CellierController:
     """The main class for constructing and controlling a cellier visualization.
 
@@ -41,6 +57,13 @@ def __init__(self, widget_parent: QWidget | None = None) -> None:
         self._canvas_to_scene: dict[UUID, UUID] = {}
         # Forward map: scene_id → list[canvas_id]
         self._scene_to_canvases: dict[UUID, list[UUID]] = {}
+        # Event bus
+        self._id: UUID = uuid4()
+        self._event_bus: EventBus = EventBus()
+        # Cache of last-known displayed_axes per scene for change detection
+        self._dims_cache: dict[UUID, tuple[int, ...]] = {}
+        # Handles for externally-registered callbacks
+        self._external_handles: list[SubscriptionHandle] = []
 
     def set_widget_parent(self, parent: QWidget) -> None:
         """Set the Qt parent for subsequently created canvas widgets."""
@@ -145,6 +168,8 @@ def add_scene(
         self._model.scenes[scene.id] = scene
         self._render_manager.add_scene(scene.id, dim=dim)
         self._scene_to_canvases[scene.id] = []
+        self._wire_dims_model(scene)
+        self._event_bus.emit(SceneAddedEvent(source_id=self._id, scene_id=scene.id))
         return scene
 
     # ------------------------------------------------------------------
@@ -246,7 +271,26 @@ def add_image(
 
         self._render_manager.add_visual(scene_id, gfx_visual, data)
         self._visual_to_scene[visual_model.id] = scene_id
-
+        self._wire_appearance(visual_model)
+        self._event_bus.subscribe(
+            AppearanceChangedEvent,
+            gfx_visual.on_appearance_changed,
+            entity_id=visual_model.id,
+            owner_id=visual_model.id,
+        )
+        self._event_bus.subscribe(
+            VisualVisibilityChangedEvent,
+            gfx_visual.on_visibility_changed,
+            entity_id=visual_model.id,
+            owner_id=visual_model.id,
+        )
+        self._event_bus.emit(
+            VisualAddedEvent(
+                source_id=self._id,
+                scene_id=scene_id,
+                visual_id=visual_model.id,
+            )
+        )
         return visual_model
 
     def add_visual(
@@ -417,6 +461,69 @@ def _dims_state_for_scene(self, scene_id: UUID) -> DimsState:
             slice_indices=dims.slice_indices,
         )
 
+    # ------------------------------------------------------------------
+    # psygnal bridges
+    # ------------------------------------------------------------------
+
+    def _wire_dims_model(self, scene: Scene) -> None:
+        """Subscribe to all field changes on a scene's DimsManager."""
+        self._dims_cache[scene.id] = scene.dims.displayed_axes
+        scene.dims.events.connect(self._make_dims_handler(scene.id))
+
+    def _make_dims_handler(self, scene_id: UUID) -> Callable:
+        """Return a psygnal catch-all handler for a scene's DimsManager."""
+
+        def _on_dims_psygnal(info: EmissionInfo) -> None:
+            dims = self._model.scenes[scene_id].dims
+            new_state = DimsState(
+                displayed_axes=dims.displayed_axes,
+                slice_indices=dims.slice_indices,
+            )
+            prev_axes = self._dims_cache[scene_id]
+            displayed_axes_changed = prev_axes != new_state.displayed_axes
+            self._dims_cache[scene_id] = new_state.displayed_axes
+            self._event_bus.emit(
+                DimsChangedEvent(
+                    source_id=self._id,
+                    scene_id=scene_id,
+                    dims_state=new_state,
+                    displayed_axes_changed=displayed_axes_changed,
+                )
+            )
+
+        return _on_dims_psygnal
+
+    def _wire_appearance(self, visual: MultiscaleImageVisual) -> None:
+        """Subscribe to all field changes on a visual's ImageAppearance."""
+        visual.appearance.events.connect(self._make_appearance_handler(visual.id))
+
+    def _make_appearance_handler(self, visual_id: UUID) -> Callable:
+        """Return a psygnal catch-all handler for a visual's ImageAppearance."""
+
+        def _on_appearance_psygnal(info: EmissionInfo) -> None:
+            field_name: str = info.signal.name
+            new_value = info.args[0]
+            if field_name == "visible":
+                self._event_bus.emit(
+                    VisualVisibilityChangedEvent(
+                        source_id=self._id,
+                        visual_id=visual_id,
+                        visible=new_value,
+                    )
+                )
+            else:
+                self._event_bus.emit(
+                    AppearanceChangedEvent(
+                        source_id=self._id,
+                        visual_id=visual_id,
+                        field_name=field_name,
+                        new_value=new_value,
+                        requires_reslice=(field_name in _RESLICE_FIELDS),
+                    )
+                )
+
+        return _on_appearance_psygnal
+
     def reslice_all(self) -> None:
         """Trigger a data load for all visuals across all scenes."""
         for scene_id in self._model.scenes:
@@ -507,12 +614,30 @@ def add_mesh(self, *args, **kwargs):
         raise NotImplementedError("add_mesh is not implemented in Phase 1.")
 
     def remove_scene(self, scene_id: UUID) -> None:
-        """Not implemented in Phase 1."""
-        raise NotImplementedError("remove_scene is not implemented in Phase 1.")
+        """Clean up bus subscriptions for a scene and its canvases.
+
+        Render-layer teardown is not yet implemented.
+        """
+        for canvas_id in self._scene_to_canvases.pop(scene_id, []):
+            self._event_bus.unsubscribe_all(canvas_id)
+            self._canvas_to_scene.pop(canvas_id, None)
+        self._event_bus.unsubscribe_all(scene_id)
+        raise NotImplementedError(
+            "Scene render-layer teardown not yet implemented. "
+            "Bus subscriptions have been cleaned up."
+        )
 
     def remove_visual(self, visual_id: UUID) -> None:
-        """Not implemented in Phase 1."""
-        raise NotImplementedError("remove_visual is not implemented in Phase 1.")
+        """Clean up bus subscriptions for a visual.
+
+        Render-layer teardown is not yet implemented.
+        """
+        self._event_bus.unsubscribe_all(visual_id)
+        self._visual_to_scene.pop(visual_id, None)
+        raise NotImplementedError(
+            "Visual render-layer teardown not yet implemented. "
+            "Bus subscriptions have been cleaned up."
+        )
 
     def remove_data_store(self, data_store_id: UUID) -> None:
         """Not implemented in Phase 1."""
@@ -525,9 +650,46 @@ def get_dims_widget(self, scene_id: UUID, parent: QWidget | None = None):
         """
         raise NotImplementedError("get_dims_widget is not implemented in Phase 1.")
 
-    def on_dims_changed(self, scene_id: UUID, callback) -> None:
-        """Register a callback to be called when dims change.
+    def on_dims_changed(
+        self, scene_id: UUID, callback: Callable[[DimsState], None]
+    ) -> None:
+        """Register a callback fired whenever the dims for *scene_id* change.
 
-        Not implemented in Phase 1.
+        The callback receives a ``DimsState`` snapshot.
         """
-        raise NotImplementedError("on_dims_changed is not implemented in Phase 1.")
+        handle = self._event_bus.subscribe(
+            DimsChangedEvent,
+            lambda e: callback(e.dims_state),
+            entity_id=scene_id,
+            owner_id=self._id,
+        )
+        self._external_handles.append(handle)
+
+    def on_camera_changed(
+        self, scene_id: UUID, callback: Callable[[CameraState], None]
+    ) -> None:
+        """Register a callback fired whenever the camera for *scene_id* changes.
+
+        Camera event wiring is dormant in this phase; the subscription is
+        registered but will never fire until camera events are wired.
+        """
+        handle = self._event_bus.subscribe(
+            CameraChangedEvent,
+            lambda e: callback(e.camera_state),
+            entity_id=scene_id,
+            owner_id=self._id,
+        )
+        self._external_handles.append(handle)
+
+    def on_visual_changed(self, visual_id: UUID, callback: Callable) -> None:
+        """Register a callback fired whenever the appearance of *visual_id* changes.
+
+        The callback receives the live ``MultiscaleImageVisual`` model.
+        """
+        handle = self._event_bus.subscribe(
+            AppearanceChangedEvent,
+            lambda e: callback(self.get_visual_model(e.visual_id)),
+            entity_id=visual_id,
+            owner_id=self._id,
+        )
+        self._external_handles.append(handle)

src/cellier/v2/_state.py

@@ -0,0 +1,43 @@
+"""cellier v2 event bus and event type catalogue."""
+
+from cellier.v2._state import CameraState, DimsState
+from cellier.v2.events._bus import EventBus, SubscriptionHandle
+from cellier.v2.events._events import (
+    AppearanceChangedEvent,
+    CameraChangedEvent,
+    CellierEventTypes,
+    DataStoreContentsChangedEvent,
+    DataStoreMetadataChangedEvent,
+    DimsChangedEvent,
+    FrameRenderedEvent,
+    ResliceCancelledEvent,
+    ResliceCompletedEvent,
+    ResliceStartedEvent,
+    SceneAddedEvent,
+    SceneRemovedEvent,
+    VisualAddedEvent,
+    VisualRemovedEvent,
+    VisualVisibilityChangedEvent,
+)
+
+__all__ = [
+    "EventBus",
+    "SubscriptionHandle",
+    "AppearanceChangedEvent",
+    "CameraChangedEvent",
+    "CameraState",
+    "CellierEventTypes",
+    "DataStoreContentsChangedEvent",
+    "DataStoreMetadataChangedEvent",
+    "DimsChangedEvent",
+    "DimsState",
+    "FrameRenderedEvent",
+    "ResliceCancelledEvent",
+    "ResliceCompletedEvent",
+    "ResliceStartedEvent",
+    "SceneAddedEvent",
+    "SceneRemovedEvent",
+    "VisualAddedEvent",
+    "VisualRemovedEvent",
+    "VisualVisibilityChangedEvent",
+]