pymmcore_plus.core package

Subpackages

• pymmcore_plus.core.events package
  • Module contents

Module contents

class ActionType(value)

Bases: enum.IntEnum

An enumeration.

AfterLoadSequence = 4

AfterSet = 2

BeforeGet = 1

IsSequenceable = 3

NoAction = 0

StartSequence = 5

StopSequence = 6

class CMMCorePlus(mm_path=None, adapter_paths: Union[List[str], Tuple[str, ...]] = ())

Bases: pymmcore.pymmcore_swig.CMMCore

property channelGroup_pattern

defineConfig(group: str, preset: str) → None

defineConfig(group: str, preset: str, device_label: str, device_property: str, value: str) → None

defineConfig(CMMCore self, char const * groupName, char const * configName)

Parameters

• groupName (char const *)

• configName (char const *)

• defineConfig(CMMCore self, char const * groupName, char const * configName, char const * deviceLabel, char const * propName, char const * value)

Parameters

• groupName (char const *)

• configName (char const *)

• deviceLabel (char const *)

• propName (char const *)

• value (char const *)

definePixelSizeConfig(resolutionID: str) → None

definePixelSizeConfig(resolutionID: str, deviceLabel: str, propName: str, value: str) → None

definePixelSizeConfig(CMMCore self, char const * resolutionID, char const * deviceLabel, char const * propName, char const * value)

Parameters

• resolutionID (char const *)

• deviceLabel (char const *)

• propName (char const *)

• value (char const *)

• definePixelSizeConfig(CMMCore self, char const * resolutionID)

Parameters

resolutionID (char const *)

deleteConfig(CMMCore self, char const * groupName, char const * configName)

Parameters

• groupName (char const *)

• configName (char const *)

• deleteConfig(CMMCore self, char const * groupName, char const * configName, char const * deviceLabel, char const * propName)

Parameters

• groupName (char const *)

• configName (char const *)

• deviceLabel (char const *)

• propName (char const *)

deleteConfigGroup(CMMCore self, char const * groupName)

Parameters

groupName (char const *)

deletePixelSizeConfig(CMMCore self, char const * configName)

Parameters

configName (char const *)

detectDevice(deviceLabel: str) → pymmcore_plus.core._constants.DeviceDetectionStatus

Tries to communicate to a device through a given serial port.

Used to automate discovery of correct serial port. Also configures the serial port correctly.

getCameraChannelNames() → Tuple[str, ...]

getConfigData(configGroup: str, configName: str, *, native=False) → pymmcore_plus.core._config.Configuration

Returns the configuration object for a given group and name.

getConfigData(CMMCore self, char const * configGroup, char const * configName) -> Configuration

Parameters

• configGroup (char const *)

• configName (char const *)

• By default, this method returns a `pymmcore_plus.Configuration` object, which

• provides some conveniences over the native `pymmcore.Configuration` object, however

• this adds a little overhead. Use `native=True` to avoid the conversion.

getConfigGroupState(group: str, *, native=False) → pymmcore_plus.core._config.Configuration

Returns the partial state of the system, for the devices included in the

specified group.

getConfigGroupState(CMMCore self, char const * group) -> Configuration

Parameters

• group (char const *)

• By default, this method returns a `pymmcore_plus.Configuration` object, which

• provides some conveniences over the native `pymmcore.Configuration` object, however

• this adds a little overhead. Use `native=True` to avoid the conversion.

getConfigGroupStateFromCache(group: str, *, native=False) → pymmcore_plus.core._config.Configuration

Returns the partial state of the system cache, for the devices included

in the specified group.

getConfigGroupStateFromCache(CMMCore self, char const * group) -> Configuration

Parameters

• group (char const *)

• By default, this method returns a `pymmcore_plus.Configuration` object, which

• provides some conveniences over the native `pymmcore.Configuration` object, however

• this adds a little overhead. Use `native=True` to avoid the conversion.

