Skip to content
pymmcore-plus PyPI version

pymmcore_plus.core

CMMCorePlus and its supporting classes.

This includes the object-oriented views onto devices, properties and config groups, the enums that replace pymmcore's integer constants, and hardware sequencing helpers.

Submodules

Name Description
events Signals emitted by CMMCorePlus.events.

Classes

Name Description
AutoFocusDevice
CameraDevice
CoreDevice
GalvoDevice
GenericDevice
HubDevice
ImageProcessorDevice
MagnifierDevice
SLMDevice
SequencedEvent Subclass of MDAEvent that represents a sequence of triggered events.
SerialDevice
ShutterDevice
SignalIODevice
StageDevice
StateDevice
XYStageDevice

Functions

Name Description
iter_sequenced_events Iterate over a sequence of MDAEvents, yielding SequencedEvents when possible.

Classes

AutoFocusDevice 

AutoFocusDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[AutoFocus]

CameraDevice 

CameraDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

exposure property writable 

exposure: float

isSequenceable 

isSequenceable = isExposureSequenceable

loadSequence 

loadSequence = loadExposureSequence

startSequence 

startSequence = startExposureSequence

stopSequence 

stopSequence = stopExposureSequence

getSequenceMaxLength 

getSequenceMaxLength = getExposureSequenceMaxLength

type 

type() -> Literal[Camera]

setROI 

setROI(x: int, y: int, width: int, height: int) -> None

Set region of interest for camera.

getROI 

getROI() -> list[int]

Return region of interest for camera.

setExposure 

setExposure(exposure: float) -> None

Set exposure time for camera.

getExposure 

getExposure() -> float

Return exposure time for camera.

startSequenceAcquisition 

startSequenceAcquisition(
    numImages: int, intervalMs: float, stopOnOverflow: bool
) -> None

Start sequence acquisition.

prepareSequenceAcquisition 

prepareSequenceAcquisition() -> None

Prepare sequence acquisition.

stopSequenceAcquisition 

stopSequenceAcquisition() -> None

Stop sequence acquisition.

isSequenceRunning 

isSequenceRunning() -> bool

Return True if sequence acquisition is running.

isExposureSequenceable 

isExposureSequenceable() -> bool

Return True if camera supports exposure sequence.

Used by:

loadExposureSequence 

loadExposureSequence(sequence: Sequence[float]) -> None

Load exposure sequence.

Used by:

startExposureSequence 

startExposureSequence() -> None

Start exposure sequence.

Used by:

stopExposureSequence 

stopExposureSequence() -> None

Stop exposure sequence.

Used by:

getExposureSequenceMaxLength 

getExposureSequenceMaxLength() -> int

Return the maximum length of a camera's exposure sequence.

Used by:

CoreDevice 

CoreDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[Core]

GalvoDevice 

GalvoDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

position property writable 

position: list[float]

type 

type() -> Literal[Galvo]

pointAndFire 

pointAndFire(x: float, y: float, pulseTime_us: float) -> None

Set Galvo to (x, y) and fire the laser for a predetermined duration.

setSpotInterval 

setSpotInterval(pulseTime_us: float) -> None

Set the SpotInterval for the specified galvo device.

setPosition 

setPosition(x: float, y: float) -> None

Set the position of the galvo device.

getPosition 

getPosition() -> list[float]

Return the position of the galvo device.

setIlluminationState 

setIlluminationState(state: bool) -> None

Set the galvo's illumination state to on or off.

getXRange 

getXRange() -> float

Get the Galvo x range.

getXMinimum 

getXMinimum() -> float

Get the Galvo x minimum.

getYRange 

getYRange() -> float

Get the Galvo y range.

getYMinimum 

getYMinimum() -> float

Get the Galvo y minimum.

addPolygonVertex 

addPolygonVertex(polygonIndex: int, x: float, y: float) -> None

Add a vertex to the polygon.

deletePolygons 

deletePolygons() -> None

Delete all polygons.

loadPolygons 

loadPolygons() -> None

Load a set of galvo polygons to the device.

runPolygons 

runPolygons() -> None

Run a loop of galvo polygons.

runSequence 

runSequence() -> None

Run a sequence of galvo positions.

setPolygonRepetitions 

setPolygonRepetitions(repetitions: int) -> None

