mesofield 0.3.2b0__py3-none-any.whl

mesofield/engines.py

@@ -0,0 +1,380 @@
+"""Custom MicroManager ``MDAEngine`` subclasses used by mesofield.
+
+Three flavours are provided, all subclasses of
+:class:`pymmcore_plus.mda.MDAEngine`:
+
+``MesoEngine``
+    Drives the mesoscope camera; loads an LED sequence on the Arduino
+    switch in :meth:`MesoEngine.setup_sequence` and streams images out of
+    the circular buffer in :meth:`MesoEngine.exec_sequenced_event`.
+
+``PupilEngine``
+    Drives the pupil camera; optionally pulses an NI-DAQ line at
+    sequence start (used for synchronisation with downstream
+    instruments).
+
+``DevEngine``
+    Hardware-free development engine. Streams whatever the camera
+    backend produces with no Arduino/NIDAQ interaction; intended for
+    mock cameras and CI.
+"""
+
+import nidaqmx.system
+import useq
+import time
+from itertools import product
+
+from typing import TYPE_CHECKING, Iterable, Mapping, Sequence
+if TYPE_CHECKING:
+    from pymmcore_plus.core._sequencing import SequencedEvent
+    from pymmcore_plus.mda.metadata import FrameMetaV1 # type: ignore
+    from numpy.typing import NDArray
+    from useq import MDAEvent
+    PImagePayload = tuple[NDArray, MDAEvent, FrameMetaV1]  
+    
+from pymmcore_plus.metadata import SummaryMetaV1
+from pymmcore_plus.mda import MDAEngine
+import nidaqmx
+from mesofield.utils._logger import get_logger
+
+logger = get_logger(__name__)
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from mesofield.config import ExperimentConfig
+    from pymmcore_plus import CMMCorePlus
+
+class MesoEngine(MDAEngine):
+    """MDA engine for the mesoscope camera.
+
+    Loads an LED switching sequence onto an Arduino driver in
+    :meth:`setup_sequence`, then streams images out of the camera's
+    circular buffer in :meth:`exec_sequenced_event`. Subclasses
+    :class:`pymmcore_plus.mda.MDAEngine`.
+    """
+
+    def __init__(self, mmc, use_hardware_sequencing: bool = True) -> None:
+        super().__init__(mmc)
+        self.logger = get_logger(f'{__name__}.{self.__class__.__name__}')
+        self._mmc: CMMCorePlus = mmc
+        self.use_hardware_sequencing = use_hardware_sequencing
+        self._wheel_data = None
+        # TODO: add triggerable parameter
+
+    def set_config(self, cfg) -> None:
+        """Bind a live :class:`~mesofield.config.ExperimentConfig` to this engine.
+
+        Called by the :class:`~mesofield.base.Procedure` orchestrator after
+        hardware is up so the engine can reach the configured encoder.
+        """
+        self._config: ExperimentConfig = cfg
+        self._encoder = cfg.hardware.encoder
+    
+    def setup_sequence(self, sequence: useq.MDASequence) -> SummaryMetaV1 | None:
+        """Perform setup required before the sequence is executed."""
+
+        led_sequence = sequence.metadata.get('led_sequence')
+        if not led_sequence and hasattr(self, '_config'):
+            led_sequence = self._config.led_pattern
+        if not led_sequence:
+            raise ValueError('Missing led_sequence in MDASequence metadata and ExperimentConfig')
+
+        camera = getattr(self, 'camera', None)
+        self.logger.debug(
+            f"setup_sequence: engine.camera={'set' if camera is not None else 'None'} "
+            f"has_start_led={hasattr(camera, 'start_led_sequence') if camera else False}"
+        )
+        if camera is not None and hasattr(camera, 'start_led_sequence'):
+            camera.start_led_sequence(led_sequence)
+        else:
+            self._mmc.getPropertyObject('Arduino-Switch', 'State').loadSequence(led_sequence)
+            self._mmc.getPropertyObject('Arduino-Switch', 'State').setValue(4) # seems essential to initiate serial communication
+            self._mmc.getPropertyObject('Arduino-Switch', 'State').startSequence()
+
+        self.logger.debug(f'setup_sequence loaded LED sequence at time: {time.time()}')
+
+        return super().setup_sequence(sequence)
+    
+    def exec_sequenced_event(self, event: 'SequencedEvent') -> Iterable['PImagePayload']:
+        """Execute a sequenced (triggered) event and return the image data.
+
+        This method is not part of the PMDAEngine protocol (it is called by
+        `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.
+        """
+
+        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
+        # is changed to accept the camera in the future, that should be kept in mind.
+        self._mmc.startSequenceAcquisition(
+            n_events,
+            0,  # intervalMS  
+            True,  # stopOnOverflow
+        )
+        self.logger.debug(f'exec_sequenced_event with {n_events} events at t0 {t0}')
+        self.post_sequence_started(event)
+
+        n_channels = self._mmc.getNumberOfCameraChannels()
+        count = 0
+        iter_events = product(event.events, range(n_channels))
+        # block until the sequence is done, popping images in the meantime
+        while self._mmc.isSequenceRunning():
+            if remaining := self._mmc.getRemainingImageCount():
+                img, mm_meta = self._mmc.popNextImageAndMD()
+                ev, ch = next(iter_events)
+                yield self._create_seqimg_payload_from_popped(
+                    img, mm_meta, event=ev, channel=ch, remaining=remaining - 1, event_t0=event_t0_ms
+                )
+                count += 1
+            else:
+                if count == n_events:
+                    self.logger.debug(f'stopped MDA with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+                    break
+                    #self._mmc.stopSequenceAcquisition() Might be source of early cutoff by not allowing engine to save the rest of image in buffer
+                #time.sleep(0.001) #does not seem to optimize performance either way
+
+        if self._mmc.isBufferOverflowed():  # pragma: no cover
+            self.logger.warning(f'OVERFLOW MDA: {self._mmc} with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+            raise MemoryError("Buffer overflowed")
+
+        while remaining := self._mmc.getRemainingImageCount():
+            self.logger.debug(f'Saving Remaining Images in buffer {self._mmc} with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+            img, mm_meta = self._mmc.popNextImageAndMD()
+            ev, ch = next(iter_events)
+            yield self._create_seqimg_payload_from_popped(
+                img, mm_meta, event=ev, channel=ch, remaining=remaining - 1, event_t0=event_t0_ms
+            )
+            count += 1
+    
+    def teardown_sequence(self, sequence: useq.MDASequence) -> None:
+        """Perform any teardown required after the sequence has been executed."""
+        self.logger.debug(f'teardown_sequence at time: {time.time()}')
+
+        # Stop the Arduino LED Sequence
+        camera = getattr(self, 'camera', None)
+        if camera is not None and hasattr(camera, 'stop_led_sequence'):
+            camera.stop_led_sequence()
+        else:
+            self._mmc.getPropertyObject('Arduino-Switch', 'State').stopSequence()
+
+
+class PupilEngine(MDAEngine):
+    """MDA engine for the pupil camera with optional NI-DAQ triggering.
+
+    On :meth:`setup_sequence` an NI-DAQ object may be loaded from the
+    sequence metadata; on :meth:`exec_sequenced_event` that NI-DAQ is
+    pulsed at sequence start so other instruments can synchronise.
+    Subclasses :class:`pymmcore_plus.mda.MDAEngine`.
+    """
+
+    def __init__(self, mmc, use_hardware_sequencing: bool = True) -> None:
+        super().__init__(mmc)
+        self._mmc: CMMCorePlus = mmc
+        self.use_hardware_sequencing = use_hardware_sequencing
+        self._wheel_data = None
+        # TODO: add triggerable parameter
+        self.logger = get_logger(f'{__name__}.{self.__class__.__name__}')
+
+    def set_config(self, cfg: 'ExperimentConfig') -> None:
+        """Bind a live :class:`~mesofield.config.ExperimentConfig`.
+
+        Caches the configured NI-DAQ device and (when more than one
+        ``CMMCorePlus`` is in play) a reference to the primary core.
+        """
+        self._config = cfg
+        self.nidaq = cfg.hardware.nidaq
+        if len(self._config._cores) > 1:
+            self._mmc1 = cfg._cores[0]
+        else:
+            self._mmc1 = None
+
+    def setup_sequence(self, sequence: useq.MDASequence) -> SummaryMetaV1 | None:
+        """Resolve the NI-DAQ from sequence metadata and reset it for the run."""
+        self.nidaq = sequence.metadata.get("nidaq")
+        if self.nidaq is not None:
+            self.nidaq.reset()
+        self.logger.debug(f'setup_sequence loaded Nidaq: {self.nidaq}')
+        return super().setup_sequence(sequence)
+        
+    def exec_sequenced_event(self, event: 'SequencedEvent') -> Iterable['PImagePayload']:
+        """Execute a sequenced (triggered) event and return the image data.
+
+        This method is not part of the PMDAEngine protocol (it is called by
+        `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.
+        """
+        n_events = len(event.events)
+
+        t0 = event.metadata.get("runner_t0") or time.perf_counter()
+        event_t0_ms = (time.perf_counter() - t0) * 1000
+
+        #https://github.com/pymmcore-plus/useq-schema/issues/213 
+        if self.nidaq is not None:# and self.io_type == "DO":
+            self.nidaq.start()
+
+
+        # Start sequence
+        # Note that the overload of startSequenceAcquisition that takes a camera
+        # label does NOT automatically initialize a circular buffer.  So if this call
+        # is changed to accept the camera in the future, that should be kept in mind.
+        self._mmc.startSequenceAcquisition(
+            n_events,
+            0,  # intervalMS  # TODO: add support for this
+            True,  # stopOnOverflow
+        )
+        self.logger.debug(f'exec_sequenced_event with {n_events} events at t0 {t0}')
+        self.post_sequence_started(event)
+
+        n_channels = self._mmc.getNumberOfCameraChannels()
+        count = 0
+        iter_events = product(event.events, range(n_channels))
+
+
+        # block until the sequence is done, popping images in the meantime
+        while True:
+            if self._mmc.isSequenceRunning():
+                if remaining := self._mmc.getRemainingImageCount():
+                    img, mm_meta = self._mmc.popNextImageAndMD()
+                    ev, ch = next(iter_events)
+                    yield self._create_seqimg_payload_from_popped(
+                        img, mm_meta, event=ev, channel=ch, remaining=remaining - 1, event_t0=event_t0_ms
+                    )
+                    count += 1
+                else:
+                    if count == n_events: # or self._mmc1 is not None and self._mmc1.isSequenceRunning() is not True:
+                        self.logger.debug(f'stopped MDA with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+                        self._mmc.stopSequenceAcquisition() 
+                        break
+                    time.sleep(0.001)
+            else:
+                break
+
+        if self._mmc.isBufferOverflowed():  # pragma: no cover
+            self.logger.warning(f'OVERFLOW MDA: {self._mmc} with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+            raise MemoryError("Buffer overflowed")
+
+        while remaining := self._mmc.getRemainingImageCount():
+            self.logger.debug(f'Saving Remaining Images in buffer {self._mmc} with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+            img, mm_meta = self._mmc.popNextImageAndMD()
+            ev, ch = next(iter_events)
+            yield self._create_seqimg_payload_from_popped(
+                img, mm_meta, event=ev, channel=ch, remaining=remaining - 1, event_t0=event_t0_ms
+            )
+            count += 1
+    
+    def teardown_sequence(self, sequence: useq.MDASequence) -> None:
+        """Perform any teardown required after the sequence has been executed."""
+        self.logger.debug(f'teardown_sequence at time: {time.time()}')
+        # self.nidaq.stop()
+        # # Save exposure times from nidaq
+        # times = self.nidaq.get_exposure_times()
+        # path = self._config.make_path('nidaq_timestamps', 'txt', 'func')
+        # with open(path, 'w') as f:
+        #     for t in times:
+        #         f.write(f"{t}\n")
+        
+        #self._encoder.stop()
+        # Get and store the encoder data
+        #self._wheel_data = self._encoder.get_data()
+        #self._config.save_wheel_encoder_data(self._wheel_data)
+        #self._config.save_configuration()
+
+        pass
+    
+
+
+
+class DevEngine(MDAEngine):
+    """Hardware-free development engine for mock cameras and CI.
+
+    Streams images out of the camera's circular buffer with no Arduino
+    or NI-DAQ interaction. Use this engine for development and tests
+    that don't have access to physical rig hardware.
+    """
+
+    def __init__(self, mmc, use_hardware_sequencing: bool = True) -> None:
+        super().__init__(mmc)
+        self._mmc = mmc
+        self.use_hardware_sequencing = use_hardware_sequencing
+        self._config = None
+        self.logger = get_logger(f'{__name__}.{self.__class__.__name__}')
+
+        self._encoder: SerialWorker = None
+
+    def set_config(self, cfg) -> None:
+        """Bind a live :class:`~mesofield.config.ExperimentConfig` to this engine."""
+        self._config = cfg
+    
+    def exec_sequenced_event(self, event: 'SequencedEvent') -> Iterable['PImagePayload']:
+        """Execute a sequenced (triggered) event and return the image data.
+
+        This method is not part of the PMDAEngine protocol (it is called by
+        `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.
+        """
+        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
+        # is changed to accept the camera in the future, that should be kept in mind.
+        self._mmc.startSequenceAcquisition(
+            n_events,
+            0,  # intervalMS  
+            True,  # stopOnOverflow
+        )
+        self.logger.info(f'exec_sequenced_event with {n_events} events at t0 {t0}')
+        self.post_sequence_started(event)
+
+        n_channels = self._mmc.getNumberOfCameraChannels()
+        count = 0
+        iter_events = product(event.events, range(n_channels))
+        # block until the sequence is done, popping images in the meantime
+        while True:
+            if self._mmc.isSequenceRunning():
+                if remaining := self._mmc.getRemainingImageCount():
+                    img, mm_meta = self._mmc.popNextImageAndMD()
+                    ev, ch = next(iter_events)
+                    yield self._create_seqimg_payload_from_popped(
+                        img, mm_meta, event=ev, channel=ch, remaining=remaining - 1, event_t0=event_t0_ms
+                    )
+                    count += 1
+                else:
+                    if count == n_events:
+                        self.logger.debug(f'stopped MDA with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+                        self._mmc.stopSequenceAcquisition() 
+                        break
+                    time.sleep(0.001)
+            else:
+                break
+
+        if self._mmc.isBufferOverflowed():  # pragma: no cover
+            self.logger.warning(f'OVERFLOW MDA: {self._mmc} with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+            raise MemoryError("Buffer overflowed")
+
+        while remaining := self._mmc.getRemainingImageCount():
+            self.logger.debug(f'Saving Remaining Images in buffer {self._mmc} with {count} events and {remaining} remaining with {self._mmc.getRemainingImageCount()} images in buffer')
+            img, mm_meta = self._mmc.popNextImageAndMD()
+            ev, ch = next(iter_events)
+            yield self._create_seqimg_payload_from_popped(
+                img, mm_meta, event=ev, channel=ch, remaining=remaining - 1, event_t0=event_t0_ms
+            )
+            count += 1
+    
+    def teardown_sequence(self, sequence: useq.MDASequence) -> None:
+        """Perform any teardown required after the sequence has been executed."""
+        self.logger.info(f'teardown_sequence at time: {time.time()}')
+        # self._encoder.stop()
+        # Get and store the encoder data
+        # self._wheel_data = self._encoder.get_data()
+        # self._config.save_wheel_encoder_data(self._wheel_data)
+        # self._config.save_configuration()
+        pass

mesofield/gui/__init__.py

@@ -0,0 +1,76 @@
+"""Mesofield Qt GUI package.
+
+Defines the desktop application widgets used by ``mesofield launch``:
+the main window, acquisition view, dynamic device controls, config
+wizard, image preview, and serial / encoder plotters.
+
+This top-level module exposes :class:`ConfigTableModel`, a thin
+``QAbstractTableModel`` that presents a :class:`ConfigRegister` as a
+table of (key, value) rows so the GUI can edit experiment parameters
+live.
+"""
+
+from typing import Any, List
+
+from PyQt6.QtCore import Qt, QAbstractTableModel, QModelIndex, QVariant
+
+class ConfigTableModel(QAbstractTableModel):
+    """A table model that presents ConfigRegister as rows of (key, value)."""
+    def __init__(self, registry):
+        super().__init__()
+        self._registry = registry
+        self._keys: List[str] = self._registry.keys()
+        # Listen to external changes
+        for key in self._keys:
+            self._registry.register_callback(key, self._on_config_changed)
+
+    def rowCount(self, parent=QModelIndex()):
+        return len(self._keys)
+
+    def columnCount(self, parent=QModelIndex()):
+        return 2  # "Parameter" and "Value"
+
+    def data(self, index: QModelIndex, role=Qt.ItemDataRole.DisplayRole):
+        if not index.isValid():
+            return QVariant()
+        key = self._keys[index.row()]
+
+        if role == Qt.ItemDataRole.DisplayRole:
+            if index.column() == 0:
+                return key
+            elif index.column() == 1:
+                return str(self._registry.get(key))
+        return QVariant()
+
+    def headerData(self, section: int, orientation, role=Qt.ItemDataRole.DisplayRole):
+        if role == Qt.ItemDataRole.DisplayRole and orientation == Qt.Orientation.Horizontal:
+            return ["Parameter", "Value"][section]
+        return super().headerData(section, orientation, role)
+
+    def flags(self, index: QModelIndex):
+        base = super().flags(index)
+        if index.column() == 1:
+            return base | Qt.ItemFlag.ItemIsEditable
+        return base
+
+    def setData(self, index: QModelIndex, value: Any, role=Qt.ItemDataRole.EditRole):
+        if index.isValid() and index.column() == 1 and role == Qt.ItemDataRole.EditRole:
+            key = self._keys[index.row()]
+            try:
+                # Attempt to set the new value (will auto-convert via ConfigRegister)
+                self._registry.set(key, value)
+                self.dataChanged.emit(index, index, [Qt.ItemDataRole.DisplayRole])
+                return True
+            except TypeError as e:
+                # you could pop up a QMessageBox here
+                print(f"Type error: {e}")
+        return False
+
+    def _on_config_changed(self, key: str, new_val: Any):
+        """Called by ConfigRegister whenever a key changes externally."""
+        try:
+            row = self._keys.index(key)
+        except ValueError:
+            return
+        idx = self.index(row, 1)
+        self.dataChanged.emit(idx, idx, [Qt.ItemDataRole.DisplayRole])