getConfigState(group: str, config: str, *, native=False) → pymmcore_plus.core._config.Configuration

Returns a partial state of the system, for devices included in the

specified configuration.

getConfigState(CMMCore self, char const * group, char const * config) -> Configuration

Parameters

• group (char const *)

• config (char const *)

• By default, this method returns a `pymmcore_plus.Configuration` object, which

• provides some conveniences over the native `pymmcore.Configuration` object, however

• this adds a little overhead. Use `native=True` to avoid the conversion.

getDeviceObject(device_label: str) → pymmcore_plus.core._device.Device

Return a Device object bound to device_label on this core.

getDeviceSchema(device_label: str) → Dict[str, Any]

Return dict in JSON-schema format for properties of device_label.

Use json.dump to convert this dict to a JSON string.

getDeviceType(label: str) → pymmcore_plus.core._constants.DeviceType

Returns device type.

getImage(*args, fix=True) → np.ndarray

Exposes the internal image buffer.

The pymmcore-plus implementation will convert images with n_components > 1 to a shape (w, h, num_components) and dtype img.dtype.itemsize//ncomp

getLastImageMD(CMMCore self, unsigned int channel, unsigned int slice, Metadata md) → void *

Parameters

• channel (unsigned int)

• slice (unsigned int)

• md (Metadata &)

• getLastImageMD(CMMCore self, Metadata md)

Parameters

md (Metadata &)

getNBeforeLastImageMD(CMMCore self, unsigned long n, Metadata md) → void *

Parameters

• n (unsigned long)

• md (Metadata &)

getOrGuessChannelGroup() → List[str]

Get the channelGroup or find a likely set of candidates.

If the group is not defined via .getChannelGroup then likely candidates will be found by searching for config groups with names that match this object’s channelGroup_pattern property. This is a settable property with a default value of:

reg = re.compile("(chan{1,2}(el)?|filt(er)?)s?", re.IGNORECASE)

getPixelSizeConfigData(configName: str, *, native=False) → pymmcore_plus.core._config.Configuration

Returns the configuration object for a given pixel size preset.

getPropertyObject(device_label: str, property_name: str) → pymmcore_plus.core._property.DeviceProperty

Return a DeviceProperty object bound to a device/property on this core.

getPropertyType(CMMCore self, char const * label, char const * propName) → MM::PropertyType

Parameters

• label (char const *)

• propName (char const *)

getSystemState(*, native=False) → pymmcore_plus.core._config.Configuration

Returns the entire system state. getSystemState(CMMCore self) -> ConfigurationBy default, this method returns a pymmcore_plus.Configuration object, which provides some conveniences over the native pymmcore.Configuration object, however this adds a little overhead. Use native=True to avoid the conversion.

getSystemStateCache(*, native=False) → pymmcore_plus.core._config.Configuration

Returns the entire system state from cache getSystemStateCache(CMMCore self) -> ConfigurationBy default, this method returns a pymmcore_plus.Configuration object, which provides some conveniences over the native pymmcore.Configuration object, however this adds a little overhead. Use native=True to avoid the conversion.

getZPosition() → float

guessObjectiveDevices() → List[str]

Find any loaded devices that are likely to be an Objective/Nosepiece.

Likely matches are loaded StateDevices with names that match this object’s objective_device_pattern property. This is a settable property with a default value of:

re.compile("(.+)?(nosepiece|obj(ective)?)(turret)?s?", re.IGNORECASE)``

classmethod instance(mm_path=None, adapter_paths: Union[List[str], Tuple[str, ...]] = ()) → pymmcore_plus.core._mmcore_plus.CMMCorePlus

iterDevices(device_type: Optional[pymmcore_plus.core._constants.DeviceType] = None, device_label: Optional[str] = None, as_object: Literal[False] = False) → Iterator[str]