Set the number of times the galvo polygon should be repeated.

getChannel 

getChannel() -> str

Get the name of the active galvo channel (for a multi-laser galvo device).

GenericDevice 

GenericDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[Generic]

HubDevice 

HubDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[Hub]

getInstalledDevices 

getInstalledDevices() -> tuple[str, ...]

Return the list of installed devices.

getInstalledDeviceDescription 

getInstalledDeviceDescription(device_label: str) -> str

Return the description of the installed device.

getLoadedPeripheralDevices 

getLoadedPeripheralDevices() -> tuple[str, ...]

Return the list of loaded peripheral devices.

ImageProcessorDevice 

ImageProcessorDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[ImageProcessor]

MagnifierDevice 

MagnifierDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[Magnifier]

SerialDevice 

SerialDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

answer_timeout property 

answer_timeout: str

Return the timeout for serial port commands.

baud_rate property 

baud_rate: str

Return the baud rate for serial port commands.

data_bits property 

data_bits: str

Return the data bits for serial port commands.

parity property 

parity: str

Return the parity for serial port commands.

stop_bits property 

stop_bits: str

Return the stop bits for serial port commands.

handshaking property 

handshaking: str

Return the handshaking for serial port commands.

delay_between_chars_ms property 

delay_between_chars_ms: str

Return the delay between characters in milliseconds.

type 

type() -> Literal[Serial]

setCommand 

setCommand(command: str, term: str) -> None

Send string to the serial device and return an answer.

getAnswer 

getAnswer(term: str) -> str

Continuously read from the serial port until the term is encountered.

write 

write(data: bytes) -> None

Send string to the serial device.

read 

read() -> list[str]

Reads the contents of the Rx buffer.

setProperties 

setProperties(
    answerTimeout: str,
    baudRate: str,
    delayBetweenCharsMs: str,
    handshaking: str,
    parity: str,
    stopBits: str,
) -> None

Sets all com port properties in a single call.

ShutterDevice 

ShutterDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[Shutter]

open 

open() -> None

Open shutter.

close 

close() -> None

Close shutter.

isOpen 

isOpen() -> bool

Return True if shutter is open.

SignalIODevice 

SignalIODevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

type 

type() -> Literal[SignalIO]

SLMDevice 

SLMDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

exposure property writable 

exposure: float

type 

type() -> Literal[SLM]

setImage 

setImage(pixels: Any) -> None

Write an image to the SLM .

setPixelsTo 

setPixelsTo(intensity: int) -> None

setPixelsTo(red: int, green: int, blue: int) -> None

setPixelsTo(*args: int) -> None

Set all SLM pixels to a single 8-bit intensity or RGB color.

displayImage 

displayImage() -> None

Display the image on the SLM.

setExposure 

setExposure(exposure_ms: float) -> None

Set exposure time for SLM.

getExposure 

getExposure() -> float

Return exposure time for SLM.

width 

width() -> int

Return the width of the SLM image.

height 

height() -> int

Return the height of the SLM image.

numberOfComponents 

numberOfComponents() -> int

Return the number of components in the SLM image.

bytesPerPixel 

bytesPerPixel() -> int

Return the number of bytes per pixel in the SLM image.

getSequenceMaxLength 

getSequenceMaxLength() -> int

Return the maximum length of a sequence for the SLM.

isSequenceable 

isSequenceable() -> bool

Return True if the SLM supports sequences.

loadSequence 

loadSequence(imageSequence: list[bytes]) -> None

Load a sequence of images to the SLM.

startSequence 

startSequence() -> None

Start the sequence of images on the SLM.

stopSequence 

stopSequence() -> None

Stop the sequence of images on the SLM.

StageDevice 

StageDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)
Returned by:

position property writable 

position: float

isSequenceable 

isSequenceable = isStageSequenceable

loadSequence 

loadSequence = loadStageSequence

startSequence 

startSequence = startStageSequence

stopSequence 

stopSequence = stopStageSequence

getSequenceMaxLength 

getSequenceMaxLength = getStageSequenceMaxLength

type 

type() -> Literal[Stage]

setPosition 

setPosition(position: float) -> None

getPosition 

getPosition() -> float

setRelativePosition 

setRelativePosition(offset: float) -> None

