pymmcore-plus 0.12.0__py3-none-any.whl → 0.13.1__py3-none-any.whl

pymmcore_plus/experimental/unicore/devices/_stage.py

@@ -0,0 +1,221 @@
+from abc import abstractmethod
+from typing import ClassVar, Literal
+
+from pymmcore_plus.core import DeviceType
+from pymmcore_plus.core._constants import Keyword
+
+from ._device import SeqT, SequenceableDevice
+
+__all__ = ["_BaseStage"]
+
+
+class _BaseStage(SequenceableDevice[SeqT]):
+    """Shared logic for Stage and XYStage devices."""
+
+    @abstractmethod
+    def home(self) -> None:
+        """Move the stage to its home position."""
+
+    @abstractmethod
+    def stop(self) -> None:
+        """Stop the stage."""
+
+    @abstractmethod
+    def set_origin(self) -> None:
+        """Zero the stage's coordinates at the current position."""
+
+
+class StageDevice(_BaseStage[float]):
+    """ABC for Stage devices."""
+
+    _TYPE: ClassVar[Literal[DeviceType.Stage]] = DeviceType.Stage
+
+    @abstractmethod
+    def set_position_um(self, val: float) -> None:
+        """Set the position of the stage in microns."""
+
+    @abstractmethod
+    def get_position_um(self) -> float:
+        """Returns the current position of the stage in microns."""
+
+
+# TODO: consider if we can just subclass StageDevice instead of _BaseStage
+class XYStageDevice(_BaseStage[tuple[float, float]]):
+    """ABC for XYStage devices."""
+
+    _TYPE: ClassVar[Literal[DeviceType.XYStage]] = DeviceType.XYStage
+
+    @abstractmethod
+    def set_position_um(self, x: float, y: float) -> None:
+        """Set the position of the XY stage in microns."""
+
+    @abstractmethod
+    def get_position_um(self) -> tuple[float, float]:
+        """Returns the current position of the XY stage in microns."""
+
+    @abstractmethod
+    def set_origin_x(self) -> None:
+        """Zero the stage's X coordinates at the current position."""
+
+    @abstractmethod
+    def set_origin_y(self) -> None:
+        """Zero the stage's Y coordinates at the current position."""
+
+    # ----------------------------------------------------------------
+
+    def set_relative_position_um(self, dx: float, dy: float) -> None:
+        """Move the stage by a relative amount.
+
+        Can be overridden for more efficient implementations.
+        """
+        x, y = self.get_position_um()
+        self.set_position_um(x + dx, y + dy)
+
+    def set_adapter_origin_um(self, x: float, y: float) -> None:
+        """Alter the software coordinate translation between micrometers and steps.
+
+        ... such that the current position becomes the given coordinates.
+        """
+        # I don't quite understand what this method is supposed to do yet.
+        # I believe it's here to give device adapter implementations a way to to set
+        # the origin of some translation between micrometers and steps, rather than to
+        # directly update the origin on the device itself.
+
+    def set_origin(self) -> None:
+        """Zero the stage's coordinates at the current position.
+
+        This is a convenience method that calls `set_origin_x` and `set_origin_y`.
+        Can be overridden for more efficient implementations.
+        """
+        self.set_origin_x()
+        self.set_origin_y()
+
+
+class XYStepperStageDevice(XYStageDevice):
+    """ABC for XYStage devices that support stepper motors.
+
+    In this variant, rather than providing `set_position_um` and `get_position_um`,
+    you provide `set_position_steps`, `get_position_steps`, `get_step_size_x_um`,
+    and `get_step_size_y_um`.  A default implementation of `set_position_um` and
+    `get_position_um` is then provided that uses these methods, taking into account
+    the XY-mirroring properties of the device.
+    """
+
+    @abstractmethod
+    def set_position_steps(self, x: int, y: int) -> None:
+        """Set the position of the XY stage in steps."""
+
+    @abstractmethod
+    def get_position_steps(self) -> tuple[int, int]:
+        """Returns the current position of the XY stage in steps."""
+
+    @abstractmethod
+    def get_step_size_x_um(self) -> float:
+        """Returns the step size of the X axis in microns."""
+
+    @abstractmethod
+    def get_step_size_y_um(self) -> float:
+        """Returns the step size of the Y axis in microns."""
+
+    # ----------------------------------------------------------------
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.register_property(name=Keyword.Transpose_MirrorX, default_value=False)
+        self.register_property(name=Keyword.Transpose_MirrorY, default_value=False)
+        self._origin_x_steps: int = 0
+        self._origin_y_steps: int = 0
+
+    def set_position_um(self, x: float, y: float) -> None:
+        """Set the position of the XY stage in microns."""
+        # Converts the given micrometer coordinates to steps and sets the position.
+        mirror_x, mirror_y = self._get_orientation()
+
+        steps_x = int(x / self.get_step_size_x_um())
+        steps_y = int(y / self.get_step_size_y_um())
+
+        if mirror_x:
+            steps_x = -steps_x
+        if mirror_y:
+            steps_y = -steps_y
+
+        x_steps = self._origin_x_steps + steps_x
+        y_steps = self._origin_y_steps + steps_y
+        self.set_position_steps(x_steps, y_steps)
+
+        self.core.events.XYStagePositionChanged.emit(self.get_label(), x, y)
+
+    def get_position_um(self) -> tuple[float, float]:
+        """Get the position of the XY stage in microns."""
+        # Converts the current steps to micrometer coordinates and returns the position.
+        mirror_x, mirror_y = self._get_orientation()
+        x_steps, y_steps = self.get_position_steps()
+
+        x = (self._origin_x_steps - x_steps) * self.get_step_size_x_um()
+        y = (self._origin_y_steps - y_steps) * self.get_step_size_y_um()
+        if not mirror_x:
+            x = -x
+        if not mirror_y:
+            y = -y
+
+        return x, y
+
+    def set_relative_position_steps(self, dx: int, dy: int) -> None:
+        """Move the stage by a relative amount.
+
+        Can be overridden for more efficient implementations.
+        """
+        x_steps, y_steps = self.get_position_steps()
+        self.set_position_steps(x_steps + dx, y_steps + dy)
+
+    def set_relative_position_um(self, dx: float, dy: float) -> None:
+        """Default implementation for relative motion.
+
+        Can be overridden for more efficient implementations.
+        """
+        mirror_x, mirror_y = self._get_orientation()
+
+        if mirror_x:
+            dx = -dx
+        if mirror_y:
+            dy = -dy
+
+        steps_x = int(dx / self.get_step_size_x_um())
+        steps_y = int(dy / self.get_step_size_y_um())
+
+        self.set_relative_position_steps(steps_x, steps_y)
+
+        x, y = self.get_position_um()
+        self.core.events.XYStagePositionChanged.emit(self.get_label(), x, y)
+
+    def set_adapter_origin_um(self, x: float = 0.0, y: float = 0.0) -> None:
+        """Alter the software coordinate translation between micrometers and steps.
+
+        ... such that the current position becomes the given coordinates.
+        """
+        mirror_x, mirror_y = self._get_orientation()
+        x_steps, y_steps = self.get_position_steps()
+
+        steps_x = int(x / self.get_step_size_x_um())
+        steps_y = int(y / self.get_step_size_y_um())
+
+        self._origin_x_steps = x_steps + (steps_x if mirror_x else -steps_x)
+        self._origin_y_steps = y_steps + (steps_y if mirror_y else -steps_y)
+
+    def set_origin(self) -> None:
+        """Zero the stage's coordinates at the current position."""
+        self.set_adapter_origin_um()
+
+    def set_origin_x(self) -> None:
+        """Zero the stage's X coordinates at the current position."""
+        raise NotImplementedError  # pragma: no cover
+
+    def set_origin_y(self) -> None:
+        """Zero the stage's Y coordinates at the current position."""
+        raise NotImplementedError  # pragma: no cover
+
+    def _get_orientation(self) -> tuple[bool, bool]:
+        return (
+            self.get_property_value(Keyword.Transpose_MirrorX),
+            self.get_property_value(Keyword.Transpose_MirrorY),
+        )

