Skip to content

Events#

There are two objects that emit events in pymmcore-plus:

  1. The CMMCorePlus object emits events at CMMCorePlus.events when the state of the microscope changes.
  2. The MDARunner object emits events at CMMCorePlus.mda.events as an acquisition sequence progresses.

The events emitted by these two objects are defined by the following protocols:

pymmcore_plus.core.events.PCoreSignaler #

Declares the protocol for all signals that will be emitted from CMMCorePlus.

The main instance of this interface is available on the CMMCorePlus object at the events attribute. Each signal on events is an object has a connect and a disconnect method that you can use to connect/disconnect your own callback functions. connect and disconnect accept a single argument, which is a callable that will be called when the signal is emitted. The callable should accept no more positional arguments than the signal emits (noted for each signal below), but may accept fewer.

Note

These events are a superset of those emitted by MMEventCallback in the MMCore C++ library. The "on" prefix has been removed from the names here and the first letter lower cased.

Important

In the core C++ library (and in pymmcore), the emission of many of these events is left to the discretion of the device adapter. In pymmcore_plus, we attempt to emit these events in a more consistent manner (e.g. by checking a particular value before and after calling into the C++ library). So, the emission of these events is not guaranteed to be 1:1 with the C++ library; however, it should be easier to follow the state of the core when using pymmcore_plus.CMMCorePlus.

Examples:

To connect to the onExposureChanged event emitted by MMCore, you would connect to the exposureChanged signal on this class:

from pymmcore_plus import CMMCorePlus

core = CMMCorePlus()


def on_exposure_changed(device: str, new_exposure: float):
    print(f"Exposure changed for {device} to {new_exposure}")


core.events.exposureChanged.connect(my_callback)

Events may also be connected as a decorator:

@core.events.exposureChanged.connect
def on_exposure_changed(device: str, new_exposure: float): ...

SLMExposureChanged: PSignal class-attribute #

Emits (name: str, newExposure: float) when the exposure of the SLM device changes.

XYStagePositionChanged: PSignal class-attribute #

Emits (name: str, xpos: float, ypos: float) when an XY stage position has changed.

autoShutterSet: PSignal class-attribute #

Emits (bool) when the auto shutter setting is changed.

channelGroupChanged: PSignal class-attribute #

Emits (newChannelGroupName: str) when a channel group has changed.

configDefined: PSignal class-attribute #

Emits (str, str, str, str, str) when a config is defined.

✨ This signal is unique to pymmcore-plus.

configDeleted: PSignal class-attribute #

Emits (str, str) when a config is deleted.

✨ This signal is unique to pymmcore-plus.

configGroupChanged: PSignal class-attribute #

Emits (groupName: str, newConfigName: str) when a config group has changed.

configGroupDeleted: PSignal class-attribute #

Emits (str) when a config group is deleted.

✨ This signal is unique to pymmcore-plus.

configSet: PSignal class-attribute #

Emits (str, str) when a config has been set.

✨ This signal is unique to pymmcore-plus.

continuousSequenceAcquisitionStarted: PSignal class-attribute #

Emits with no arguments when continuous sequence acquisition is started.

✨ This signal is unique to pymmcore-plus.

exposureChanged: PSignal class-attribute #

Emits (name: str, newExposure: float) when an exposure has changed.

imageSnapped: PSignal class-attribute #

Emits with no arguments whenever snap is called.

✨ This signal is unique to pymmcore-plus.

mdaEngineRegistered: PSignal class-attribute #

Emits (MDAEngine, MDAEngine) when an MDAEngine is registered.

✨ This signal is unique to pymmcore-plus.

pixelSizeAffineChanged: PSignal class-attribute #

Emits (float, float, float, float, float, float) when the pixel size affine has changed.

pixelSizeChanged: PSignal class-attribute #

Emits (newPixelSizeUm: float) when the pixel size has changed.

propertiesChanged: PSignal class-attribute #

Emits with no arguments when properties have changed.

propertyChanged: PSignal class-attribute #

Emits (name: str, : propName: str, propValue: str) when a specific property has changed.

roiSet: PSignal class-attribute #

Emits (str, int, int, int, int) when an ROI is set.

✨ This signal is unique to pymmcore-plus.

sequenceAcquisitionStarted: PSignal class-attribute #

Emits (str, int, float, bool) when sequence acquisition is started.

✨ This signal is unique to pymmcore-plus.

sequenceAcquisitionStopped: PSignal class-attribute #

Emits (str) when sequence acquisition is stopped.

✨ This signal is unique to pymmcore-plus.

stagePositionChanged: PSignal class-attribute #

Emits (name: str, pos: float) when a stage position has changed.

systemConfigurationLoaded: PSignal class-attribute #

Emits with no arguments when the system configuration has been loaded.

devicePropertyChanged(device: str, property: Optional[str] = None) -> PSignalInstance #

Return object to connect/disconnect to device/property-specific changes.

Note that the callback provided to .connect() must take two parameters (property_name, new_value) if only device is provided, and one parameter (new_value) of both device and property are provided.

Parameters:

Name Type Description Default
device str

A device label

 required
property Optional[str]

Optional property label. If not provided, all property changes on device will trigger an event emission. by default None

 None

Returns:

Type Description
_PropertySignal

Object with connect and disconnect methods that attach a callback to the change event of a specific property or device.

Examples:

>>> core.events.devicePropertyChanged("Camera", "Gain").connect(callback)
>>> core.events.devicePropertyChanged("Camera").connect(callback)

pymmcore_plus.mda.events.PMDASignaler #

Declares the protocol for all signals that will be emitted from pymmcore_plus.mda.MDARunner.

awaitingEvent: PSignal class-attribute #

Emits (event: MDAEvent, remaining_sec: float) when the runner is waiting to start an event.

Note: Not all events in a sequence will emit this signal. This will only be emitted if the wait time is non-zero.

eventStarted: PSignal class-attribute #

Emits (event: MDAEvent) immediately before event setup and execution.

frameReady: PSignal class-attribute #

Emits (img: np.ndarray, event: MDAEvent, metadata: dict) after an image is acquired during an acquisition sequence.

For the default MDAEngine, the metadata dict will be of type FrameMetaV1.

sequenceCanceled: PSignal class-attribute #

Emits (sequence: MDASequence) when an acquisition sequence is canceled.

sequenceFinished: PSignal class-attribute #

Emits (sequence: MDASequence) when an acquisition sequence is finished.

sequencePauseToggled: PSignal class-attribute #

Emits (paused: bool) when an acquisition sequence is paused or unpaused.

sequenceStarted: PSignal class-attribute #

Emits (sequence: MDASequence, metadata: dict) when an acquisition sequence is started.

For the default MDAEngine, the metadata dict will be of type SummaryMetaV1.