getPositionAccumulator 

getPositionAccumulator() -> PositionChangeAccumulator

setOrigin 

setOrigin() -> None

setAdapterOrigin 

setAdapterOrigin(newZUm: float) -> None

setFocusDirection 

setFocusDirection(sign: int) -> None

getFocusDirection 

getFocusDirection() -> FocusDirection

isContinuousFocusDrive 

isContinuousFocusDrive() -> bool

Return True if device supports continuous focus.

isStageSequenceable 

isStageSequenceable() -> bool

Return True if device supports stage sequence.

Used by:

isStageLinearSequenceable 

isStageLinearSequenceable() -> bool

Return True if device supports linear stage sequence.

startStageSequence 

startStageSequence() -> None

Start stage sequence.

Used by:

stopStageSequence 

stopStageSequence() -> None

Stop stage sequence.

Used by:

getStageSequenceMaxLength 

getStageSequenceMaxLength() -> int

Return maximum length of stage sequence.

Used by:

loadStageSequence 

loadStageSequence(positions: Sequence[float]) -> None

Load stage sequence.

Used by:

setStageLinearSequence 

setStageLinearSequence(dZ_um: float, nSlices: int) -> None

Set stage linear sequence.

StateDevice 

StateDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)

Bases: Device

Returned by:

state property writable 

state: int

type 

type() -> Literal[State]

setState 

setState(state: int) -> None

Set state.

getState 

getState() -> int

Return state.

getNumberOfStates 

getNumberOfStates() -> int

Return number of states.

setStateLabel 

setStateLabel(label: str) -> None

Set state by label.

getStateLabel 

getStateLabel() -> StateLabel

Return state label.

defineStateLabel 

defineStateLabel(state: int, label: str) -> None

Define state labels.

getStateLabels 

getStateLabels() -> tuple[StateLabel, ...]

Return state labels.

getStateFromLabel 

getStateFromLabel(label: str) -> int

Return state for given label.

XYStageDevice 

XYStageDevice(
    device_label: str = UNASSIGNED,
    mmcore: CMMCorePlus | None = None,
    adapter_name: str = "",
    device_name: str = "",
    type: DeviceType = UnknownType,
    description: str = "",
)
Returned by:

position property writable 

position: tuple[float, float]

Return the position of the XY stage in microns.

setOrigin 

setOrigin = setOriginXY

isSequenceable 

isSequenceable = isXYStageSequenceable

startSequence 

startSequence = startXYStageSequence

stopSequence 

stopSequence = stopXYStageSequence

getSequenceMaxLength 

getSequenceMaxLength = getXYStageSequenceMaxLength

type 

type() -> Literal[XYStage]

setXYPosition 

setXYPosition(x: float, y: float) -> None

Set the position of the XY stage in microns.

getXYPosition 

getXYPosition() -> Sequence[float]

Return the position of the XY stage in microns.

setRelativeXYPosition 

setRelativeXYPosition(dx: float, dy: float) -> None

Set the relative position of the XY stage in microns.

getPositionAccumulator 

getPositionAccumulator() -> XYPositionChangeAccumulator

getXPosition 

getXPosition() -> float

Return the X position of the XY stage in microns.

getYPosition 

getYPosition() -> float

Return the Y position of the XY stage in microns.

setOriginXY 

setOriginXY() -> None

Zero the current XY stage's coordinates at the current position.

Used by:

setOriginX 

setOriginX() -> None

Zero the given XY stage's X coordinate at the current position.

setOriginY 

setOriginY() -> None

Zero the given XY stage's Y coordinate at the current position.

setAdapterOriginXY 

setAdapterOriginXY(newXUm: float, newYUm: float) -> None

Enable software translation of coordinates for the current XY stage.

The current position of the stage becomes (newXUm, newYUm). It is recommended that setOriginXY() be used instead where available.

isXYStageSequenceable 

isXYStageSequenceable() -> bool

Return True if device supports XY stage sequence.

Used by:

startXYStageSequence 

startXYStageSequence() -> None

Start XY stage sequence.

Used by:

stopXYStageSequence 

stopXYStageSequence() -> None

Stop XY stage sequence.

Used by:

getXYStageSequenceMaxLength 

getXYStageSequenceMaxLength() -> int

