pymmcore-plus 0.13.7__py3-none-any.whl → 0.15.0__py3-none-any.whl

pymmcore_plus/core/events/_protocol.py

@@ -1,4 +1,15 @@
-from typing import Any, Callable, Optional, Protocol, Union, runtime_checkable
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Protocol,
+    overload,
+    runtime_checkable,
+)
+
+from typing_extensions import Self
 
 
 @runtime_checkable
@@ -12,7 +23,7 @@ class PSignalInstance(Protocol):
     def connect(self, slot: Callable) -> Any:
         """Connect slot to this signal."""
 
-    def disconnect(self, slot: Optional[Callable] = None) -> Any:
+    def disconnect(self, slot: Callable | None = None) -> Any:
         """Disconnect slot from this signal.
 
         If `None`, all slots should be disconnected.
@@ -23,14 +34,18 @@ class PSignalInstance(Protocol):
 
 
 @runtime_checkable
-class PSignalDescriptor(Protocol):
+class PSignal(Protocol):
     """Descriptor that returns a signal instance."""
 
-    def __get__(self, instance: Optional[Any], owner: Any) -> PSignalInstance:
+    @overload
+    def __get__(self, instance: None, owner: type, /) -> Self: ...
+    @overload
+    def __get__(self, instance: Any, owner: type | None = None, /) -> Any: ...
+    def __get__(
+        self, instance: Any, owner: type | None = ..., /
+    ) -> PSignalInstance | PSignal:
         """Returns the signal instance for this descriptor."""
-
-
-PSignal = Union[PSignalDescriptor, PSignalInstance]
+        ...
 
 
 @runtime_checkable
@@ -91,102 +106,102 @@ class PCoreSignaler(Protocol):
     """
 
     # native MMCore callback events
-    propertiesChanged: PSignal
+    propertiesChanged: ClassVar[PSignal]
     """Emits with no arguments when properties have changed."""
-    propertyChanged: PSignal
+    propertyChanged: ClassVar[PSignal]
     """Emits `(name: str, : propName: str, propValue: str)` when a specific property has changed."""  # noqa: E501
-    channelGroupChanged: PSignal
+    channelGroupChanged: ClassVar[PSignal]
     """Emits `(newChannelGroupName: str)` when a channel group has changed."""
-    configGroupChanged: PSignal
+    configGroupChanged: ClassVar[PSignal]
     """Emits `(groupName: str, newConfigName: str)` when a config group has changed."""
-    systemConfigurationLoaded: PSignal
+    systemConfigurationLoaded: ClassVar[PSignal]
     """Emits with no arguments when the system configuration has been loaded."""
-    pixelSizeChanged: PSignal
+    pixelSizeChanged: ClassVar[PSignal]
     """Emits `(newPixelSizeUm: float)` when the pixel size has changed."""
-    pixelSizeAffineChanged: PSignal
+    pixelSizeAffineChanged: ClassVar[PSignal]
     """Emits `(float, float, float, float, float, float)` when the pixel size affine has changed."""  # noqa: E501
-    stagePositionChanged: PSignal
+    stagePositionChanged: ClassVar[PSignal]
     """Emits `(name: str, pos: float)` when a stage position has changed."""
-    XYStagePositionChanged: PSignal
+    XYStagePositionChanged: ClassVar[PSignal]
     """Emits `(name: str, xpos: float, ypos: float)` when an XY stage position has changed."""  # noqa: E501
-    xYStagePositionChanged: PSignal  # alias
-    exposureChanged: PSignal
+    xYStagePositionChanged: ClassVar[PSignal]  # alias
+    exposureChanged: ClassVar[PSignal]
     """Emits `(name: str, newExposure: float)` when an exposure has changed."""
-    SLMExposureChanged: PSignal
+    SLMExposureChanged: ClassVar[PSignal]
     """Emits `(name: str, newExposure: float)` when the exposure of the SLM device changes."""  # noqa: E501
-    sLMExposureChanged: PSignal  # alias
+    sLMExposureChanged: ClassVar[PSignal]  # alias
 
     # added for CMMCorePlus
