pymmcore-plus 0.10.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

pymmcore_plus/core/_mmcore_plus.py

@@ -31,6 +31,7 @@ from psygnal import SignalInstance
 from pymmcore_plus._logger import current_logfile, logger
 from pymmcore_plus._util import find_micromanager, print_tabular_data
 from pymmcore_plus.mda import MDAEngine, MDARunner, PMDAEngine
+from pymmcore_plus.metadata.functions import summary_metadata
 
 from ._adapter import DeviceAdapter
 from ._config import Configuration
@@ -39,6 +40,7 @@ from ._constants import (
     DeviceDetectionStatus,
     DeviceInitializationState,
     DeviceType,
+    FocusDirection,
     PixelType,
     PropertyType,
 )
@@ -46,7 +48,6 @@ from ._device import Device
 from ._metadata import Metadata
 from ._property import DeviceProperty
 from ._sequencing import can_sequence_events
-from ._state import core_state
 from .events import CMMCoreSignaler, PCoreSignaler, _get_auto_core_callback_class
 
 if TYPE_CHECKING:
@@ -56,8 +57,7 @@ if TYPE_CHECKING:
     from useq import MDAEvent
 
     from pymmcore_plus.mda._runner import SingleOutput
-
-    from ._state import StateDict
+    from pymmcore_plus.metadata.schema import SummaryMetaV1
 
     _T = TypeVar("_T")
     _F = TypeVar("_F", bound=Callable[..., Any])
@@ -193,6 +193,9 @@ class CMMCorePlus(pymmcore.CMMCore):
         if _instance is None:
             _instance = self
 
+        if hasattr("self", "enableFeature"):
+            self.enableFeature("StrictInitializationChecks", True)
+
         # TODO: test this on windows ... writing to the same file may be an issue there
         if logfile := current_logfile(logger):
             self.setPrimaryLogFile(str(logfile))
@@ -400,6 +403,14 @@ class CMMCorePlus(pymmcore.CMMCore):
         """
         return DeviceType(super().getDeviceType(label))
 
+    def getFocusDirection(self, stageLabel: str) -> FocusDirection:
+        """Return device type for a given device.
+
+        **Why Override?** The returned [`pymmcore_plus.FocusDirection`][] enum is more
+        interpretable than the raw `int` returned by `pymmcore`
+        """
+        return FocusDirection(super().getFocusDirection(stageLabel))
+
     def getPropertyType(self, label: str, propName: str) -> PropertyType:
         """Return the intrinsic property type for a given device and property.
 
@@ -621,7 +632,7 @@ class CMMCorePlus(pymmcore.CMMCore):
 
     @synchronized(_lock)
     def popNextImageAndMD(
-        self, channel: int | None = None, slice: int | None = None, *, fix: bool = True
+        self, channel: int = 0, slice: int = 0, *, fix: bool = True
     ) -> tuple[np.ndarray, Metadata]:
         """Gets and removes the next image (and metadata) from the circular buffer.
 
@@ -651,10 +662,7 @@ class CMMCorePlus(pymmcore.CMMCore):
             Image and metadata
         """
         md = Metadata()
-        if channel is not None and slice is not None:
-            img = super().popNextImageMD(channel, slice, md)
-        else:
-            img = super().popNextImageMD(md)
+        img = super().popNextImageMD(channel, slice, md)
         return (self.fixImage(img) if fix else img, md)
 
     @synchronized(_lock)
@@ -1470,7 +1478,11 @@ class CMMCorePlus(pymmcore.CMMCore):
         old_engine = self.mda.set_engine(engine)
         self.events.mdaEngineRegistered.emit(engine, old_engine)
 
-    def fixImage(self, img: np.ndarray, ncomponents: int | None = None) -> np.ndarray:
+    def fixImage(
+        self,
+        img: np.ndarray,
+        ncomponents: int | None = None,
+    ) -> np.ndarray:
         """Fix img shape/dtype based on `self.getNumberOfComponents()`.
 
         :sparkles: *This method is new in `CMMCorePlus`.*
@@ -1498,6 +1510,28 @@ class CMMCorePlus(pymmcore.CMMCore):
             img = img[..., [2, 1, 0]]  # Convert from BGRA to RGB
         return img
 
+    def getPhysicalCameraDevice(self, channel_index: int = 0) -> str:
+        """Return the name of the actual camera device for a given channel index.
+
+        :sparkles: *This method is new in `CMMCorePlus`.* It provides a convenience
+        for accessing the name of the actual camera device when using the multi-camera
+        utility.
+        """
+        cam_dev = self.getCameraDevice()
+        # best as I can tell, this is a hard-coded string in Utilities/MultiCamera.cpp
+        # (it also appears in ArduinoCounter.cpp).  This appears to be "the way"
+        # to get at the original camera when using the multi-camera utility.
+        prop_name = f"Physical Camera {channel_index+1}"
+        if self.hasProperty(cam_dev, prop_name):
+            return self.getProperty(cam_dev, prop_name)
+        if channel_index > 0:
+            warnings.warn(
+                f"Camera {cam_dev} does not have a property {prop_name}. "
+                f"Cannot get channel_index={channel_index}",
+                stacklevel=2,
+            )
+        return cam_dev
+
     def getTaggedImage(self, channel_index: int = 0) -> TaggedImage:
         """Return getImage as named tuple with metadata.
 
