pymmcore-plus 0.9.3__py3-none-any.whl → 0.13.0__py3-none-any.whl

pymmcore_plus/mda/_engine.py

@@ -1,54 +1,50 @@
 from __future__ import annotations
 
 import time
-from datetime import datetime
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Iterable,
-    Iterator,
-    Mapping,
-    NamedTuple,
-    cast,
-)
+from contextlib import suppress
+from itertools import product
+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 PixelType
-from pymmcore_plus.core._sequencing import SequencedEvent
+from pymmcore_plus.core._constants import Keyword
+from pymmcore_plus.core._sequencing import SequencedEvent, iter_sequenced_events
+from pymmcore_plus.metadata import (
+    FrameMetaV1,
+    PropertyValue,
+    SummaryMetaV1,
+    frame_metadata,
+    summary_metadata,
+)
 
 from ._protocol import PMDAEngine
 
 if TYPE_CHECKING:
-    from typing import TypedDict
+    from collections.abc import Iterable, Iterator, Sequence
+    from typing import TypeAlias
 
     from numpy.typing import NDArray
 
-    from pymmcore_plus.core import CMMCorePlus, Metadata
+    from pymmcore_plus.core import CMMCorePlus
 
     from ._protocol import PImagePayload
 
-    # currently matching keys from metadata from AcqEngJ
-    SummaryMetadata = TypedDict(
-        "SummaryMetadata",
-        {
-            "DateAndTime": str,
-            "PixelType": str,
-            "PixelSize_um": float,
-            "PixelSizeAffine": str,
-            "Core-XYStage": str,
-            "Core-Focus": str,
-            "Core-Autofocus": str,
-            "Core-Camera": str,
-            "Core-Galvo": str,
-            "Core-ImageProcessor": str,
-            "Core-SLM": str,
-            "Core-Shutter": str,
-            "AffineTransform": str,
-        },
-    )
+    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):
@@ -57,6 +53,9 @@ class MDAEngine(PMDAEngine):
     This implements the [`PMDAEngine`][pymmcore_plus.mda.PMDAEngine] protocol, and
     uses a [`CMMCorePlus`][pymmcore_plus.CMMCorePlus] instance to control the hardware.
 
+    It may be subclassed to provide custom behavior, or to override specific methods.
+    <https://pymmcore-plus.github.io/pymmcore-plus/guides/custom_engine/>
+
     Attributes
     ----------
     mmcore: CMMCorePlus
@@ -66,14 +65,17 @@ class MDAEngine(PMDAEngine):
         attempt to combine MDAEvents into a single `SequencedEvent` if
         [`core.canSequenceEvents()`][pymmcore_plus.CMMCorePlus.canSequenceEvents]
         reports that the events can be sequenced. This can be set after instantiation.
-        By default, this is `False`, in order to avoid unexpected behavior, particularly
-        in testing and demo scenarios.  But in many "real world" scenarios, this can be
-        set to `True` to improve performance.
+        By default, this is `True`, however in various testing and demo scenarios, you
+        may wish to set it to `False` in order to avoid unexpected behavior.
     """
 
-    def __init__(self, mmc: CMMCorePlus, use_hardware_sequencing: bool = False) -> None:
+    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).
@@ -90,6 +92,26 @@ class MDAEngine(PMDAEngine):
         # Note: getAutoShutter() is True when no config is loaded at all
         self._autoshutter_was_set: bool = self._mmc.getAutoShutter()
 
+        # -----
+        # The following values are stored during setup_sequence simply to speed up
+        # retrieval of metadata during each frame.
+        # sequence of (device, property) of all properties used in any of the presets
+        # 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."""
@@ -97,7 +119,7 @@ class MDAEngine(PMDAEngine):
 
     # ===================== Protocol Implementation =====================
 
-    def setup_sequence(self, sequence: MDASequence) -> Mapping[str, Any]:
+    def setup_sequence(self, sequence: MDASequence) -> SummaryMetaV1 | None:
         """Setup the hardware for the entire sequence."""
         # clear z_correction for new sequence
         self._z_correction.clear()
