Events¶
There are two objects that emit events in pymmcore-plus. The CMMCorePlus
object emits the PCoreSignaler signals at
core.events when the state of the microscope changes, and the MDARunner emits
the PMDASignaler signals at
core.mda.events as an acquisition sequence progresses.
See Events and Callbacks for how to connect callbacks, choosing the Qt or psygnal backend, and which thread your callbacks run on.
Bases: Protocol
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 that 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(on_exposure_changed)
Events may also be connected as a decorator:
- API Reference pymmcore-plus
- User Guide Controlling Hardware Events and Callbacks Connecting callbacks to events
Emits with no arguments when properties have changed.
Emits (name: str, propName: str, propValue: str) when a specific property has changed.
Emits (newChannelGroupName: str) when a channel group has changed.
Emits (groupName: str, newConfigName: str) when a config group has changed.
Emits with no arguments when the system configuration has been loaded.
Emits (newPixelSizeUm: float) when the pixel size has changed.
Emits (float, float, float, float, float, float) when the pixel size affine has changed.
Emits (name: str, pos: float) when a stage position has changed.
Emits (name: str, xpos: float, ypos: float) when an XY stage position has changed.
Emits (name: str, newExposure: float) when an exposure has changed.
Emits (name: str, newExposure: float) when the exposure of the SLM device changes.
Emits (name: str, isOpen: bool) when the shutter open state has changed.
Emits (groupName: str, configName: str) when a config has been set.
This signal is unique to
pymmcore-plus.
- User Guide Controlling Hardware Configuration and Groups Using groups and presets
Emits (cameraLabel: str) whenever snapImage is called.
Emits (newEngine, oldEngine) when an MDAEngine is registered.
pymmcore-plus.
- User Guide Running Acquisitions Custom Acquisition Engines Customizing the MDAEngine
Emits with no arguments before continuous sequence acquisition is started.
pymmcore-plus.
Emits with no arguments after continuous sequence acquisition has started.
pymmcore-plus.
Emits (cameraLabel: str) before sequence acquisition is started.
Breaking Change
In pymmcore-plus version 0.16.0, the sequenceAcquisitionStarting signal
was reduced from (str, int, float, bool) to (str,) to match the signature
emitted by the C++ MMCore library.
pymmcore-plus.
Emits (cameraLabel: str) after sequence acquisition has started.
Breaking Change
In pymmcore-plus version 0.16.0, the sequenceAcquisitionStarted signal
was reduced from (str, int, float, bool) to (str,) to match the signature
emitted by the C++ MMCore library.
Emits (cameraLabel: str) when sequence acquisition is stopped.
Emits (state: bool) when the auto shutter setting is changed.
pymmcore-plus.
Emits (groupName: str) when a config group is deleted.
pymmcore-plus.
Emits (groupName: str, configName: str) when a config is deleted.
pymmcore-plus.
Emits (str, str, str, str, str) when a config is defined.
The arguments are (groupName, configName, deviceLabel, propName, value). The
last three are empty strings when an empty preset is defined.
pymmcore-plus.
Emits (cameraLabel: str, x, y, width, height) when an ROI is set.
pymmcore-plus.
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 |
None
|
Returns:
| Type | Description |
|---|---|
_PropertySignal
|
Object with |
Examples:
>>> core.events.devicePropertyChanged("Camera", "Gain").connect(callback)
>>> core.events.devicePropertyChanged("Camera").connect(callback)
Bases: Protocol
Declares the protocol for all signals that will be emitted from pymmcore_plus.mda.MDARunner.
- API Reference pymmcore-plus
- Getting Started Your First Acquisition Running it
- User Guide Controlling Hardware Events and Callbacks Connecting callbacks to events
Emits (sequence: MDASequence, metadata: dict) when an acquisition sequence is started.
For the default MDAEngine, the metadata dict will
be of type SummaryMetaV1.
Emits (paused: bool) when an acquisition sequence is paused or unpaused.
Emits (sequence: MDASequence) when an acquisition sequence is canceled.
Emits (sequence: MDASequence) when an acquisition sequence is finished.
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.
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.
Emits (event: MDAEvent) immediately before event setup and execution.
- User Guide Running Acquisitions The Acquisition Engine What the engine does