pymmcore_plus.core package#

Subpackages#

Module contents#

class ActionType(value)[source]#

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, ...]] = ())[source]#

Bases: pymmcore.pymmcore_swig.CMMCore

property channelGroup_pattern#
detectDevice(deviceLabel: str) pymmcore_plus.core._constants.DeviceDetectionStatus[source]#

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, ...][source]#
getConfigData(configGroup: str, configName: str, *, native=False) pymmcore_plus.core._config.Configuration[source]#

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[source]#
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[source]#
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[source]#
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[source]#

Return a Device object bound to device_label on this core.

getDeviceSchema(device_label: str) Dict[str, Any][source]#

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[source]#

Returns device type.

getImage(*args, fix=True) np.ndarray[source]#

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 *[source]#
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 *[source]#
Parameters
  • n (unsigned long)

  • md (Metadata &)

getOrGuessChannelGroup() List[str][source]#

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[source]#

Returns the configuration object for a given pixel size preset.

getPropertyObject(device_label: str, property_name: str) pymmcore_plus.core._property.DeviceProperty[source]#

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

getPropertyType(CMMCore self, char const * label, char const * propName) MM::PropertyType[source]#
Parameters
  • label (char const *)

  • propName (char const *)

getSystemState(*, native=False) pymmcore_plus.core._config.Configuration[source]#

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[source]#

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[source]#
guessObjectiveDevices() List[str][source]#

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[source]#
iterDevices(device_type: Optional[pymmcore_plus.core._constants.DeviceType] = None, device_label: Optional[str] = None, as_object: Literal[False] = False) Iterator[str][source]#
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]][source]#
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[source]#

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[source]#

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 *[source]#
Parameters
  • channel (unsigned int)

  • slice (unsigned int)

  • md (Metadata &)

  • popNextImageMD(CMMCore self, Metadata md)

Parameters

md (Metadata &)

register_mda_engine(engine)[source]#

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[source]#

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)[source]#
Parameters

state (bool)

setConfig(groupName: str, configName: str) None[source]#

Applies a configuration to a group.

setContext(**kwargs)[source]#

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

setDeviceAdapterSearchPaths(CMMCore self, StrVector paths)[source]#
Parameters

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

setPosition(stageLabel: str, position: float)[source]#
setPosition(position: float)

Set position of the stage in microns.

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

setProperty with reliable event emission.

setROI(x: int, y: int, width: int, height: int) None[source]#
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[source]#

Sets the relative XYZ position in microns.

setShutterOpen(state: bool) None[source]#
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[source]#

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

setStateLabel(stateDeviceLabel: str, stateLabel: str) None[source]#

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

setXYPosition(CMMCore self, char const * xyStageLabel, double x, double y)[source]#
Parameters
  • xyStageLabel (char const *)

  • x (double)

  • y (double)

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

Parameters
  • x (double)

  • y (double)

setZPosition(val: float) None[source]#
snap(*args, fix=True) np.ndarray[source]#

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)[source]#
startContinuousSequenceAcquisition(intervalMs: float = 0) None[source]#

Start a ContinuousSequenceAcquisition.

startSequenceAcquisition(numImages: int, intervalMs: float, stopOnOverflow: bool) None[source]#
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[source]#

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

stopSequenceAcquisition(cameraLabel: Optional[str] = None) None[source]#

Stop a SequenceAcquisition.

unloadAllDevices(CMMCore self)[source]#
class Configuration[source]#

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)[source]#

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]][source]#

Return config as a nested dict

classmethod from_configuration(config: pymmcore.pymmcore_swig.Configuration)[source]#

Create Configuration (Plus) from pymmcore.Configuration

html() str[source]#

Return config as HTML.

json() str[source]#

Dump config to JSON string.

yaml() str[source]#

Dump config to YAML string (requires PyYAML).

class Device(device_label: str, mmcore: CMMCorePlus)[source]#

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[source]#

Return action delay in ms for this device

description() str[source]#

Return device description.

detect() DeviceDetectionStatus[source]#

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[source]#

Initialize device.

isBusy() bool[source]#

Return busy status for this device.

isLoaded() bool[source]#

Return True if device is loaded.

library() str[source]#

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

load(adapter_name: str, device_name: str) None[source]#

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[source]#

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, ...][source]#

Return all property names supported by this device.

schema() dict[source]#

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

setDelayMs(delayMs: float)[source]#

Override the built-in value for the action delay.

supportsDetection() bool[source]#

Return whether or not the device supports automatic device detection.

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

type() DeviceType[source]#

Return device type.

unload()[source]#

Unload device from the core and adjust all configuration data.

usesDelay() bool[source]#

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

wait() None[source]#

Block the calling thread until device becomes non-busy.

class DeviceDetectionStatus(value)[source]#

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)[source]#

Bases: enum.IntEnum

An enumeration.

Attention = 0#
Done = 1#
StatusChanged = 2#
class DeviceProperty(device_label: str, property_name: str, mmcore: CMMCorePlus)[source]#

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)[source]#

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, ...][source]#

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[source]#

Return DeviceType of the device owning this property.

dict() pymmcore_plus.core._property.InfoDict[source]#

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[source]#

Return cached property value.

hasLimits() bool[source]#

Return True if property has limits

isLoaded() bool[source]#

Return true if the device name is loaded

isPreInit() bool[source]#

Return True if property must be defined prior to initialization.

isReadOnly() bool[source]#

Return True if property is read only.

isSequenceable() bool[source]#

Return True if property can be used in a sequence.

isValid() bool[source]#

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

loadSequence(eventSequence: Sequence[str]) None[source]#

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[source]#

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

range() Tuple[float, float][source]#

Return (lowerLimit, upperLimit) range tuple.

sequenceMaxLength() int[source]#

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

setValue(val: Any) None[source]#

Functional alternate to property setter.

startSequence() None[source]#

Start an ongoing sequence of triggered events in a property.

stopSequence() None[source]#

Stop an ongoing sequence of triggered events in a property.

type() pymmcore_plus.core._constants.PropertyType[source]#

Return PropertyType of this property.

upperLimit() float[source]#

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)[source]#

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)[source]#

Bases: enum.IntEnum

An enumeration.

AwayFromSample = 2#
FocusDirectionAwayFromSample = 2#
FocusDirectionTowardSample = 1#
FocusDirectionUnknown = 0#
TowardSample = 1#
Unknown = 0#
class Metadata(*args, **kwargs)[source]#

Bases: pymmcore.pymmcore_swig.Metadata

clear() None[source]#
copy()[source]#
get(name, default=<object object>)[source]#
items() ItemsView[str, str][source]#
json() str[source]#
keys() KeysView[str][source]#
values() ValuesView[str][source]#
class PortType(value)[source]#

Bases: enum.IntEnum

An enumeration.

HIDPort = 3#
InvalidPort = 0#
SerialPort = 1#
USBPort = 2#
class PropertyType(value)[source]#

Bases: enum.IntEnum

An enumeration.

Float = 2#
Integer = 3#
String = 1#
Undef = 0#
to_json()[source]#
to_python()[source]#