iterDevices(device_type: Optional[pymmcore_plus.core._constants.DeviceType] = None, device_label: Optional[str] = None, as_object: Literal[True] = False) → Iterator[pymmcore_plus.core._device.Device]

Iterate over currently loaded devices.

Parameters

• device_type (Optional[DeviceType]) – DeviceType to filter by, by default all device types will be yielded.

• device_label (Optional[str]) – Device label to filter by, by default all device labels will be yielded.

• as_object (bool, optional) – If True, Device objects will be yielded instead of device label strings. By default False

Yields

Iterator[Union[Device, str]] – Device objects (if as_object==True) or device label strings.

iterProperties(device_type: Optional[pymmcore_plus.core._constants.DeviceType] = None, device_label: Optional[str] = None, property_type: Optional[pymmcore_plus.core._constants.PropertyType] = None, as_object: Literal[False] = False) → Iterator[Tuple[str, str]]

iterProperties(device_type: Optional[pymmcore_plus.core._constants.DeviceType] = None, device_label: Optional[str] = None, property_type: Optional[pymmcore_plus.core._constants.PropertyType] = None, as_object: Literal[True] = False) → Iterator[pymmcore_plus.core._property.DeviceProperty]

Iterate over currently loaded (device_label, property_name) pairs.

Parameters

• device_type (Optional[DeviceType]) – DeviceType to filter by, by default all device types will be yielded.

• device_label (Optional[str]) – Device label to filter by, by default all device labels will be yielded.

• property_type (Optional[PropertyType]) – PropertyType to filter by, by default all property types will be yielded.

• as_object (bool, optional) – If True, DeviceProperty objects will be yielded instead of (device_label, property_name) tuples. By default False

Yields

Iterator[Union[DeviceProperty, Tuple[str, str]]] – DeviceProperty objects (if as_object==True) or 2-tuples of (device_name, property_name)

loadSystemConfiguration(fileName: str | Path = 'MMConfig_demo.cfg') → None

Load a config file.

For relative paths first checks relative to the current working directory, then in the device adapter path.

lock = <unlocked _thread.RLock object owner=0 count=0>

property mda

property objective_device_pattern

popNextImage() → np.ndarray

Gets and removes the next image from the circular buffer.

The pymmcore-plus implementation will convert images with n_components > 1 to a shape (w, h, num_components) and dtype img.dtype.itemsize//ncomp

popNextImageMD(CMMCore self, unsigned int channel, unsigned int slice, Metadata md) → void *

Parameters

• channel (unsigned int)

• slice (unsigned int)

• md (Metadata &)

• popNextImageMD(CMMCore self, Metadata md)

Parameters

md (Metadata &)

register_mda_engine(engine)

Set the MDA Engine to be used on run_mda. This will unregister the previous engine and emit an mdaEngineRegistered signal. The current Engine must not be running an MDA in order to register a new engine.

Parameters

engine (PMDAEngine) – Any object conforming to the PMDAEngine protocol.

run_mda(sequence: MDASequence) → Thread

Run MDA defined by sequence on a new thread. The currently registered MDAEngine (core.mda) will be responsible for executing the acquisition.

After starting the sequence you can pause or cancel with the mda with the mda object’s toggle_pause and cancel methods.

Parameters

sequence (useq.MDASequence)

Returns

Thread – The thread the MDA is running on.

setAutoShutter(CMMCore self, bool state)

Parameters

state (bool)

setConfig(groupName: str, configName: str) → None

Applies a configuration to a group.

setContext(**kwargs)

Set core properties in a context restoring the initial values on exit.

setDeviceAdapterSearchPaths(CMMCore self, StrVector paths)

Parameters

paths (std::vector< std::string,std::allocator< std::string > > const &)

setPixelSizeUm(CMMCore self, char const * resolutionID, double pixSize)

Parameters

• resolutionID (char const *)

• pixSize (double)

setPosition(stageLabel: str, position: float)

setPosition(position: float)

Set position of the stage in microns.

