pymmcore-plus 0.13.6__py3-none-any.whl → 0.14.0__py3-none-any.whl

pymmcore_plus/__init__.py

@@ -8,6 +8,7 @@ except PackageNotFoundError:  # pragma: no cover
     __version__ = "unknown"
 
 
+from ._accumulator import AbstractChangeAccumulator
 from ._logger import configure_logging
 from ._util import find_micromanager, use_micromanager
 from .core import (
@@ -34,6 +35,7 @@ from .core.events import CMMCoreSignaler, PCoreSignaler
 from .mda._runner import GeneratorMDASequence
 
 __all__ = [
+    "AbstractChangeAccumulator",
     "ActionType",
     "CFGCommand",
     "CFGGroup",

pymmcore_plus/_accumulator.py

@@ -0,0 +1,258 @@
+"""Accumulate `setX` calls to a device value or property."""
+
+from __future__ import annotations
+
+import abc
+import sys
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeVar
+
+import psygnal
+
+from pymmcore_plus.core._constants import DeviceType
+from pymmcore_plus.core._mmcore_plus import CMMCorePlus
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+T = TypeVar("T")
+DT = TypeVar("DT", bound=DeviceType)
+
+
+class AbstractChangeAccumulator(ABC, Generic[T]):
+    """Abstract base class for accumulating a series of `setX` calls to a device.
+
+    A `ChangeAccumulator`` is a class that accumulates a series of `setX` calls to a
+    device, retaining an internal target value, and emitting a signal when the device
+    has reached its target and is idle. It can be shared by multiple players (e.g.
+    widgets, or other classes) that want to control the same device, and allows them all
+    to issue relative/absolute moves, and be notified when the device is idle.
+
+    A common use case is to accumulate setPosition calls made to a stage device, where
+    you might want to accumulate a series of relative moves, and snap an image only when
+    the stage is idle after reaching its target position.
+    """
+
+    finished = psygnal.Signal()
+    """Signal emitted when the device has reached its target and is idle."""
+
+    def __init__(self, zero: T) -> None:
+        self._zero = zero
+        self._reset()
+
+    def _reset(self) -> None:
+        self._base: T | None = None
+        self._delta: T | None = None
+
+    # ------------------------ Public API ------------------------
+
+    def add_relative(self, delta: T) -> None:
+        """Add a relative value to the target."""
+        if self._delta is None:
+            self._base = self._get_value()
+            self._delta = delta
+        else:
+            self._delta = self._add(self._delta, delta)
+        self._issue_move()
+
+    def set_absolute(self, target: T) -> None:
+        """Assign an absolute value to the target.
+
+        This will reset the accumulated state and issue a move to the target position.
+        After the move finishes, new `move_relative()` calls are interpreted
+        relative to *target*.
+        """
+        self._base = target  # anchor for later relatives
+        self._delta = self._zero  # target == base + delta
+        self._issue_move()
+
+    def poll_done(self) -> bool:
+        """Check if the device is done moving.
+
+        This should be called repeatedly by some event loop driver.
+
+        Returns True exactly once when:
+        1. The device is idle (not busy) AND
+        2. The last issued move command has been completed
+
+        After returning True it resets its state and will return False until the next
+        move_relative() call.
+        """
+        # if we have no base or delta, we're not moving
+        if self._delta is None:
+            return False
+
+        # if the device is busy, we're not done
+        if self._is_busy():
+            return False
+
+        # no new work, we're done
+        self._reset()
+        self.finished.emit()
+        return True
+
+    @property
+    def is_moving(self) -> bool:
+        """Returns True if the device is moving."""
+        return self._delta is not None
+
+    @property
+    def target(self) -> T | None:
+        """The target position of the stage. Or None if not moving."""
+        if self._base is None or self._delta is None:
+            return None
+        return self._add(self._base, self._delta)
+
+    # ------------------------ Public API ------------------------
+
+    def _issue_move(self) -> None:
+        # self._base and self._delta are guaranteed to be not None here
+        target = self._add(self._base, self._delta)  # type: ignore[arg-type]
+        # issue the move command
+        try:
+            self._set_value(target)
+        except Exception:  # pragma: no cover
+            from pymmcore_plus._logger import logger
+
+            logger.exception(f"Error setting {type(self)} to {target}")
+
+    # ------------------------ Abstract methods ------------------------
+
+    @abstractmethod
+    def _get_value(self) -> T:
+        """Get the current position of the device."""
+
+    @abstractmethod
+    def _set_value(self, value: T) -> None:
+        """Set the position of the device."""
+
+    @abstractmethod
+    def _add(self, a: T, b: T) -> T:
+        """Add two values together.
+
+        Provided for more complex types like sequences.
+        """
+
+    @abstractmethod
+    def _is_busy(self) -> bool:
+        """Return True if the device is busy."""
+
+
+class FloatChangeAccumulator(AbstractChangeAccumulator[float]):
+    def __init__(self) -> None:
+        super().__init__(zero=0.0)
+
+    def _add(self, a: float, b: float) -> float:
+        return a + b
+
+
+ZIP_STRICT = {"strict": True} if sys.version_info >= (3, 10) else {}
+
+
+class SequenceChangeAccumulator(AbstractChangeAccumulator[Sequence[float]]):
+    def __init__(self, sequence_length: int) -> None:
+        self.sequence_length = sequence_length
+        super().__init__(zero=[0.0] * sequence_length)
+
+    def _add(self, a: Sequence[float], b: Sequence[float]) -> Sequence[float]:
+        return [x + y for x, y in zip(a, b, **ZIP_STRICT)]
+
+
+class DeviceAccumulator(abc.ABC, Generic[DT]):
+    def __init__(
+        self,
+        *,
+        device_label: str,
+        mmcore: CMMCorePlus | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._mmcore = mmcore or CMMCorePlus.instance()
+        dev_type = self._device_type()
+        if not self._mmcore.getDeviceType(device_label) == dev_type:  # pragma: no cover
+            raise ValueError(
+                f"Cannot create {self.__class__.__name__}. "
+                f"Device {device_label!r} is not a {dev_type.name}. "
+            )
+
+        self._device_label = device_label
+        super().__init__(**kwargs)
+
+    def _is_busy(self) -> bool:
+        return self._mmcore.deviceBusy(self._device_label)
+
+    @classmethod
+    @abstractmethod
+    def _device_type(cls) -> DT:
+        """Return the device type for this class."""
+
+    _CACHE: ClassVar[dict[tuple[int, str], DeviceAccumulator]] = {}
+
+    @classmethod
+    def get_cached(cls, device: str, mmcore: CMMCorePlus | None = None) -> Self:
+        """Get a cached instance of the class for the given (device, core) pair.
+
+        This is intended to be called on the subclass for the device type you want to
+        create. For example, if you want to create a `PositionChangeAccumulator` for a
+        `StageDevice`, you would call: `PositionChangeAccumulator.get_cached(device)`.
+
+        But it may also be called on the base class, in which case it will still return
+        the correct subclass instance, but you will not have type safety on the return
+        type.
+        """
+        mmcore = mmcore or CMMCorePlus.instance()
+        cache_key = (id(mmcore), device)
+        device_type = mmcore.getDeviceType(device)
+        if cache_key not in DeviceAccumulator._CACHE:
+            if device_type == cls._device_type():
+                cls._CACHE[cache_key] = cls(device_label=device, mmcore=mmcore)
+            else:
+                for sub in cls.__subclasses__():
+                    if sub._device_type() == device_type:  # noqa: SLF001
+                        cls._CACHE[cache_key] = sub(device_label=device, mmcore=mmcore)
+                        break
+                else:
+                    raise ValueError(
+                        "No matching DeviceTypeMixin subclass found for device type "
+                        f"{device_type.name} (for device {device!r})."
+                    )
+        obj = cls._CACHE[cache_key]
+        if not isinstance(obj, cls):
+            raise TypeError(
+                f"Cannot create {cls.__name__} for {device!r}. "
+                f"Device is a {device_type!r}, not a {cls._device_type().name}. "
+            )
+        return obj
+
+
+class PositionChangeAccumulator(DeviceAccumulator, FloatChangeAccumulator):
+    """Accumulator for single axis stage devices."""
+
+    def __init__(self, device_label: str, mmcore: CMMCorePlus | None = None) -> None:
+        super().__init__(device_label=device_label, mmcore=mmcore)
+
+    @classmethod
+    def _device_type(cls) -> Literal[DeviceType.StageDevice]:
+        return DeviceType.StageDevice
+
+    def _get_value(self) -> float:
+        return self._mmcore.getPosition(self._device_label)
+
+    def _set_value(self, value: float) -> None:
+        self._mmcore.setPosition(self._device_label, value)
+
+
+class XYPositionChangeAccumulator(DeviceAccumulator, SequenceChangeAccumulator):
+    """Accumulator for XY stage devices."""
+
+    def __init__(self, device_label: str, mmcore: CMMCorePlus | None = None) -> None:
+        super().__init__(device_label=device_label, mmcore=mmcore, sequence_length=2)
+
+    @classmethod
+    def _device_type(cls) -> Literal[DeviceType.XYStageDevice]:
+        return DeviceType.XYStageDevice
+
+    def _get_value(self) -> Sequence[float]:
+        return self._mmcore.getXYPosition(self._device_label)
+
+    def _set_value(self, value: Sequence[float]) -> None:
+        self._mmcore.setXYPosition(self._device_label, *value)

pymmcore_plus/_cli.py

@@ -1,4 +1,5 @@
 # do NOT use __future__.annotations here. It breaks typer.
+import contextlib
 import os
 import shutil
 import subprocess
@@ -143,12 +144,13 @@ def mmstudio() -> None:  # pragma: no cover
         if mm
         else None
     )
-    if not app:  # pragma: no cover
+    if not mm or not app:  # pragma: no cover
         print(f":x: [bold red]No MMStudio application found in {mm!r}")
         print("[magenta]run `mmcore install` to install a version of Micro-Manager")
         raise typer.Exit(1)
     cmd = ["open", "-a", str(app)] if PLATFORM == "Darwin" else [str(app)]
-    raise typer.Exit(subprocess.run(cmd).returncode)
+    with contextlib.chdir(mm):
+        raise typer.Exit(subprocess.run(cmd).returncode)
 
 
 @app.command()

pymmcore_plus/_util.py

@@ -181,14 +181,17 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
     app_path = applications[sys.platform]
     pth = next(app_path.glob("[m,M]icro-[m,M]anager*"), None)
     if return_first:
-        if pth is None:
-            logger.error(
-                "could not find micromanager directory. Please run 'mmcore install'"
-            )
-            return None
-        if _mm_path_has_compatible_div(pth):  # pragma: no cover
+        if pth and _mm_path_has_compatible_div(pth):  # pragma: no cover
             logger.debug("using MM path found in applications: %s", pth)
             return str(pth)
+        from . import _pymmcore
+
+        div = _pymmcore.version_info.device_interface
+        logger.error(
+            f"could not find micromanager directory for device interface {div}. "
+            "Please run 'mmcore install'"
+        )
+        return None
     if pth is not None:
         full_list[str(pth)] = None
     return list(full_list)
@@ -659,9 +662,9 @@ def get_device_interface_version(lib_path: str | Path) -> int:
     import ctypes
 
     if sys.platform.startswith("win"):
-        lib = ctypes.WinDLL(lib_path)
+        lib = ctypes.WinDLL(str(lib_path))
     else:
-        lib = ctypes.CDLL(lib_path)
+        lib = ctypes.CDLL(str(lib_path))
 
     try:
         func = lib.GetDeviceInterfaceVersion

pymmcore_plus/core/__init__.py

@@ -1,10 +1,14 @@
 __all__ = [
     "ActionType",
+    "AutoFocusDevice",
     "CFGCommand",
     "CFGGroup",
     "CMMCorePlus",
+    "CameraDevice",
     "ConfigGroup",
     "Configuration",
+    "CoreDevice",
+    "Device",
     "Device",
     "DeviceAdapter",
     "DeviceDetectionStatus",
@@ -13,12 +17,24 @@ __all__ = [
     "DeviceProperty",
     "DeviceType",
     "FocusDirection",
+    "GalvoDevice",
+    "GenericDevice",
+    "HubDevice",
+    "ImageProcessorDevice",
     "Keyword",
+    "MagnifierDevice",
     "Metadata",
     "PixelFormat",
     "PortType",
     "PropertyType",
+    "SLMDevice",
     "SequencedEvent",
+    "SerialDevice",
+    "ShutterDevice",
+    "SignalIODevice",
+    "StageDevice",
+    "StateDevice",
+    "XYStageDevice",
     "iter_sequenced_events",
 ]
 
@@ -39,7 +55,24 @@ from ._constants import (
     PortType,
     PropertyType,
 )
-from ._device import Device
+from ._device import (
+    AutoFocusDevice,
+    CameraDevice,
+    CoreDevice,
+    Device,
+    GalvoDevice,
+    GenericDevice,
+    HubDevice,
+    ImageProcessorDevice,
+    MagnifierDevice,
+    SerialDevice,
+    ShutterDevice,
+    SignalIODevice,
+    SLMDevice,
+    StageDevice,
+    StateDevice,
+    XYStageDevice,
+)
 from ._metadata import Metadata
 from ._mmcore_plus import CMMCorePlus
 from ._property import DeviceProperty