-    configSet: PSignal
+    configSet: ClassVar[PSignal]
     """Emits `(str, str)` when a config has been set.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    imageSnapped: PSignal
+    imageSnapped: ClassVar[PSignal]
     """Emits with no arguments whenever snap is called.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    mdaEngineRegistered: PSignal
+    mdaEngineRegistered: ClassVar[PSignal]
     """Emits `(MDAEngine, MDAEngine)` when an MDAEngine is registered.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
 
-    continuousSequenceAcquisitionStarting: PSignal
+    continuousSequenceAcquisitionStarting: ClassVar[PSignal]
     """Emits with no arguments *before* continuous sequence acquisition is started.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    continuousSequenceAcquisitionStarted: PSignal
+    continuousSequenceAcquisitionStarted: ClassVar[PSignal]
     """Emits with no arguments *after* continuous sequence acquisition has started.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    sequenceAcquisitionStarting: PSignal
+    sequenceAcquisitionStarting: ClassVar[PSignal]
     """Emits `(str, int, float, bool)` *before* sequence acquisition is started.
 
     (cameraLabel, numImages, intervalMs, stopOnOverflow)
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    sequenceAcquisitionStarted: PSignal
+    sequenceAcquisitionStarted: ClassVar[PSignal]
     """Emits `(str, int, float, bool)` *after* sequence acquisition has started.
 
     (cameraLabel, numImages, intervalMs, stopOnOverflow)
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    sequenceAcquisitionStopped: PSignal
+    sequenceAcquisitionStopped: ClassVar[PSignal]
     """Emits `(str)` when sequence acquisition is stopped.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    autoShutterSet: PSignal
+    autoShutterSet: ClassVar[PSignal]
     """Emits `(bool)` when the auto shutter setting is changed.
 
     """
-    configGroupDeleted: PSignal
+    configGroupDeleted: ClassVar[PSignal]
     """Emits `(str)` when a config group is deleted.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    configDeleted: PSignal
+    configDeleted: ClassVar[PSignal]
     """Emits `(str, str)` when a config is deleted.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    configDefined: PSignal
+    configDefined: ClassVar[PSignal]
     """Emits `(str, str, str, str, str)` when a config is defined.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
-    roiSet: PSignal
+    roiSet: ClassVar[PSignal]
     """Emits `(str, int, int, int, int)` when an ROI is set.
 
     > :sparkles: This signal is unique to `pymmcore-plus`.
     """
 
     def devicePropertyChanged(
-        self, device: str, property: Optional[str] = None
+        self, device: str, property: str | None = None
     ) -> PSignalInstance:
         """Return object to connect/disconnect to device/property-specific changes.
 

pymmcore_plus/core/events/_psygnal.py

@@ -38,9 +38,9 @@ class CMMCoreSignaler(SignalGroup, _DevicePropertyEventMixin):
 
     # aliases for lower casing
     @property
-    def xYStagePositionChanged(self) -> SignalInstance:  # type: ignore
+    def xYStagePositionChanged(self) -> SignalInstance:
         return self.XYStagePositionChanged
 
     @property
-    def sLMExposureChanged(self) -> SignalInstance:  # type: ignore
+    def sLMExposureChanged(self) -> SignalInstance:
         return self.SLMExposureChanged

pymmcore_plus/experimental/unicore/__init__.py

@@ -1,12 +1,18 @@
-from ._unicore import UniMMCore
+from .core._unicore import UniMMCore
+from .devices._camera import Camera
 from .devices._device import Device
 from .devices._properties import PropertyInfo, pymm_property
+from .devices._slm import SLMDevice
 from .devices._stage import StageDevice, XYStageDevice, XYStepperStageDevice