@@ -107,6 +129,7 @@ class MDAEngine(PMDAEngine):
 
             self._mmc = CMMCorePlus.instance()
 
+        self._update_config_device_props()
         # get if the autofocus is engaged at the start of the sequence
         self._af_was_engaged = self._mmc.isContinuousFocusLocked()
 
@@ -114,30 +137,10 @@ class MDAEngine(PMDAEngine):
             self._update_grid_fov_sizes(px_size, sequence)
 
         self._autoshutter_was_set = self._mmc.getAutoShutter()
-        return self.get_summary_metadata()
+        return self.get_summary_metadata(mda_sequence=sequence)
 
-    def get_summary_metadata(self) -> SummaryMetadata:
-        """Get the summary metadata for the sequence."""
-        pt = PixelType.for_bytes(
-            self._mmc.getBytesPerPixel(), self._mmc.getNumberOfComponents()
-        )
-        affine = self._mmc.getPixelSizeAffine(True)  # true == cached
-
-        return {
-            "DateAndTime": datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f"),
-            "PixelType": str(pt),
-            "PixelSize_um": self._mmc.getPixelSizeUm(),
-            "PixelSizeAffine": ";".join(str(x) for x in affine),
-            "Core-XYStage": self._mmc.getXYStageDevice(),
-            "Core-Focus": self._mmc.getFocusDevice(),
-            "Core-Autofocus": self._mmc.getAutoFocusDevice(),
-            "Core-Camera": self._mmc.getCameraDevice(),
-            "Core-Galvo": self._mmc.getGalvoDevice(),
-            "Core-ImageProcessor": self._mmc.getImageProcessorDevice(),
-            "Core-SLM": self._mmc.getSLMDevice(),
-            "Core-Shutter": self._mmc.getShutterDevice(),
-            "AffineTransform": "Undefined",
-        }
+    def get_summary_metadata(self, mda_sequence: MDASequence | None) -> SummaryMetaV1:
+        return summary_metadata(self._mmc, mda_sequence=mda_sequence)
 
     def _update_grid_fov_sizes(self, px_size: float, sequence: MDASequence) -> None:
         *_, x_size, y_size = self._mmc.getROI()
@@ -175,7 +178,7 @@ class MDAEngine(PMDAEngine):
             # skip if no autofocus device is found
             if not self._mmc.getAutoFocusDevice():
                 logger.warning("No autofocus device found. Cannot execute autofocus.")
-                return ()
+                return
 
             try:
                 # execute hardware autofocus
@@ -190,7 +193,7 @@ class MDAEngine(PMDAEngine):
                 self._z_correction[p_idx] = new_correction + self._z_correction.get(
                     p_idx, 0.0
                 )
-            return ()
+            return
 
         # if the autofocus was engaged at the start of the sequence AND autofocus action
         # did not fail, re-engage it. NOTE: we need to do that AFTER the runner calls
@@ -214,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 =====================
 
@@ -246,9 +235,11 @@ 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.
                 self._mmc.setConfig(event.channel.group, event.channel.config)
             except Exception as e:
                 logger.warning("Failed to set channel. %s", e)
@@ -278,49 +269,77 @@ 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
+            # not sure that's what we want, but it's currently consistent with the
+            # timing of the sequenced event runner (where Elapsed_Time_ms is taken after
+            # the image is acquired, not before the exposure starts)
+            t0 = event.metadata.get("runner_t0") or time.perf_counter()
+            event_time_ms = (time.perf_counter() - t0) * 1000
         except Exception as e:
             logger.warning("Failed to snap image. %s", e)
-            return ()
+            return
         if not event.keep_shutter_open:
             self._mmc.setShutterOpen(False)
-        yield ImagePayload(self._mmc.getImage(), event, self.get_frame_metadata())
-
-    def get_frame_metadata(
-        self, meta: Metadata | None = None, channel_index: int | None = None
-    ) -> dict[str, Any]:
-        # TODO:
 