setProperty(label: str, propName: str, propValue: Union[bool, float, int, str]) → None

setProperty with reliable event emission.

setROI(x: int, y: int, width: int, height: int) → None

setROI(label: str, x: int, y: int, width: int, height: int) → None

setROI(CMMCore self, int x, int y, int xSize, int ySize)

Parameters

• x (int)

• y (int)

• xSize (int)

• ySize (int)

• setROI(CMMCore self, char const * label, int x, int y, int xSize, int ySize)

Parameters

• label (char const *)

• x (int)

• y (int)

• xSize (int)

• ySize (int)

setRelativeXYZPosition(dx: float = 0, dy: float = 0, dz: float = 0) → None

Sets the relative XYZ position in microns.

setShutterOpen(state: bool) → None

setShutterOpen(shutterLabel: str, state: bool) → None

setShutterOpen(CMMCore self, bool state)

Parameters

• state (bool)

• setShutterOpen(CMMCore self, char const * shutterLabel, bool state)

Parameters

• shutterLabel (char const *)

• state (bool)

setState(stateDeviceLabel: str, state: int) → None

Set state (by position) on stateDeviceLabel, with reliable event emission.

setStateLabel(stateDeviceLabel: str, stateLabel: str) → None

Set state (by label) on stateDeviceLabel, with reliable event emission.

setXYPosition(CMMCore self, char const * xyStageLabel, double x, double y)

Parameters

• xyStageLabel (char const *)

• x (double)

• y (double)

• setXYPosition(CMMCore self, double x, double y)

Parameters

• x (double)

• y (double)

setZPosition(val: float) → None

snap(*args, fix=True) → np.ndarray

snap and return an image.

In contrast to snapImage this will directly return the image without also calling getImage.

Parameters

• *args – Passed through to getImage

• fix (bool, default: True) – Whether to fix the shape of images with n_components >1 Pass on to getImage

Returns

img (np.ndarray)

snapImage(CMMCore self)

startContinuousSequenceAcquisition(intervalMs: float = 0) → None

Start a ContinuousSequenceAcquisition.

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

startSequenceAcquisition(cameraLabel: str, numImages: int, intervalMs: float, stopOnOverflow: bool) → None

startSequenceAcquisition(CMMCore self, long numImages, double intervalMs, bool stopOnOverflow)

Parameters

• numImages (long)

• intervalMs (double)

• stopOnOverflow (bool)

• startSequenceAcquisition(CMMCore self, char const * cameraLabel, long numImages, double intervalMs, bool stopOnOverflow)

Parameters

• cameraLabel (char const *)

• numImages (long)

• intervalMs (double)

• stopOnOverflow (bool)

state(exclude=()) → dict

A dict with commonly accessed state values. Faster than getSystemState.

stopSequenceAcquisition(cameraLabel: Optional[str] = None) → None

Stop a SequenceAcquisition.

unloadAllDevices(CMMCore self)

class Configuration

Bases: pymmcore.pymmcore_swig.Configuration

Encapsulation of the configuration information, with convenience methods.

This pymmcore_plus variant provides additional conveniences:

__len__ - number of settings __str__ - pretty printing of Config __contains__ - check if (devLabel, propLabel) is in the config __getitem__ - get property setting by index or (devLabel, propLabel) key __iter__ - iterate over (devLabeL, propLabel, value) tuples dict() - convert Configuration to nested dict json() - convert to JSON string yaml() - convert to YAML string (requires PyYAML) html() - convert to HTML string

classmethod create(*args, **kwargs)

More flexible init to create a Configuration from:

1. A dict of dicts (outer key is device, inner key is prop)

2. A sequence of 3-tuple

3. kwargs: where the key is the device, and the value is a {prop: value} map

dict() → Dict[str, Dict[str, str]]

Return config as a nested dict

classmethod from_configuration(config: pymmcore.pymmcore_swig.Configuration)