@@ -1570,15 +1604,9 @@ class CMMCorePlus(pymmcore.CMMCore):
             tags["Binning"] = self.getProperty(self.getCameraDevice(), "Binning")
 
         if channel_index is not None:
-            if "CameraChannelIndex" not in tags:
-                tags["CameraChannelIndex"] = channel_index
-                tags["ChannelIndex"] = channel_index
-            if "Camera" not in tags:
-                core_cam = tags.get("Core-Camera")
-                phys_cam_key = f"{core_cam}-Physical Camera {channel_index+1}"
-                if phys_cam_key in tags:
-                    tags["Camera"] = tags[phys_cam_key]
-                    # tags["Channel"] = tags[phys_cam_key] # ?? why did MMCoreJ do this?
+            tags["CameraChannelIndex"] = channel_index
+            tags["ChannelIndex"] = channel_index
+            tags["Camera"] = self.getPhysicalCameraDevice(channel_index)
 
         # these are added by AcqEngJ
         # yyyy-MM-dd HH:mm:ss.mmmmmm  # NOTE AcqEngJ omits microseconds
@@ -2009,35 +2037,17 @@ class CMMCorePlus(pymmcore.CMMCore):
         print_tabular_data(data, sort=sort)
 
     def state(
-        self,
-        *,
-        devices: bool = True,
-        image: bool = True,
-        system_info: bool = False,
-        system_status: bool = False,
-        config_groups: bool | Sequence[str] = True,
-        position: bool = False,
-        autofocus: bool = False,
-        pixel_size_configs: bool = False,
-        device_types: bool = False,
-        cached: bool = True,
-        error_value: Any = None,
-    ) -> StateDict:
+        self, *, cached: bool = True, include_time: bool = False, **_kwargs: Any
+    ) -> SummaryMetaV1:
         """Return info on the current state of the core."""
-        return core_state(
-            self,
-            devices=devices,
-            image=image,
-            system_info=system_info,
-            system_status=system_status,
-            config_groups=config_groups,
-            position=position,
-            autofocus=autofocus,
-            pixel_size_configs=pixel_size_configs,
-            device_types=device_types,
-            cached=cached,
-            error_value=error_value,
-        )
+        if _kwargs:
+            keys = ", ".join(_kwargs.keys())
+            warnings.warn(
+                f"CMMCorePlus.state no longer takes arguments: {keys}. Ignoring."
+                "Please update your code as this may be an error in the future.",
+                stacklevel=2,
+            )
+        return summary_metadata(self, include_time=include_time, cached=cached)
 
     @contextmanager
     def _property_change_emission_ensured(
@@ -2061,8 +2071,18 @@ class CMMCorePlus(pymmcore.CMMCore):
             and self.getDeviceType(device) is DeviceType.StateDevice
         ):
             properties = STATE_PROPS
+        try:
+            before = [self.getProperty(device, p) for p in properties]
+        except Exception as e:
+            logger.error(
+                "Error getting properties %s on %s: %s. Cannot ensure signal emission",
+                properties,
+                device,
+                e,
+            )
+            yield
+            return
 
-        before = [self.getProperty(device, p) for p in properties]
         with _blockSignal(self.events, self.events.propertyChanged):
             yield
         after = [self.getProperty(device, p) for p in properties]

pymmcore_plus/core/events/_psygnal.py

@@ -1,11 +1,11 @@
-from psygnal import Signal, SignalInstance
+from psygnal import Signal, SignalGroup, SignalInstance
 
 from pymmcore_plus.mda import MDAEngine
 
 from ._prop_event_mixin import _DevicePropertyEventMixin
 
 