pymmcore_plus/install.py

@@ -37,14 +37,12 @@ try:
         rich_print(f"{emoji}{color}{text}")
 
     @contextmanager
-    def _spinner(
-        text: str = "", color: str = "bold blue"
-    ) -> Iterator[progress.Progress]:
+    def _spinner(text: str, color: str = "bold blue") -> Iterator[None]:
         with progress.Progress(
             progress.SpinnerColumn(), progress.TextColumn(f"[{color}]{text}")
         ) as pbar:
             pbar.add_task(description=text, total=None)
-            yield pbar
+            yield None
 
 except ImportError:  # pragma: no cover
     progress = None  # type: ignore
@@ -53,7 +51,7 @@ except ImportError:  # pragma: no cover
         print(text)
 
     @contextmanager
-    def _spinner(text: str = "", color: str = "") -> Iterator[None]:
+    def _spinner(text: str, color: str = "") -> Iterator[None]:
         print(text)
         yield
 
@@ -78,8 +76,8 @@ def _get_spinner(log_msg: _MsgLogger) -> Callable[[str], AbstractContextManager]
     else:
 
         @contextmanager
-        def spinner(msg: str) -> Iterator[None]:
-            log_msg(msg)
+        def spinner(text: str, color: str = "") -> Iterator[None]:
+            log_msg(text)
             yield
 
     return spinner