Create Configuration (Plus) from pymmcore.Configuration

html() → str

Return config as HTML.

json() → str

Dump config to JSON string.

yaml() → str

Dump config to YAML string (requires PyYAML).

class Device(device_label: str, mmcore: CMMCorePlus)

Bases: object

Convenience view onto a device.

Parameters

• device_label (str) – Device this property belongs to

• mmcore (CMMCorePlus) – CMMCorePlus instance

Examples

>>> core = CMMCorePlus()
>>> device = Device('Camera', core)
>>> device.isLoaded()
>>> device.load('NotALib', 'DCam')  # useful error
>>> device.load('DemoCamera', 'DCam')
>>> device.initialize()
>>> device.load('DemoCamera', 'DCam')  # no-op w/ useful warning
>>> device.properties  # tuple of DeviceProperty objects
>>> device.description()
>>> device.isBusy()
>>> device.wait()
>>> device.type()
>>> device.schema()  # JSON schema of device properties

property core: CMMCorePlus

Return the core instance to which this Device is bound.

delayMs() → float

Return action delay in ms for this device

description() → str

Return device description.

detect() → DeviceDetectionStatus

Tries to communicate to device through a given serial port.

Used to automate discovery of correct serial port. Also configures the serial port correctly.

initialize() → None

Initialize device.

isBusy() → bool

Return busy status for this device.

isLoaded() → bool

Return True if device is loaded.

library() → str

Return device library (aka module, device adapter) name.

load(adapter_name: str, device_name: str) → None

Load device from the plugin library.

Parameters

• adapter_name (str) – The name of the device adapter module (short name, not full file name). (This is what is returned by Device.library())

• device_name (str) – The name of the device. The name must correspond to one of the names recognized by the specific plugin library. (This is what is returned by Device.name())

name() → str

Returns device name (this is not the same as the device label).

property properties: Tuple[pymmcore_plus.core._property.DeviceProperty, ...]

Get all properties supported by device as DeviceProperty objects.

propertyNames() → Tuple[str, ...]

Return all property names supported by this device.

schema() → dict

Return dict in JSON-schema format for properties of device_label.

setDelayMs(delayMs: float)

Override the built-in value for the action delay.

supportsDetection() → bool

Return whether or not the device supports automatic device detection.

(i.e. whether or not detectDevice() may be safely called).

type() → DeviceType

Return device type.

unload()

Unload device from the core and adjust all configuration data.

usesDelay() → bool

Return True if the device will use the delay setting or not.

wait() → None

Block the calling thread until device becomes non-busy.

class DeviceDetectionStatus(value)

Bases: enum.IntEnum

DeviceDetectionStatus from device discovery

Unimplemented

there is as yet no mechanism to programmatically detect the device

Misconfigured

some information needed to communicate with the device is invalid

CanNotCommunicate

communication attributes are valid, but the device does not respond

CanCommunicate

communication verified, parameters have been set to valid values.

CanCommunicate = 1

CanNotCommunicate = 0

Misconfigured = -1

Unimplemented = -2

class DeviceNotification(value)

Bases: enum.IntEnum

An enumeration.

Attention = 0

Done = 1

StatusChanged = 2

class DeviceProperty(device_label: str, property_name: str, mmcore: CMMCorePlus)

Bases: object

Convenience “View” onto a device property.

Parameters

• device_label (str) – Device this property belongs to

• property_name (str) – Name of this property

• mmcore (CMMCorePlus) – CMMCorePlus instance

Examples

>>> core = CMMCorePlus()
>>> prop = DeviceProperty('Objective', 'Label', core)
>>> prop.isValid()  # points to a loaded device property in core
>>> prop.value
>>> prop.value = 'Objective-2'  # setter
>>> prop.isReadOnly()
>>> prop.hasLimits()
>>> prop.range()
>>> prop.dict()  # all the info in one dict.

class InfoDict(_typename, _fields=None, /, **kwargs)

