cellier 0.0.2__py3-none-any.whl

cellier/__init__.py

@@ -0,0 +1,10 @@
+"""A workshop for rendering cellular models."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cellier")
+except PackageNotFoundError:
+    __version__ = "uninstalled"
+__author__ = "Kevin Yamauchi"
+__email__ = "kevin.yamauchi@gmail.com"

cellier/convenience/__init__.py

@@ -0,0 +1,4 @@
+"""Functionalities to make building viewers easier.
+
+This module will likely get pulled out into a separate package.
+"""

cellier/convenience/qt/__init__.py

@@ -0,0 +1 @@
+"""Convenience module for making Qt GUIs."""

cellier/convenience/qt/qt_viewer.py

@@ -0,0 +1,43 @@
+"""Qt widget for the viewer."""
+
+from typing import Dict
+
+from qtpy.QtWidgets import QVBoxLayout, QWidget
+from wgpu.gui.qt import WgpuCanvas
+
+from cellier.models.viewer import ViewerModel
+
+
+class QtViewer(QWidget):
+    """Qt widget for the viewer.
+
+    This contains all the canvases and the dim sliders.
+    """
+
+    def __init__(self, viewer_model: ViewerModel, parent=None) -> None:
+        super().__init__(parent=parent)
+
+        # make the canvas widgets
+        canvas_widgets = {}
+        for scene_model in viewer_model.scenes.scenes:
+            for canvas_model in scene_model.canvases:
+                canvas_widgets[canvas_model.id] = WgpuCanvas(parent=self)
+        self._canvases = canvas_widgets
+
+        # make the layout
+        self.setLayout(QVBoxLayout())
+        for canvas_widget in self._canvases.values():
+            # add the canvas widgets
+            self.layout().addWidget(canvas_widget)
+
+    @property
+    def canvases(self) -> Dict[str, WgpuCanvas]:
+        """The canvas widgets.
+
+        Returns
+        -------
+        Dict[str, WgpuCanvas]
+            Dictionary where the keys are the canvas IDs and
+            the values are the canvas widgets.
+        """
+        return self._canvases

cellier/events/__init__.py

@@ -0,0 +1,5 @@
+"""Infrastructure for the events system."""
+
+from cellier.events._event_bus import EventBus
+
+__all__ = ["EventBus"]

cellier/events/_event_bus.py

@@ -0,0 +1,25 @@
+"""Class to manage connecting events between the model and the view."""
+
+import logging
+
+from cellier.events._visual import VisualEventBus
+
+logger = logging.getLogger(__name__)
+
+
+class EventBus:
+    """Class to manage connecting events between the model and the view.
+
+    There are three types of events:
+        - visual: communicate changes to the visual model state.
+        - visual_controls: communicate changes to the visual gui state.
+    """
+
+    def __init__(self):
+        # the signals for each visual model
+        self._visual_bus = VisualEventBus()
+
+    @property
+    def visual(self) -> VisualEventBus:
+        """Return the visual events."""
+        return self._visual_bus

cellier/events/_visual.py

@@ -0,0 +1,175 @@
+"""Class to manage connecting events between the visual model and the view."""
+
+import logging
+from typing import Any, Callable
+
+from psygnal import EmissionInfo, Signal, SignalInstance
+
+from cellier.types import VisualType
+
+logger = logging.getLogger(__name__)
+
+
+class VisualEventBus:
+    """Class to manage connecting events for the visual models.
+
+    There are three types of events:
+        - visual: communicate changes to the visual model state.
+        - visual_controls: communicate changes to the visual gui state.
+    """
+
+    def __init__(self):
+        # the signals for each visual model that has been registered
+        self._visual_model_signals: dict[str, SignalInstance] = {}
+
+        # the signals for each visual control that has been registered
+        self._visual_control_signals: dict[str, SignalInstance] = {}
+
+    @property
+    def model_signals(self) -> dict[str, SignalInstance]:
+        """Return the signals for each registered visual model.
+
+        The dictionary key is the visual model ID and the value is the SignalInstance.
+        """
+        return self._visual_model_signals
+
+    @property
+    def control_signals(self) -> dict[str, SignalInstance]:
+        """Return the signals for each registered visual control.
+
+        The dictionary key is the visual model ID and the value is
+        the SignalInstance.
+        """
+        return self._visual_control_signals
+
+    def register_visual(self, visual: VisualType):
+        """Register a visual with the event bus.
+
+        This will create a signal on the event bus that will be
+        emitted when the visual model updates. Other components (e.g., GUI)
+        can register to this signal to be notified of changes via the
+        subscribe_to_visual() method.
+
+        Parameters
+        ----------
+        visual : VisualType
+            The visual model to register.
+        """
+        if visual.id in self.model_signals:
+            logging.info(f"Visual {visual.id} is already registered.")
+            return
+        # connect all events to the visual model update handler
+        visual.events.all.connect(self._on_visual_model_update)
+
+        # initialize the visual model callbacks
+        self.model_signals[visual.id] = SignalInstance(
+            name=visual.id, check_nargs_on_connect=False, check_types_on_connect=False
+        )
+
+    def subscribe_to_visual(self, visual_id: str, callback: Callable):
+        """Subscribe to an event on a visual model.
+
+        Parameters
+        ----------
+        visual_id : str
+            The ID of the visual model to subscribe to.
+        callback : Callable
+            The callback to call when the visual model updates.
+        """
+        try:
+            visual_model_signal = self.model_signals[visual_id]
+        except KeyError:
+            raise ValueError(f"Visual {visual_id} is not registered.") from None
+
+        # connect the visual model signal
+        visual_model_signal.connect(callback)
+
+    def register_controls(self, visual_id: str, signal: SignalInstance):
+        """Register a visual control with the event bus.
+
+        This creates a signal on the event bus that will be emitted when
+        the visual control updates. Visual models can subscribe to this
+        signal to be notified of changes.
+
+        Parameters
+        ----------
+        visual_id : str
+            The ID of the visual model to register the control for.
+        signal : SignalInstance
+            The signal to register.
+        """
+        if visual_id not in self.control_signals:
+            # If we haven't registered this visual_id yet, create the signal
+            self.control_signals[visual_id] = SignalInstance(
+                name=visual_id,
+                check_nargs_on_connect=False,
+                check_types_on_connect=False,
+            )
+        # connect the visual control signal
+        signal.connect(self._on_visual_control_update)
+
+    def subscribe_to_controls(self, visual_id: str, callback: Callable):
+        """Subscribe to the event emitted when the visual controls are updated."""
+        try:
+            visual_control_signal = self.control_signals[visual_id]
+        except KeyError:
+            raise ValueError(f"Visual {visual_id} is not registered.") from None
+
+        # connect the visual control signal
+        visual_control_signal.connect(callback)
+
+    def _on_visual_model_update(self, event: EmissionInfo):
+        """Handle a visual model update event.
+
+        This emits a dictionary containing the visual id and
+        the updated property values.
+        """
+        # get the sender
+        emitter_object = Signal.sender()
+
+        try:
+            signal = self.model_signals[emitter_object.id]
+        except KeyError:
+            logger.debug(
+                f"EventBus received event from visual model {emitter_object.id},"
+                "but the model is not registered"
+            )
+
+        # dictionary with the updated state
+        property_name = event.signal.name
+        property_value = event.args[0]
+        new_state = {"id": emitter_object.id, property_name: property_value}
+        signal.emit(new_state)
+
+    def _on_visual_control_update(self, event: Any | None = None):
+        """Handle a visual control update event.
+
+        The update dictionary must include the following keys:
+        - id: the id of the visual model
+        - controls_update_callback: the visual control's update callback that
+                                    should be blocked when updating the visual model.
+                                    this prevents the update from bouncing back
+                                    to the GUI.
+        """
+        visual_id = event["id"]
+        try:
+            control_signal = self.control_signals[visual_id]
+        except KeyError:
+            logger.debug(
+                f"EventBus received event from visual model {visual_id},"
+                "but the model is not registered"
+            )
+
+        callback_to_block = event.pop("controls_update_callback")
+
+        # update the visual model
+        if visual_id in self._visual_control_signals:
+            # block the gui update callback so the signal doesn't bounce back
+            visual_signal = self.model_signals[visual_id]
+
+            # emit the event and temporarily disconnect the callback
+            visual_signal.disconnect(callback_to_block, missing_ok=True)
+            control_signal.emit(event)
+            visual_signal.connect(callback_to_block)
+        else:
+            control_signal.emit(event)

cellier/gui/__init__.py

@@ -0,0 +1 @@
+"""GUI related functions."""

cellier/gui/constants.py

@@ -0,0 +1,9 @@
+"""Constants for the GUI."""
+
+from enum import Enum
+
+
+class GuiFramework(Enum):
+    """Enum for supported GUI frameworks."""
+
+    QT = "qt"

cellier/gui/qt/__init__.py

@@ -0,0 +1 @@
+"""Qt GUI related functions."""

cellier/gui/qt/utils.py

@@ -0,0 +1,36 @@
+"""Utility functions for generating Qt widgets."""
+
+from typing import Dict, Optional
+
+from qtpy.QtWidgets import QWidget
+from wgpu.gui.qt import WgpuCanvas
+
+from cellier.models.viewer import ViewerModel
+
+
+def construct_qt_canvases_from_model(
+    viewer_model: ViewerModel, parent: Optional[QWidget] = None
+) -> Dict[str, WgpuCanvas]:
+    """Construct Qt PyGFX canvas widgets from the viewer model.
+
+    Parameters
+    ----------
+    viewer_model : ViewerModel
+        The viewer model to construct the Qt canvases from.
+
+    parent : Optional[QWidget]
+        The parent for the constructed Qt canvases.
+        Default value is None.
+
+    Returns
+    -------
+    Dict[str, WgpuCanvas]
+        A dictionary where the canvas IDs are the keys and
+        The constructed Qt canvases are the values.
+    """
+    canvas_widgets = {}
+    for scene_model in viewer_model.scenes.scenes.values():
+        for canvas_model in scene_model.canvases.values():
+            canvas_widgets[canvas_model.id] = WgpuCanvas(parent=parent)
+
+    return canvas_widgets

cellier/models/__init__.py

@@ -0,0 +1 @@
+"""Models to express the viewer state."""

cellier/models/data_manager.py

@@ -0,0 +1,45 @@
+"""Class to hold all of the data stores and streams."""
+
+from typing import Dict, Union
+
+from psygnal import EventedModel
+from pydantic import Field
+from typing_extensions import Annotated
+
+from cellier.models.data_stores.points import PointsMemoryStore
+
+# types for discrimitive unions
+DataStoreType = Annotated[
+    Union[PointsMemoryStore,],
+    Field(discriminator="store_type"),
+]
+
+
+class DataManager(EventedModel):
+    """Class to model all data_stores in the viewer.
+
+    todo: add discrimitive union
+
+    Attributes
+    ----------
+    stores : Dict[str, DataStoreType]
+        The data stores in the viewer.
+        The key to the store is the data store id.
+
+    """
+
+    stores: Dict[str, DataStoreType]
+
+    def add_data_store(self, data_store: DataStoreType):
+        """Add a data store to the viewer.
+
+        Parameters
+        ----------
+        data_store : DataStoreType
+            The data store to add to the viewer.
+
+        """
+        self.stores[data_store.id] = data_store
+
+        # emit event to signal that the data has been updated
+        self.events.stores.emit()

cellier/models/data_stores/__init__.py

@@ -0,0 +1,6 @@
+"""Models for the DataStore classes."""
+
+from cellier.models.data_stores.lines import LinesMemoryStore
+from cellier.models.data_stores.points import PointsMemoryStore
+
+__all__ = ["LinesMemoryStore", "PointsMemoryStore"]

cellier/models/data_stores/base_data_store.py

@@ -0,0 +1,36 @@
+"""Base Data Store classes."""
+
+from dataclasses import dataclass
+from uuid import uuid4
+
+from psygnal import EventedModel
+from pydantic import Field
+
+
+class BaseDataStore(EventedModel):
+    """The base class for all DataStores.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier for the data store.
+        The default value is a UUID4 generated hex string.
+
+    Attributes
+    ----------
+    id : str
+        The unique identifier for the data store.
+    """
+
+    # store a UUID to identify this specific scene.
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    name: str = "data store"
+
+
+@dataclass(frozen=True)
+class DataStoreSlice:
+    """Base class for all data store slices."""
+
+    scene_id: str
+    visual_id: str
+    resolution_level: int

cellier/models/data_stores/lines.py

@@ -0,0 +1,84 @@
+"""Classes for lines DataStores."""
+
+from typing import Literal
+
+import numpy as np
+from pydantic import ConfigDict, field_serializer, field_validator
+from pydantic_core.core_schema import ValidationInfo
+
+from cellier.models.data_stores.base_data_store import BaseDataStore
+from cellier.slicer.data_slice import DataSliceRequest, RenderedLinesDataSlice
+
+
+class BaseLinesDataStore(BaseDataStore):
+    """The base class for all lines data_stores.
+
+    todo: properly set up. this shouldn't specify ndarrays.
+    """
+
+    coordinates: np.ndarray
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @field_validator("coordinates", mode="before")
+    @classmethod
+    def coerce_to_ndarray_float32(cls, v: str, info: ValidationInfo):
+        """Coerce to a float32 numpy array."""
+        if not isinstance(v, np.ndarray):
+            v = np.asarray(v, dtype=np.float32)
+        return v.astype(np.float32)
+
+
+class LinesMemoryStore(BaseLinesDataStore):
+    """Point data_stores store for arrays stored in memory."""
+
+    # this is used for a discriminated union
+    store_type: Literal["lines_memory"] = "lines_memory"
+
+    @field_serializer("coordinates")
+    def serialize_ndarray(self, array: np.ndarray, _info) -> list:
+        """Coerce numpy arrays into lists for serialization."""
+        return array.tolist()
+
+    def get_slice(self, slice_data: DataSliceRequest) -> RenderedLinesDataSlice:
+        """Get the data required to render a slice of the mesh.
+
+        todo: generalize to oblique slicing
+        """
+        displayed_dimensions = list(slice_data.world_slice.displayed_dimensions)
+        points_ndim = self.coordinates.shape[1]
+
+        # get a mask for the not displayed dimensions
+        not_displayed_mask = np.ones((points_ndim,), dtype=bool)
+        not_displayed_mask[displayed_dimensions] = False
+
+        # get the range to include
+        point = np.asarray(slice_data.world_slice.point)
+        margin_negative = np.asarray(slice_data.world_slice.margin_negative)
+        margin_positive = np.asarray(slice_data.world_slice.margin_positive)
+        low = point - margin_negative
+        high = point + margin_positive
+
+        # get the components of the range from the not displayed dimensions
+        not_displayed_low = low[not_displayed_mask]
+        not_displayed_high = high[not_displayed_mask]
+
+        # find the coordinates inside the slice
+        not_displayed_coordinates = self.coordinates[:, not_displayed_mask]
+
+        inside_slice_mask = np.all(
+            (not_displayed_coordinates >= not_displayed_low)
+            & (not_displayed_coordinates <= not_displayed_high),
+            axis=1,
+        )
+
+        in_slice_coordinates = np.atleast_2d(
+            self.coordinates[inside_slice_mask, :][:, displayed_dimensions]
+        )
+
+        return RenderedLinesDataSlice(
+            scene_id=slice_data.scene_id,
+            visual_id=slice_data.visual_id,
+            resolution_level=slice_data.resolution_level,
+            coordinates=in_slice_coordinates,
+        )

cellier/models/data_stores/points.py

@@ -0,0 +1,84 @@
+"""Classes for Point DataStores."""
+
+from typing import Literal
+
+import numpy as np
+from pydantic import ConfigDict, field_serializer, field_validator
+from pydantic_core.core_schema import ValidationInfo
+
+from cellier.models.data_stores.base_data_store import BaseDataStore
+from cellier.slicer.data_slice import DataSliceRequest, RenderedPointsDataSlice
+
+
+class BasePointsDataStore(BaseDataStore):
+    """The base class for all point data_stores.
+
+    todo: properly set up. this shouldn't specify ndarrays.
+    """
+
+    coordinates: np.ndarray
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @field_validator("coordinates", mode="before")
+    @classmethod
+    def coerce_to_ndarray_float32(cls, v: str, info: ValidationInfo):
+        """Coerce to a float32 numpy array."""
+        if not isinstance(v, np.ndarray):
+            v = np.asarray(v, dtype=np.float32)
+        return v.astype(np.float32)
+
+
+class PointsMemoryStore(BasePointsDataStore):
+    """Point data_stores store for arrays stored in memory."""
+
+    # this is used for a discriminated union
+    store_type: Literal["points_memory"] = "points_memory"
+
+    @field_serializer("coordinates")
+    def serialize_ndarray(self, array: np.ndarray, _info) -> list:
+        """Coerce numpy arrays into lists for serialization."""
+        return array.tolist()
+
+    def get_slice(self, slice_data: DataSliceRequest) -> RenderedPointsDataSlice:
+        """Get the data required to render a slice of the mesh.
+
+        todo: generalize to oblique slicing
+        """
+        displayed_dimensions = list(slice_data.world_slice.displayed_dimensions)
+        points_ndim = self.coordinates.shape[1]
+
+        # get a mask for the not displayed dimensions
+        not_displayed_mask = np.ones((points_ndim,), dtype=bool)
+        not_displayed_mask[displayed_dimensions] = False
+
+        # get the range to include
+        point = np.asarray(slice_data.world_slice.point)
+        margin_negative = np.asarray(slice_data.world_slice.margin_negative)
+        margin_positive = np.asarray(slice_data.world_slice.margin_positive)
+        low = point - margin_negative
+        high = point + margin_positive
+
+        # get the components of the range from the not displayed dimensions
+        not_displayed_low = low[not_displayed_mask]
+        not_displayed_high = high[not_displayed_mask]
+
+        # find the coordinates inside the slice
+        not_displayed_coordinates = self.coordinates[:, not_displayed_mask]
+
+        inside_slice_mask = np.all(
+            (not_displayed_coordinates >= not_displayed_low)
+            & (not_displayed_coordinates <= not_displayed_high),
+            axis=1,
+        )
+
+        in_slice_coordinates = np.atleast_2d(
+            self.coordinates[inside_slice_mask, :][:, displayed_dimensions]
+        )
+
+        return RenderedPointsDataSlice(
+            scene_id=slice_data.scene_id,
+            visual_id=slice_data.visual_id,
+            resolution_level=slice_data.resolution_level,
+            coordinates=in_slice_coordinates,
+        )

cellier/models/scene/__init__.py

@@ -0,0 +1,15 @@
+"""Models for the scene objects."""
+
+from cellier.models.scene.cameras import OrthographicCamera, PerspectiveCamera
+from cellier.models.scene.canvas import Canvas
+from cellier.models.scene.dims_manager import CoordinateSystem, DimsManager
+from cellier.models.scene.scene import Scene
+
+__all__ = [
+    "Canvas",
+    "CoordinateSystem",
+    "DimsManager",
+    "OrthographicCamera",
+    "PerspectiveCamera",
+    "Scene",
+]