Skip to content

Configuration & Groups#

Configuring a microscope with micro-manager entails storing and retrieving a number of device parameters settings. In general, a single setting comprises a device name, a property name, and a value. A Configuration object represents a collection of individual settings; that is, it represents a number of device parameters all in a specific state, such as would be used to prepare the microscope to image a specific channel, like "DAPI", or "FITC".

A Configuration Group is, in turn, a collection of Configuration objects; for example, all of the Configuration objects that represent different "Channel" settings.

Conceptually, Configurations and Groups are organized like this:

ConfigGroupA:
    Configuration1:
        deviceA:
            propertyA: 'value_a'
            propertyB: 'value_b'
        deviceB:
            propertyC: 'value_c'
        ...
    Configuration2:
        deviceA:
            propertyA: 'value_d'
            propertyB: 'value_e'
        deviceB:
            propertyC: 'value_f'
        ...
    ...
ConfigGroupB:
    Configuration1:
        deviceC:
            propertyA: 'value_g'
        ...
    ...

pymmcore-plus Objects#

MMCore and pymmcore's configuration object implements a basic mutable mapping interface, but with custom method names like addSetting, getSetting, and deleteSetting methods).

pymmcore-plus provides a Configuration subclass that implements a MutableMapping interface, allowing dict-like access to the configuration, where the keys are 2-tuples of (deviceLabel, propertyLabel) and the values are the property values. (Note, however, that iterating of a Configuration object behaves like iterating over a list of 3-tuples (deviceLabel, propertyLabel, value), not a dict.)

pymmcore-plus also offers a ConfigGroup object, which is a MutableMapping where the keys are Configuration Preset names and the values are Configuration objects.

pymmcore_plus.Configuration #

Encapsulation of configuration information.

This is the type of object returned by default (provided native==False) by: getConfigData][pymmcore_plus.CMMCorePlus.getConfigData], [getPixelSizeConfigData getSystemState][pymmcore_plus.CMMCorePlus.getSystemState] [getSystemStateCache getConfigState][pymmcore_plus.CMMCorePlus.getConfigState] [getConfigGroupState `getConfigGroupStateFromCache

This class is a subclass of pymmcore.Configuration that implements an collections.abc.MutableSequence (i.e. it behaves like a Python list). It also behaves much like a collections.abc.MutableMapping, where the keys are 2-tuples of (deviceLabel, propertyLabel) and the values are the property values.

Note that the "order" of this collection is not well-defined, so while you can index with an integer, you should not rely on the order of the items in the collection. __getitem__/__setitem__/__delitem__ all accept a 2-tuple of (deviceLabel, propertyLabel).

It adds a few convenience methods:

Tip

All of the methods in pymmcore_plus.CMMCorePlus that would have returned a pymmcore.Configuration in pymmcore (e.g. getConfigData, getConfigState, etc...). have been reimplemented to return a pymmcore_plus.Configuration object. This object has the same API as pymmcore.Configuration, but you can request a "native" (unenhanced) pymmcore object by passing native=True to the method.

append(setting: pymmcore.PropertySetting | DevPropValueTuple) -> None #

Add a setting to the configuration.

create(*args: Any, **kwargs: Any) -> Configuration classmethod #

More flexible init to create a Configuration.

Can create 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 {Device: {Property: Value}}.

extend(other: pymmcore.Configuration | Iterable[pymmcore.PropertySetting | DevPropValueTuple]) -> None #

Add all settings from another Configuration.

from_configuration(config: pymmcore.Configuration) -> Configuration classmethod #

Create Configuration (Plus) from pymmcore.Configuration.

html() -> str #

Return config representation as HTML.

remove(key: DevPropTuple) -> None #

Remove setting for (devLabel, propLabel) from the configuration.

pymmcore_plus.ConfigGroup #

Convenience object for dealing with a set of related Configuration objects.

This object behaves as a collections.abc.MutableMapping of str (configuration group name) to Configuration objects.

It is object type returned by pymmcore_plus.CMMCorePlus.getConfigGroupObject.

Parameters:

Name Type Description Default
group_name str

The name of the configuration group to manage. (It needn't exist yet)

 required
mmcore CMMCorePlus

The core object managing this config group.

 required

core() -> CMMCorePlus property #

Return the CMMCorePlus instance to which this Device is bound.

create() -> None #

Create this configuration group in core (as an empty group).

If the group already exists, this is a no-op.

delete() -> None #

Delete this entire configuration group and all presets in it.

exists() -> bool #

Return True if this ConfigGroup exists in the current configuration.

getCurrentConfig(as_object: bool = False) -> str | Configuration #

Returns the current configuration for a given group.

getCurrentConfigFromCache(as_object: bool = False) -> str | Configuration #

Returns the current configuration for a given group from the cache.

is_consistent() -> bool property #

Return True if all presets in this group have the same properties.

Note that a group with 0 or 1 presets is always considered consistent. If two or more presets are present, they must all have the same device properties. (values of course may vary.)

iterDeviceProperties() -> Iterator[DeviceProperty] #

Iterate DeviceProperty for all properties in this ConfigGroup.

Note, this only iterates over properties that are defined in the first preset of this ConfigGroup. This should be the same for all presets in this ConfigGroup, but it is not guaranteed. Use is_consistent to check if all presets in this ConfigGroup have the same properties.

name() -> str property #

Return the name of this ConfigGroup.

rename(newGroupName: str) -> None #

Rename this configuration group.

renameConfig(oldConfigName: str, newConfigName: str) -> None #

Rename a configuration in this group.

If the configuration does not exist, a KeyError is thrown.

setConfig(configName: str) -> None #

Set the current configuration to configName.

This actually updates the hardware state to match what is stored in the preset configName.

wait(configName: str | None = None) -> None #

Blocks until all devices included in the configuration group ready.

If configName not provided, then the first configuration in the group is used.