Bases: dict

allowed_values: Optional[Tuple[str, ...]]

device_type: Optional[str]

pre_init: Optional[bool]

range: Optional[Tuple[float, float]]

read_only: Optional[bool]

sequence_max_length: Optional[int]

sequenceable: Optional[bool]

type: Optional[str]

valid: bool

value: Optional[Any]

allowedValues() → Tuple[str, ...]

Return allowed values for this property, if contstrained.

property core: CMMCorePlus

Return the core instance to which this Property is bound.

deviceType() → pymmcore_plus.core._constants.DeviceType

Return DeviceType of the device owning this property.

dict() → pymmcore_plus.core._property.InfoDict

Return dict of info about this Property.

Contains the following keys (See InfoDict type): “valid”, “value”, “type”, “device_type”, “read_only”, “pre_init”, “range”, “allowed”.

fromCache() → Any

Return cached property value.

hasLimits() → bool

Return True if property has limits

isLoaded() → bool

Return true if the device name is loaded

isPreInit() → bool

Return True if property must be defined prior to initialization.

isReadOnly() → bool

Return True if property is read only.

isSequenceable() → bool

Return True if property can be used in a sequence.

isValid() → bool

Return True if device is loaded and has a property by this name.

loadSequence(eventSequence: Sequence[str]) → None

Transfer a sequence of events/states/whatever to the device.

Parameters

eventSequence (Sequence[str]) – The sequence of events/states that the device will execute in response to external triggers

lowerLimit() → float

Return lower limit if property has limits, or 0 otherwise.

range() → Tuple[float, float]

Return (lowerLimit, upperLimit) range tuple.

sequenceMaxLength() → int

Return maximum number of property events that can be put in a sequence

setValue(val: Any) → None

Functional alternate to property setter.

startSequence() → None

Start an ongoing sequence of triggered events in a property.

stopSequence() → None

Stop an ongoing sequence of triggered events in a property.

type() → pymmcore_plus.core._constants.PropertyType

Return PropertyType of this property.

upperLimit() → float

Return upper limit if property has limits, or 0 otherwise.

property value: Any

Return current property value, cast to appropriate type if applicable.

class DeviceType(value)

Bases: enum.IntEnum

An enumeration.

Any = 1

AnyType = 1

AutoFocus = 9

AutoFocusDevice = 9

Camera = 2

CameraDevice = 2

Core = 10

CoreDevice = 10

Galvo = 16

GalvoDevice = 16

Generic = 8

GenericDevice = 8

Hub = 15

HubDevice = 15

ImageProcessor = 11

ImageProcessorDevice = 11

Magnifier = 13

MagnifierDevice = 13

SLM = 14

SLMDevice = 14

Serial = 7

SerialDevice = 7

Shutter = 3

ShutterDevice = 3

SignalIO = 12

SignalIODevice = 12

Stage = 5

StageDevice = 5

State = 4

StateDevice = 4

Unknown = 0

UnknownType = 0

XYStage = 6

XYStageDevice = 6

class FocusDirection(value)

Bases: enum.IntEnum

An enumeration.

AwayFromSample = 2

FocusDirectionAwayFromSample = 2

FocusDirectionTowardSample = 1

FocusDirectionUnknown = 0

TowardSample = 1

Unknown = 0

class Metadata(*args, **kwargs)

Bases: pymmcore.pymmcore_swig.Metadata

clear() → None

copy()

get(name, default=<object object>)

items() → ItemsView[str, str]

json() → str

keys() → KeysView[str]

values() → ValuesView[str]

class PortType(value)

Bases: enum.IntEnum

An enumeration.

HIDPort = 3

InvalidPort = 0

SerialPort = 1

USBPort = 2

class PropertyType(value)

Bases: enum.IntEnum

An enumeration.

Float = 2

Integer = 3

String = 1

Undef = 0

to_json()

to_python()