-        # this is not a very fast method, and it is called for every frame.
-        # Nico Stuurman has suggested that it was a mistake for MM to pull so much
-        # metadata for every frame.  So we'll begin with a more conservative approach.
-
-        # while users can now simply re-implement this method,
-        # consider coming up with a user-configurable way to specify needed metadata
-
-        # rather than using self._mmc.getTags (which mimics MM) we pull a smaller
-        # amount of metadata.
-        # If you need more than this, either override or open an issue.
-
-        tags = dict(meta) if meta else {}
-        for dev, label, val in self._mmc.getSystemStateCache():
-            tags[f"{dev}-{label}"] = val
-
-        # these are added by AcqEngJ
-        # yyyy-MM-dd HH:mm:ss.mmmmmm  # NOTE AcqEngJ omits microseconds
-        tags["Time"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")
+        # most cameras will only have a single channel
+        # but Multi-camera may have multiple, and we need to retrieve a buffer for each
+        for cam in range(self._mmc.getNumberOfCameraChannels()):
+            meta = self.get_frame_metadata(
+                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.
+            # https://github.com/python/mypy/issues/4976
+            yield ImagePayload(self._mmc.getImage(cam), event, meta)  # type: ignore[misc]
 
-        # used by Runner
-        tags["PerfCounter"] = time.perf_counter()
-        return tags
+    def get_frame_metadata(
+        self,
+        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):
+            prop_values = self._get_current_props(ch.group)
+        else:
+            prop_values = ()
+        return frame_metadata(
+            self._mmc,
+            cached=True,
+            runner_time_ms=runner_time_ms,
+            camera_device=camera_device,
+            property_values=prop_values,
+            mda_event=event,
+            include_position=include_position,
+        )
 
     def teardown_event(self, event: MDAEvent) -> None:
         """Teardown state of system (hardware, etc.) after `event`."""
         # autoshutter was set at the beginning of the sequence, and this event
         # doesn't want to leave the shutter open.  Re-enable autoshutter.
+        core = self._mmc
         if not event.keep_shutter_open and self._autoshutter_was_set:
-            self._mmc.setAutoShutter(True)
+            core.setAutoShutter(True)
+        # FIXME: this may not be hitting as intended...
+        # https://github.com/pymmcore-plus/pymmcore-plus/pull/353#issuecomment-2159176491
+        if isinstance(event, SequencedEvent):
+            if event.exposure_sequence:
+                core.stopExposureSequence(self._mmc.getCameraDevice())
+            if event.x_sequence:
+                core.stopXYStageSequence(core.getXYStageDevice())
+            if event.z_sequence:
+                core.stopStageSequence(core.getFocusDevice())
+            for dev, prop in event.property_sequences:
+                core.stopPropertySequence(dev, prop)
 
     def teardown_sequence(self, sequence: MDASequence) -> None:
         """Perform any teardown required after the sequence has been executed."""
@@ -328,63 +347,93 @@ 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)
         if event.x_sequence:  # y_sequence is implied and will be the same length
             stage = core.getXYStageDevice()
+            with suppress(RuntimeError):
+                core.stopXYStageSequence(stage)
             core.loadXYStageSequence(stage, event.x_sequence, event.y_sequence)
         if event.z_sequence:
-            # these notes are from Nico Stuurman in AcqEngJ
-            # https://github.com/micro-manager/AcqEngJ/pull/108
-            # at least some zStages freak out (in this case, NIDAQ board) when you
-            # try to load a sequence while the sequence is still running.  Nothing in
-            # the engine stops a stage sequence if all goes well.
-            # Stopping a sequence if it is not running hopefully will not harm anyone.
             zstage = core.getFocusDevice()
-            core.stopStageSequence(zstage)
+            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
@@ -414,9 +463,14 @@ 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.
         """
-        # TODO: add support for multiple camera devices
         n_events = len(event.events)
 
+        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
@@ -426,15 +480,17 @@ class MDAEngine(PMDAEngine):
             0,  # intervalMS  # TODO: add support for this
             True,  # stopOnOverflow
         )
-
         self.post_sequence_started(event)
 
+        n_channels = self._mmc.getNumberOfCameraChannels()
         count = 0
-        iter_events = iter(event.events)
+        iter_events = product(event.events, range(n_channels))
         # block until the sequence is done, popping images in the meantime
         while self._mmc.isSequenceRunning():
-            if self._mmc.getRemainingImageCount():
-                yield self._next_img_payload(next(iter_events))
+            if remaining := self._mmc.getRemainingImageCount():
+                yield self._next_seqimg_payload(
+                    *next(iter_events), remaining=remaining - 1, event_t0=event_t0_ms
+                )
                 count += 1
             else:
                 time.sleep(0.001)
@@ -442,23 +498,61 @@ class MDAEngine(PMDAEngine):
         if self._mmc.isBufferOverflowed():  # pragma: no cover
             raise MemoryError("Buffer overflowed")
 
-        while self._mmc.getRemainingImageCount():
-            yield self._next_img_payload(next(iter_events))
+        while remaining := self._mmc.getRemainingImageCount():
+            yield self._next_seqimg_payload(
+                *next(iter_events), remaining=remaining - 1, event_t0=event_t0_ms
+            )
             count += 1
 
-        if count != n_events:
+        # necessary?
+        expected_images = n_events * n_channels
+        if count != expected_images:
             logger.warning(
                 "Unexpected number of images returned from sequence. "
                 "Expected %s, got %s",
-                n_events,
+                expected_images,
                 count,
             )
 
-    def _next_img_payload(self, event: MDAEvent) -> PImagePayload:
+    def _next_seqimg_payload(
+        self,
+        event: MDAEvent,
+        channel: int = 0,
+        *,
+        event_t0: float = 0.0,
+        remaining: int = 0,
+    ) -> PImagePayload:
         """Grab next image from the circular buffer and return it as an ImagePayload."""
-        img, meta = self._mmc.popNextImageAndMD()
-        tags = self.get_frame_metadata(meta)
-        return ImagePayload(img, event, tags)
+        _slice = 0  # ?
+        img, mm_meta = self._mmc.popNextImageAndMD(channel, _slice)
+        try:
+            seq_time = float(mm_meta.get(Keyword.Elapsed_Time_ms))
+        except Exception:
+            seq_time = 0.0
+        try:
+            # note, when present in circular buffer meta, this key is called "Camera".
+            # It's NOT actually Keyword.CoreCamera (but it's the same value)
+            # it is hardcoded in various places in mmCoreAndDevices, see:
+            # see: https://github.com/micro-manager/mmCoreAndDevices/pull/468
+            camera_device = mm_meta.GetSingleTag("Camera").GetValue()
+        except Exception:
+            camera_device = self._mmc.getPhysicalCameraDevice(channel)
+
+        # TODO: determine whether we want to try to populate changing property values
+        # during the course of a triggered sequence
+        meta = self.get_frame_metadata(
+            event,
+            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
+        meta["camera_metadata"] = dict(mm_meta)
+
+        # https://github.com/python/mypy/issues/4976
+        return ImagePayload(img, event, meta)  # type: ignore[return-value]
 
     # ===================== EXTRA =====================
 
@@ -508,8 +602,86 @@ 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()
+        for grp in self._mmc.getAvailableConfigGroups():
+            for preset in self._mmc.getAvailableConfigs(grp):
+                # ordered/unique list of (device, property) tuples for each group
+                self._config_device_props[grp] = tuple(
+                    {(i[0], i[1]): None for i in self._mmc.getConfigData(grp, preset)}
+                )
+
+    def _get_current_props(self, *groups: str) -> tuple[PropertyValue, ...]:
+        """Faster version of core.getConfigGroupState(group).
+
+        MMCore does some excess iteration that we want to avoid here. It calls
+        GetAvailableConfigs and then calls getConfigData for *every* preset in the
+        group, (not only the one being requested).  We go straight to cached data
+        for the group we want.
+        """
+        return tuple(
+            {
+                "dev": dev,
+                "prop": prop,
+                "val": self._mmc.getPropertyFromCache(dev, prop),
+            }
+            for group in groups
+            if (dev_props := self._config_device_props.get(group))
+            for dev, prop in dev_props
+        )
+
 
 class ImagePayload(NamedTuple):
     image: NDArray
     event: MDAEvent
-    metadata: dict
+    metadata: FrameMetaV1 | SummaryMetaV1