@@ -209,6 +207,11 @@ def install(
     """
     if PLATFORM not in ("Darwin", "Windows"):  # pragma: no cover
         log_msg(f"Unsupported platform: {PLATFORM!r}", "bold red", ":x:")
+        log_msg(
+            "Consider building from source (mmcore build-dev).",
+            "bold yellow",
+            ":light_bulb:",
+        )
         raise sys.exit(1)
 
     if release == "latest":

pymmcore_plus/mda/__init__.py

@@ -5,9 +5,9 @@ from ._thread_relay import mda_listeners_connected
 from .events import PMDASignaler
 
 __all__ = [
-    "mda_listeners_connected",
     "MDAEngine",
     "MDARunner",
     "PMDAEngine",
     "PMDASignaler",
+    "mda_listeners_connected",
 ]

pymmcore_plus/mda/_engine.py

@@ -3,18 +3,16 @@ from __future__ import annotations
 import time
 from contextlib import suppress
 from itertools import product
-from typing import (
-    TYPE_CHECKING,
-    NamedTuple,
-    cast,
-)
+from typing import TYPE_CHECKING, Literal, NamedTuple, cast
 
+import numpy as np
+import useq
 from useq import HardwareAutofocus, MDAEvent, MDASequence
 
 from pymmcore_plus._logger import logger
 from pymmcore_plus._util import retry
 from pymmcore_plus.core._constants import Keyword
-from pymmcore_plus.core._sequencing import SequencedEvent
+from pymmcore_plus.core._sequencing import SequencedEvent, iter_sequenced_events
 from pymmcore_plus.metadata import (
     FrameMetaV1,
     PropertyValue,
@@ -27,6 +25,7 @@ from ._protocol import PMDAEngine
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator, Sequence
+    from typing import TypeAlias
 
     from numpy.typing import NDArray
 
@@ -34,6 +33,19 @@ if TYPE_CHECKING:
 
     from ._protocol import PImagePayload
 
+    IncludePositionArg: TypeAlias = Literal[True, False, "unsequenced-only"]
+
+
+# these are SLM devices that have a known pixel_on_value.
+# there is currently no way to extract this information from the core,
+# so it is hard-coded here.
+# maps device_name -> pixel_on_value
+_SLM_DEVICES_PIXEL_ON_VALUES: dict[str, int] = {
+    "MightexPolygon1000": 255,
+    "Mosaic3": 1,
+    "GenericSLM": 255,
+}
+
 
 class MDAEngine(PMDAEngine):
     """The default MDAengine that ships with pymmcore-plus.
@@ -59,7 +71,11 @@ class MDAEngine(PMDAEngine):
 
     def __init__(self, mmc: CMMCorePlus, use_hardware_sequencing: bool = True) -> None:
         self._mmc = mmc
-        self.use_hardware_sequencing = use_hardware_sequencing
+        self.use_hardware_sequencing: bool = use_hardware_sequencing
+
+        # whether to include position metadata when fetching on-frame metadata
+        # omitted by default when performing triggered acquisition because it's slow.
+        self._include_frame_position_metadata: IncludePositionArg = "unsequenced-only"
 
         # used to check if the hardware autofocus is engaged when the sequence begins.
         # if it is, we will re-engage it after the autofocus action (if successful).
@@ -83,6 +99,19 @@ class MDAEngine(PMDAEngine):
         # in the channel group.
         self._config_device_props: dict[str, Sequence[tuple[str, str]]] = {}
 
+    @property
+    def include_frame_position_metadata(self) -> IncludePositionArg:
+        return self._include_frame_position_metadata
+
+    @include_frame_position_metadata.setter
+    def include_frame_position_metadata(self, value: IncludePositionArg) -> None:
+        if value not in (True, False, "unsequenced-only"):  # pragma: no cover
+            raise ValueError(
+                "include_frame_position_metadata must be True, False, or "
+                "'unsequenced-only'"
+            )
+        self._include_frame_position_metadata = value
+
     @property
     def mmcore(self) -> CMMCorePlus:
         """The `CMMCorePlus` instance to use for hardware control."""
@@ -188,21 +217,7 @@ class MDAEngine(PMDAEngine):
             yield from events
             return
 
-        seq: list[MDAEvent] = []
-        for event in events:
-            # if the sequence is empty or the current event can be sequenced with the
-            # previous event, add it to the sequence
-            if not seq or self._mmc.canSequenceEvents(seq[-1], event, len(seq)):
-                seq.append(event)
-            else:
-                # otherwise, yield a SequencedEvent if the sequence has accumulated
-                # more than one event, otherwise yield the single event
-                yield seq[0] if len(seq) == 1 else SequencedEvent.create(seq)
-                # add this current event and start a new sequence
-                seq = [event]
-        # yield any remaining events
-        if seq:
-            yield seq[0] if len(seq) == 1 else SequencedEvent.create(seq)
+        yield from iter_sequenced_events(self._mmc, events)
 
     # ===================== Regular Events =====================
 
@@ -220,7 +235,8 @@ class MDAEngine(PMDAEngine):
             self._set_event_position(event)
         if event.z_pos is not None:
             self._set_event_z(event)
-
+        if event.slm_image is not None:
+            self._set_event_slm_image(event)
         if event.channel is not None:
             try:
                 # possible speedup by setting manually.
@@ -232,7 +248,12 @@ class MDAEngine(PMDAEngine):
                 self._mmc.setExposure(event.exposure)
             except Exception as e:
                 logger.warning("Failed to set exposure. %s", e)
-
+        if event.properties is not None:
+            try:
+                for dev, prop, value in event.properties:
+                    self._mmc.setProperty(dev, prop, value)
+            except Exception as e:
+                logger.warning("Failed to set properties. %s", e)
         if (
             # (if autoshutter wasn't set at the beginning of the sequence
             # then it never matters...)
@@ -253,6 +274,9 @@ class MDAEngine(PMDAEngine):
         `exec_event`, which *is* part of the protocol), but it is made public
         in case a user wants to subclass this engine and override this method.
         """
+        if event.slm_image is not None:
+            self._exec_event_slm_image(event.slm_image)
+
         try:
             self._mmc.snapImage()
             # taking event time after snapImage includes exposure time
@@ -274,6 +298,7 @@ class MDAEngine(PMDAEngine):
                 event,
                 runner_time_ms=event_time_ms,
                 camera_device=self._mmc.getPhysicalCameraDevice(cam),
+                include_position=self._include_frame_position_metadata is not False,
             )
             # Note, the third element is actually a MutableMapping, but mypy doesn't
             # see TypedDict as a subclass of MutableMapping yet.
@@ -285,6 +310,7 @@ class MDAEngine(PMDAEngine):
         event: MDAEvent,
         prop_values: tuple[PropertyValue, ...] | None = None,
         runner_time_ms: float = 0.0,
+        include_position: bool = True,
         camera_device: str | None = None,
     ) -> FrameMetaV1:
         if prop_values is None and (ch := event.channel):
@@ -298,6 +324,7 @@ class MDAEngine(PMDAEngine):
             camera_device=camera_device,
             property_values=prop_values,
             mda_event=event,
+            include_position=include_position,
         )
 
     def teardown_event(self, event: MDAEvent) -> None:
@@ -316,7 +343,7 @@ class MDAEngine(PMDAEngine):
                 core.stopXYStageSequence(core.getXYStageDevice())
             if event.z_sequence:
                 core.stopStageSequence(core.getFocusDevice())
-            for dev, prop in event.property_sequences(core):
+            for dev, prop in event.property_sequences:
                 core.stopPropertySequence(dev, prop)
 
     def teardown_sequence(self, sequence: MDASequence) -> None:
@@ -325,17 +352,15 @@ class MDAEngine(PMDAEngine):
 
     # ===================== Sequenced Events =====================
 
-    def setup_sequenced_event(self, event: SequencedEvent) -> None:
-        """Setup hardware for a sequenced (triggered) event.
+    def _load_sequenced_event(self, event: SequencedEvent) -> None:
+        """Load a `SequencedEvent` into the core.
 
-        This method is not part of the PMDAEngine protocol (it is called by
-        `setup_event`, which *is* part of the protocol), but it is made public
-        in case a user wants to subclass this engine and override this method.
+        `SequencedEvent` is a special pymmcore-plus specific subclass of
+        `useq.MDAEvent`.
         """
         core = self._mmc
-        cam_device = self._mmc.getCameraDevice()
-
         if event.exposure_sequence:
+            cam_device = core.getCameraDevice()
             with suppress(RuntimeError):
                 core.stopExposureSequence(cam_device)
             core.loadExposureSequence(cam_device, event.exposure_sequence)
@@ -349,40 +374,71 @@ class MDAEngine(PMDAEngine):
             with suppress(RuntimeError):
                 core.stopStageSequence(zstage)
             core.loadStageSequence(zstage, event.z_sequence)
-        if prop_seqs := event.property_sequences(core):
-            for (dev, prop), value_sequence in prop_seqs.items():
+        if event.slm_sequence:
+            slm = core.getSLMDevice()
+            with suppress(RuntimeError):
+                core.stopSLMSequence(slm)
+            core.loadSLMSequence(slm, event.slm_sequence)  # type: ignore[arg-type]
+        if event.property_sequences:
+            for (dev, prop), value_sequence in event.property_sequences.items():
                 with suppress(RuntimeError):
                     core.stopPropertySequence(dev, prop)
                 core.loadPropertySequence(dev, prop, value_sequence)
 
-        # TODO: SLM
+        # set all static properties, these won't change over the course of the sequence.
+        if event.properties:
+            for dev, prop, value in event.properties:
+                core.setProperty(dev, prop, value)
+
+    def setup_sequenced_event(self, event: SequencedEvent) -> None:
+        """Setup hardware for a sequenced (triggered) event.
+
+        This method is not part of the PMDAEngine protocol (it is called by
+        `setup_event`, which *is* part of the protocol), but it is made public
+        in case a user wants to subclass this engine and override this method.
+        """
+        core = self._mmc
+
+        self._load_sequenced_event(event)
+
+        # this is probably not necessary.  loadSequenceEvent will have already
+        # set all the config properties individually/manually.  However, without
+        # the call below, we won't be able to query `core.getCurrentConfig()`
+        # not sure that's necessary; and this is here for tests to pass for now,
+        # but this could be removed.
+        if event.channel is not None:
+            try:
+                core.setConfig(event.channel.group, event.channel.config)
+            except Exception as e:
+                logger.warning("Failed to set channel. %s", e)
+
+        if event.slm_image:
+            self._set_event_slm_image(event)
 
         # preparing a Sequence while another is running is dangerous.
         if core.isSequenceRunning():
             self._await_sequence_acquisition()
-        core.prepareSequenceAcquisition(cam_device)
+        core.prepareSequenceAcquisition(core.getCameraDevice())
 
         # start sequences or set non-sequenced values
         if event.x_sequence:
-            core.startXYStageSequence(stage)
+            core.startXYStageSequence(core.getXYStageDevice())
         elif event.x_pos is not None or event.y_pos is not None:
             self._set_event_position(event)
 
         if event.z_sequence:
-            core.startStageSequence(zstage)
+            core.startStageSequence(core.getFocusDevice())
         elif event.z_pos is not None:
             self._set_event_z(event)
 
         if event.exposure_sequence:
-            core.startExposureSequence(cam_device)
+            core.startExposureSequence(core.getCameraDevice())
         elif event.exposure is not None:
             core.setExposure(event.exposure)
 
-        if prop_seqs:
-            for dev, prop in prop_seqs:
+        if event.property_sequences:
+            for dev, prop in event.property_sequences:
                 core.startPropertySequence(dev, prop)
-        elif event.channel is not None:
-            core.setConfig(event.channel.group, event.channel.config)
 
     def _await_sequence_acquisition(
         self, timeout: float = 5.0, poll_interval: float = 0.2
@@ -417,6 +473,9 @@ class MDAEngine(PMDAEngine):
         t0 = event.metadata.get("runner_t0") or time.perf_counter()
         event_t0_ms = (time.perf_counter() - t0) * 1000
 
+        if event.slm_image is not None:
+            self._exec_event_slm_image(event.slm_image)
+
         # Start sequence
         # Note that the overload of startSequenceAcquisition that takes a camera
         # label does NOT automatically initialize a circular buffer.  So if this call
@@ -491,6 +550,7 @@ class MDAEngine(PMDAEngine):
             prop_values=(),
             runner_time_ms=event_t0 + seq_time,
             camera_device=camera_device,
+            include_position=self._include_frame_position_metadata is True,
         )
         meta["hardware_triggered"] = True
         meta["images_remaining_in_buffer"] = remaining
@@ -547,6 +607,55 @@ class MDAEngine(PMDAEngine):
         correction = self._z_correction.setdefault(p_idx, 0.0)
         self._mmc.setZPosition(cast("float", event.z_pos) + correction)
 
+    def _set_event_slm_image(self, event: MDAEvent) -> None:
+        if not event.slm_image:
+            return
+        try:
+            # Get the SLM device
+            if not (
+                slm_device := event.slm_image.device or self._mmc.getSLMDevice()
+            ):  # pragma: no cover
+                raise ValueError("No SLM device found or specified.")
+
+            # cast to numpy array
+            slm_array = np.asarray(event.slm_image)
+            # if it's a single value, we can just set all pixels to that value
+            if slm_array.ndim == 0:
+                value = slm_array.item()
+                if isinstance(value, bool):
+                    dev_name = self._mmc.getDeviceName(slm_device)
+                    on_value = _SLM_DEVICES_PIXEL_ON_VALUES.get(dev_name, 1)
+                    value = on_value if value else 0
+                self._mmc.setSLMPixelsTo(slm_device, int(value))
+            elif slm_array.size == 3:
+                # if it's a 3-valued array, we assume it's RGB
+                r, g, b = slm_array.astype(int)
+                self._mmc.setSLMPixelsTo(slm_device, r, g, b)
+            elif slm_array.ndim in (2, 3):
+                # if it's a 2D/3D array, we assume it's an image
+                # where 3D is RGB with shape (h, w, 3)
+                if slm_array.ndim == 3 and slm_array.shape[2] != 3:
+                    raise ValueError(  # pragma: no cover
+                        "SLM image must be 2D or 3D with 3 channels (RGB)."
+                    )
+                # convert boolean on/off values to pixel values
+                if slm_array.dtype == bool:
+                    dev_name = self._mmc.getDeviceName(slm_device)
+                    on_value = _SLM_DEVICES_PIXEL_ON_VALUES.get(dev_name, 1)
+                    slm_array = np.where(slm_array, on_value, 0).astype(np.uint8)
+                self._mmc.setSLMImage(slm_device, slm_array)
+            if event.slm_image.exposure:
+                self._mmc.setSLMExposure(slm_device, event.slm_image.exposure)
+        except Exception as e:
+            logger.warning("Failed to set SLM Image: %s", e)
+
+    def _exec_event_slm_image(self, img: useq.SLMImage) -> None:
+        if slm_device := (img.device or self._mmc.getSLMDevice()):
+            try:
+                self._mmc.displaySLMImage(slm_device)
+            except Exception as e:
+                logger.warning("Failed to set SLM Image: %s", e)
+
     def _update_config_device_props(self) -> None:
         # store devices/props that make up each config group for faster lookup
         self._config_device_props.clear()

pymmcore_plus/mda/_runner.py

@@ -274,7 +274,14 @@ class MDARunner:
     def _run(self, engine: PMDAEngine, events: Iterable[MDAEvent]) -> None:
         """Main execution of events, inside the try/except block of `run`."""
         teardown_event = getattr(engine, "teardown_event", lambda e: None)
-        event_iterator = getattr(engine, "event_iterator", iter)
+        if isinstance(events, Iterator):
+            # if an iterator is passed directly, then we use that iterator
+            # instead of the engine's event_iterator.  Directly passing an iterator
+            # is an advanced use case, (for example, `iter(Queue(), None)` for event-
+            # driven acquisition) and we don't want the engine to interfere with it.
+            event_iterator = iter
+        else:
+            event_iterator = getattr(engine, "event_iterator", iter)
         _events: Iterator[MDAEvent] = event_iterator(events)
         self._reset_event_timer()
         self._sequence_t0 = self._t0

pymmcore_plus/mda/events/__init__.py

@@ -8,12 +8,12 @@ from ._protocol import PMDASignaler
 from ._psygnal import MDASignaler
 
 if TYPE_CHECKING:
-    from ._qsignals import QMDASignaler  # noqa: TCH004
+    from ._qsignals import QMDASignaler  # noqa: TC004
 
 
 __all__ = [
-    "PMDASignaler",
     "MDASignaler",
+    "PMDASignaler",
     "QMDASignaler",
     "_get_auto_MDA_callback_class",
 ]

pymmcore_plus/mda/handlers/__init__.py

@@ -5,7 +5,7 @@ from ._tensorstore_handler import TensorStoreHandler
 
 __all__ = [
     "ImageSequenceWriter",
-    "OMEZarrWriter",
     "OMETiffWriter",
+    "OMEZarrWriter",
     "TensorStoreHandler",
 ]

pymmcore_plus/mda/handlers/_ome_zarr_writer.py

@@ -134,8 +134,8 @@ class OMEZarrWriter(_5DWriterBase["zarr.Array"]):
 
         # if we don't check this here, we'll get an error when creating the first array
         if (
-            not overwrite and any(self._group.arrays()) or self._group.attrs
-        ):  # pragma: no cover
+            not overwrite and any(self._group.arrays())
+        ) or self._group.attrs:  # pragma: no cover
             path = self._group.store.path if hasattr(self._group.store, "path") else ""
             raise ValueError(
                 f"There is already data in {path!r}. Use 'overwrite=True' to overwrite."