Return maximum length of XY stage sequence.

Used by:

loadXYStageSequence 

loadXYStageSequence(
    xSequence: Sequence[float], ySequence: Sequence[float]
) -> None

Load XY stage sequence.

loadSequence 

loadSequence(sequence: Sequence[tuple[float, float]]) -> None

Load XY stage sequence with a sequence of 2-tuples.

Provided as a wrapper for loadXYStageSequence, for API parity with other sequencaable devices.

SequencedEvent

Bases: MDAEvent

Subclass of MDAEvent that represents a sequence of triggered events.

Attributes:

Name Type Description
index ReadOnlyDict

A read-only dictionary.
channel Channel | None
exposure float | None
min_start_time float | None
pos_name str | None
x_pos float | None
y_pos float | None
z_pos float | None
slm_image SLMImage | None
sequence MDASequence | None
properties list[PropertyTuple] | None
roi CameraROI | None
metadata dict[str, Any]
action HardwareAutofocus | AcquireImage | CustomAction

useq.Action to acquire an image.

Attributes

type : Literal["acquire_image"] This action can be used to acquire an image.
keep_shutter_open bool
reset_event_timer bool
events tuple[MDAEvent, ...]
exposure_sequence tuple[float, ...]
x_sequence tuple[float, ...]
y_sequence tuple[float, ...]
z_sequence tuple[float, ...]
slm_sequence tuple[bytes, ...]
property_sequences dict[tuple[str, str], list[str]]
Referenced by: Returned by: Used by:

events 

events: tuple[MDAEvent, ...] = Field(repr=False)

exposure_sequence 

exposure_sequence: tuple[float, ...] = Field(default_factory=tuple)

x_sequence 

x_sequence: tuple[float, ...] = Field(default_factory=tuple)

y_sequence 

y_sequence: tuple[float, ...] = Field(default_factory=tuple)

z_sequence 

z_sequence: tuple[float, ...] = Field(default_factory=tuple)

slm_sequence 

slm_sequence: tuple[bytes, ...] = Field(default_factory=tuple)

sequence 

sequence: MDASequence | None = Field(default=None, repr=False)

property_sequences 

property_sequences: dict[tuple[str, str], list[str]] = Field(
    default_factory=dict
)

Functions

iter_sequenced_events 

iter_sequenced_events(
    core: CMMCorePlus, events: Iterable[MDAEvent]
) -> Iterator[MDAEvent | SequencedEvent]

Iterate over a sequence of MDAEvents, yielding SequencedEvents when possible.

Parameters:

Name Type Description Default
core CMMCorePlus

The core object to use for determining sequenceable properties.

 required
events Iterable[MDAEvent]

The events to iterate over.

 required

Returns:

Type Description
Iterator[MDAEvent | SequencedEvent]

A new iterator that will combine multiple MDAEvents into a single SequencedEvent when possible, based on the sequenceable properties of the core object. Note that SequencedEvent itself is a subclass of MDAEvent, but it's up to the engine to check isinstance(event, SequencedEvent) in order to handle SequencedEvents differently.
Referenced by:

Re-exports

These can also be imported from this module, but each is documented under its shortest import path (linked below).

Name Description
ActionType Action that triggered a device property handler.
CFGCommand Commands used in Micro-Manager configuration (.cfg) files.
CFGGroup Names of built-in config groups and presets (System, Startup, etc...).
CMMCorePlus Wrapper for CMMCore with extended functionality.
ConfigGroup Convenience object for dealing with a set of related Configuration objects.
Configuration Encapsulation of configuration information.
Device Convenience object-oriented device API.
DeviceAdapter Convenience view onto a device-adapter library.
DeviceDetectionStatus DeviceDetectionStatus from device discovery.
DeviceInitializationState DeviceInitializationState returned by getDeviceInitializationState.
DeviceProperty Convenience view onto a device property.
DeviceType Type of a Micro-Manager device.
FocusDirection Direction a focus stage moves (towards or away from the sample).
Keyword Standard property and device names (the g_Keyword_* constants).
Metadata Subclass of pymmcore.Metadata with a pythonic interface.
PixelFormat Subset of GeniCam Pixel Format names used by pymmcore-plus.
PortType Type of a port device (serial, USB, HID).
PropertyType Type of a device property value.