+from .devices._state import StateDevice
 
 __all__ = [
+    "Camera",
     "Device",
     "PropertyInfo",
+    "SLMDevice",
     "StageDevice",
+    "StateDevice",
     "UniMMCore",
     "XYStageDevice",
     "XYStepperStageDevice",

pymmcore_plus/experimental/unicore/_proxy.py

@@ -106,22 +106,39 @@ def create_proxy(
     ```
     """
     sub_proxies = sub_proxies or {}
+
+    # Get all public attribute names from the protocol (both from dir() and type hints)
     allowed_names = {
         x
         for x in chain(dir(protocol), get_type_hints(protocol))
-        if not x.startswith("_")
+        if not x.startswith("_")  # Exclude private/dunder attributes
     }
+
+    # Create an immutable module to act as our proxy object
     proxy = _ImmutableModule(protocol.__name__)
+
+    # Iterate through each allowed attribute name
     for attr_name in allowed_names:
+        # Get the actual attribute from the source object
         attr = getattr(obj, attr_name)
+
+        # Check if this attribute should be sub-proxied
         if subprotocol := sub_proxies.get(attr_name):
-            # look for nested sub-proxies on attr_name, e.g. `attr_name.sub_attr`
+            # Look for nested sub-proxies on attr_name, e.g. `attr_name.sub_attr`
+            # Filter sub_proxies for keys that start with "attr_name."
             sub = {
-                k.split(".", 1)[1]: v
+                k.split(".", 1)[1]: v  # Remove the "attr_name." prefix
                 for k, v in sub_proxies.items()
                 if k.startswith(f"{attr_name}.")
             }
+            # Recursively create a proxy for this attribute
             attr = create_proxy(attr, subprotocol, sub)
+
+        # Set the attribute on our proxy object
         setattr(proxy, attr_name, attr)
+
+    # Freeze the proxy to prevent further modifications
     proxy.__frozen__ = True
+
+    # Return the proxy cast to the expected protocol type
     return cast("T", proxy)

pymmcore_plus/experimental/unicore/core/_sequence_buffer.py

@@ -0,0 +1,318 @@
+"""High-throughput, zero-copy ring buffer for camera image streams."""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from numpy.typing import DTypeLike, NDArray
+
+
+class BufferSlot(NamedTuple):
+    """Record describing one frame held in the pool."""
+
+    array: NDArray[Any]
+    metadata: Mapping[str, Any] | None  # metadata associated with this frame
+    nbytes_total: int  # full span in the pool (data + padding)
+
+
+class SequenceBuffer:
+    """A lock-protected circular buffer backed by a single numpy byte array.
+
+    This buffer is designed for a single device.  If you want to stream data from
+    multiple devices, it is recommended to use a separate `SequenceBuffer` for each
+    device (rather than to pack two streams into a single FIFO buffer).
+
+    Parameters
+    ----------
+    size_mb:
+        Pool capacity in **mebibytes** (binary - 1 MiB = 1,048,576 bytes).
+    overwrite_on_overflow:
+        When `True` (default) the oldest frame will be discarded to make space.
+        When `False`, an attempt to acquire a slot that does not fit raises
+        `BufferError`.
+    """
+
+    def __init__(self, size_mb: float, *, overwrite_on_overflow: bool = True) -> None:
+        self._size_bytes: int = int(size_mb * 1024 * 1024)
+        self._pool: NDArray[np.uint8] = np.empty(self._size_bytes, dtype=np.uint8)
+
+        # ring indices (bytes)
+        self._head: int = 0  # next write offset
+        self._tail: int = 0  # oldest frame offset
+        self._bytes_in_use: int = 0  # live bytes (includes padding)
+
+        # active frames in FIFO order (BufferSlot objects)
+        self._slots: deque[BufferSlot] = deque()
+
+        self._overwrite_on_overflow: bool = overwrite_on_overflow
+        self._overflow_occurred: bool = False
+
+        self._lock = threading.Lock()  # not re-entrant, but slightly faster than RLock
+        self._pending_slot: tuple[NDArray, int] | None = None  # only 1 outstanding slot
+
+    # ---------------------------------------------------------------------
+    # Producer API - acquire a slot, fill it, finalize it
+    # ---------------------------------------------------------------------
+
+    def acquire_slot(
+        self, shape: Sequence[int], dtype: DTypeLike = np.uint8
+    ) -> NDArray[Any]:
+        """Return a **writable** view into the internal pool.
+
+        After filling the array, *must* call `finalize_slot`.
+        """
+        dtype_ = np.dtype(dtype)
+        nbytes_data = int(np.prod(shape, dtype=int) * dtype_.itemsize)
+
+        # ---------- NEW: explicit capacity check ---------------------------
+        if nbytes_data > self._size_bytes:
+            msg = (
+                f"Requested size ({nbytes_data} bytes) exceeds buffer capacity "
+                f"({self.size_mb} MiB)."
+            )
+            raise BufferError(msg)
+
+        # --- reserve space -------------------------------------------------
+
+        with self._lock:
+            if self._pending_slot is not None:
+                msg = "Cannot acquire a new slot before finalizing the pending one."
+                raise RuntimeError(msg)
+
+            # Calculate padding needed to align start address to dtype boundary
+            align_pad = (-self._head) % dtype_.itemsize
+            needed = nbytes_data + align_pad
+
+            # ensure capacity (may evict oldest frames if overwrite enabled)
+            self._ensure_space(needed)
+
+            # alignment may force wrapping to 0 => recompute alignment
+            if needed > self._contiguous_free_bytes:
+                # wrap head to start of buffer for contiguous allocation
+                self._head = 0
+                align_pad = 0  # new head is already aligned to buffer start
+                needed = nbytes_data  # recalculated without padding
+                self._ensure_space(needed)  # guaranteed to succeed after wrap
+
+            # Calculate actual start position after alignment padding
+            start = self._head + align_pad
+            # Advance head pointer past this allocation (with wraparound)
+            self._head = (start + nbytes_data) % self._size_bytes
+            # Track total bytes consumed (data + alignment padding)
+            self._bytes_in_use += needed
+
+            # Create zero-copy view into the pool buffer at calculated offset
+            arr: NDArray[Any] = np.ndarray(
+                shape, dtype_, buffer=self._pool, offset=start
+            )
+            self._pending_slot = (arr, needed)
+            return arr
+
+    def finalize_slot(self, metadata: Mapping[str, Any] | None = None) -> None:
+        """Publish the frame acquired via `acquire_write_slot`.
+
+        This makes the frame available for retrieval via `pop_next` or
+        `peek_last`. If `metadata` is provided, it will be merged into the
+        slot's metadata dictionary.
+        """
+        with self._lock:
+            if (slot := self._pending_slot) is None:
+                msg = "No pending slot to finalize"
+                raise RuntimeError(msg)
+
+            self._pending_slot = None
+            arr, nbytes_total = slot
+            self._slots.append(BufferSlot(arr, metadata, nbytes_total))
+
+    # Convenience: copy-in one-shot insert ------------------------------
+
+    def insert_data(
+        self, data: NDArray[Any], metadata: Mapping[str, Any] | None = None
+    ) -> None:
+        """Insert data into the buffer, overwriting any existing frame.
+
+        This is a convenience method that acquires a slot, copies the data, and
+        finalizes the slot in one go.
+
+        For users who *can* write directly into our buffer, they should use
+        `acquire_slot` and `finalize_slot`. `insert_data` is for when the data already
+        exists in another NumPy array.
+        """
+        self.acquire_slot(data.shape, data.dtype)[:] = data
+        self.finalize_slot(metadata)
+
+    # ------------------------------------------------------------------
+    # Consumer API - pop frames, peek at frames
+    # ------------------------------------------------------------------
+
+    def pop_next(
+        self, *, copy: bool = False
+    ) -> tuple[NDArray[Any], Mapping[str, Any]] | None:
+        """Remove and return the oldest frame.
+
+        If `copy` is `True`, a copy of the data is returned, otherwise a read-only
+        view into the internal buffer is returned. The metadata is always returned
+        as a copy to prevent external modification.
+        """
+        with self._lock:
+            if not self._slots:
+                return None
+            slot = self._slots.popleft()
+            self._evict_slot(slot)
+
+        if copy:
+            arr = slot.array.copy()
+        else:
+            # even though we're popping, we still return a read-only view since
+            # the caller should be able to modify our _pool directly.
+            arr = slot.array.view()
+            arr.flags.writeable = False
+
+        # return actual metadata, we're done with it.
+        return arr, (slot.metadata or {})
+
+    def peek_last(
+        self, *, copy: bool = False
+    ) -> tuple[NDArray[Any], Mapping[str, Any]] | None:
+        """Return the newest frame without removing it."""
+        return self.peek_nth_from_last(0, copy=copy)
+
+    def peek_nth_from_last(
+        self, n: int, *, copy: bool = False
+    ) -> tuple[NDArray[Any], dict[str, Any]] | None:
+        """Return the n-th most recent frame without removing it.
+
+        Last frame is n=0, second to last is n=1, etc.
+        """
+        with self._lock:
+            if n < 0 or n >= len(self._slots):
+                return None
+            slot = self._slots[-(n + 1)]
+
+            if copy:
+                arr = slot.array.copy()
+            else:
+                # Return a read-only view to prevent modification of data in the buffer
+                arr = slot.array.view()
+                arr.flags.writeable = False
+
+            # Return a copy of the metadata to avoid external modification
+            return arr, (dict(slot.metadata) if slot.metadata else {})
+
+    # ------------------------------------------------------------------
+    # Administrative helpers
+    # ------------------------------------------------------------------
+
+    def clear(self) -> None:
+        with self._lock:
+            self._slots.clear()
+            self._pending_slot = None
+            self._head = self._tail = self._bytes_in_use = 0
+            self._overflow_occurred = False
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def size_mb(self) -> float:  # human readable
+        return self._size_bytes / 1024**2
+
+    @property
+    def size_bytes(self) -> int:
+        """Return the buffer size in bytes."""
+        return self._size_bytes
+
+    @property
+    def used_bytes(self) -> int:
+        """Return the number of bytes currently in use."""
+        return self._bytes_in_use
+
+    @property
+    def free_bytes(self) -> int:
+        """Return the number of free bytes in the buffer."""
+        return self._size_bytes - self._bytes_in_use
+
+    @property
+    def free_mb(self) -> float:
+        """Get the free space in the buffer in mebibytes."""
+        return self.free_bytes / 1024**2
+
+    @property
+    def overwrite_on_overflow(self) -> bool:
+        """Return the overflow policy (immutable while data is present)."""
+        return self._overwrite_on_overflow
+
+    @overwrite_on_overflow.setter
+    def overwrite_on_overflow(self, value: bool) -> None:
+        """Set the overflow policy (immutable while data is present)."""
+        with self._lock:
+            if self._bytes_in_use > 0:
+                msg = "Cannot change overflow policy with active data in buffer."
+                raise RuntimeError(msg)
+            self._overwrite_on_overflow = value
+
+    def __len__(self) -> int:
+        """Return the number of frames currently in the buffer."""
+        return len(self._slots)
+
+    @property
+    def overflow_occurred(self) -> bool:
+        """Return whether an overflow occurred since the last clear."""
+        return self._overflow_occurred
+
+    def __repr__(self) -> str:
+        used_mb = self.used_bytes / 1024**2
+        name = self.__class__.__name__
+        return (
+            f"{name}(size_mb={self.size_mb:.1f}, slots={len(self)}, "
+            f"used_mb={used_mb:.1f}, overwrite={self._overwrite_on_overflow})"
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _evict_slot(self, slot: BufferSlot) -> None:
+        """Advance the tail pointer past `slot`, updating house-keeping."""
+        self._tail = (self._tail + slot.nbytes_total) % self._size_bytes
+        self._bytes_in_use -= slot.nbytes_total
+
+    @property
+    def _contiguous_free_bytes(self) -> int:
+        """Get the number of contiguous free bytes in the buffer."""
+        if self._bytes_in_use >= self._size_bytes:
+            return 0
+        if self._bytes_in_use == 0:
+            return self._size_bytes
+        if self._head >= self._tail:
+            return self._size_bytes - self._head
+        # it's very hard to make this case happen...
+        return self._tail - self._head  # pragma: no cover
+
+    def _ensure_space(self, needed: int) -> None:
+        """Ensure `needed` bytes contiguous space is available."""
+        while self._contiguous_free_bytes < needed:
+            if not self._slots:
+                # Buffer empty but fragmented: just reset pointers
+                self._head = self._tail = self._bytes_in_use = 0
+                break
+            if not self._overwrite_on_overflow:
+                self._overflow_occurred = True
+                msg = "Buffer is full and overwrite is disabled."
+                raise BufferError(msg)
+            self._overflow_occurred = True
+            while self._slots and self._contiguous_free_bytes < needed:
+                slot = self._slots.popleft()
+                self._evict_slot(slot)
+
+        # If the buffer is now empty, reset head/tail to maximise contiguous space.
+        if self._bytes_in_use == 0:
+            self._head = self._tail = 0