-class CMMCoreSignaler(_DevicePropertyEventMixin):
+class CMMCoreSignaler(SignalGroup, _DevicePropertyEventMixin):
     """Signals that will be emitted from CMMCorePlus objects."""
 
     # native MMCore callback events

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",
-    "PMDAEngine",
     "MDARunner",
+    "PMDAEngine",
     "PMDASignaler",
-    "mda_listeners_connected",
 ]

pymmcore_plus/mda/_engine.py

@@ -2,14 +2,13 @@ from __future__ import annotations
 
 import time
 from contextlib import suppress
-from datetime import datetime
+from itertools import product
 from typing import (
     TYPE_CHECKING,
-    Any,
     Iterable,
     Iterator,
-    Mapping,
     NamedTuple,
+    Sequence,
     cast,
 )
 
@@ -17,40 +16,25 @@ 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._constants import Keyword
 from pymmcore_plus.core._sequencing import SequencedEvent
+from pymmcore_plus.metadata import (
+    FrameMetaV1,
+    PropertyValue,
+    SummaryMetaV1,
+    frame_metadata,
+    summary_metadata,
+)
 
 from ._protocol import PMDAEngine
 
 if TYPE_CHECKING:
-    from typing import TypedDict
-
     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,
-        },
-    )
-
 
 class MDAEngine(PMDAEngine):
     """The default MDAengine that ships with pymmcore-plus.
@@ -58,6 +42,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
@@ -91,6 +78,13 @@ 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 mmcore(self) -> CMMCorePlus:
         """The `CMMCorePlus` instance to use for hardware control."""
@@ -98,7 +92,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()
@@ -108,6 +102,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()
 
@@ -115,30 +110,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()
@@ -250,6 +225,7 @@ class MDAEngine(PMDAEngine):
 
         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)
@@ -281,46 +257,50 @@ class MDAEngine(PMDAEngine):
         """
         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
         if not event.keep_shutter_open:
             self._mmc.setShutterOpen(False)
-        yield ImagePayload(self._mmc.getImage(), event, self.get_frame_metadata())
+
+        # 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),
+            )
+            # 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]
 
     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")
-        tags["PixelSizeUm"] = self._mmc.getPixelSizeUm(True)  # true == cached
-        with suppress(RuntimeError):
-            tags["XPositionUm"] = self._mmc.getXPosition()
-            tags["YPositionUm"] = self._mmc.getYPosition()
-        with suppress(RuntimeError):
-            tags["ZPositionUm"] = self._mmc.getZPosition()
-
-        # used by Runner
-        tags["PerfCounter"] = time.perf_counter()
-        return tags
+        self,
+        event: MDAEvent,
+        prop_values: tuple[PropertyValue, ...] | None = None,
+        runner_time_ms: float = 0.0,
+        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,
+        )
 
     def teardown_event(self, event: MDAEvent) -> None:
         """Teardown state of system (hardware, etc.) after `event`."""
@@ -434,9 +414,11 @@ 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
+
         # Start sequence
         # Note that the overload of startSequenceAcquisition that takes a camera
         # label does NOT automatically initialize a circular buffer.  So if this call
@@ -446,15 +428,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)
@@ -462,23 +446,60 @@ 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,
+        )
+        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 =====================
 
@@ -528,8 +549,37 @@ class MDAEngine(PMDAEngine):
         correction = self._z_correction.setdefault(p_idx, 0.0)
         self._mmc.setZPosition(cast("float", event.z_pos) + correction)
 
+    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

pymmcore_plus/mda/_protocol.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from abc import abstractmethod
-from typing import TYPE_CHECKING, Any, Mapping, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     from typing import Iterable, Iterator
@@ -9,7 +9,9 @@ if TYPE_CHECKING:
     from numpy.typing import NDArray
     from useq import MDAEvent, MDASequence
 
-    PImagePayload = tuple[NDArray, MDAEvent, dict]
+    from pymmcore_plus.metadata.schema import FrameMetaV1, SummaryMetaV1
+
+    PImagePayload = tuple[NDArray, MDAEvent, FrameMetaV1]
 
 
 # NOTE: This whole thing could potentially go in useq-schema
@@ -21,7 +23,7 @@ class PMDAEngine(Protocol):
     """Protocol that all MDA engines must implement."""
 
     @abstractmethod
-    def setup_sequence(self, sequence: MDASequence) -> None | Mapping[str, Any]:
+    def setup_sequence(self, sequence: MDASequence) -> SummaryMetaV1 | None:
         """Setup state of system (hardware, etc.) before an MDA is run.
 
         This method is called once at the beginning of a sequence.