Skip to content

CMMCorePlus#

The main object in pymmcore_plus is the pymmcore_plus.CMMCorePlus class. CMMCorePlus is a subclass of pymmcore.CMMCore with additional functionality, and some overrides for the sake of convenience or fixed behavior.

CMMCorePlus API summary#

This table presents all methods available in the CMMCorePlus class, and indicates which methods are unique to CMMCorePlus (✨) and which methods are overridden from CMMCore (). Below the table, the signatures of all methods are presented, broken into a CMMCorePlus section and a CMMCore section (depending on whether the method is implemented in CMMCorePlus or not).

This method is overridden by CMMCorePlus.
✨ This method only exists in CMMCorePlus.
🚫 This method is deprecated.

Method Description
addGalvoPolygonVertex Add a vertex to a galvo polygon.
canSequenceEvents ✨ Check whether two useq.MDAEvent are sequenceable by this core instance.
channelGroup_pattern ✨ The regex pattern used to identify channel groups.
clearCircularBuffer Removes all images from the circular buffer.
clearROI Set the region of interest of the current camera to the full frame.
debugLogEnabled Indicates if logging of debug messages is enabled
defineConfig Defines a configuration.
defineConfigGroup Creates an empty configuration group.
definePixelSizeConfig Defines an empty pixel size entry.
defineStateLabel Defines a label for the specific state.
deleteConfig Delete configName from groupName.
deleteConfigGroup Deletes an entire configuration group.
deleteGalvoPolygons Remove all added polygons
deletePixelSizeConfig Delete the pixel size configuration for the given resolutionID.
describe ✨ Print information table with the current configuration.
detectDevice Tries to communicate to a device through a given serial port.
deviceBusy Checks the busy status of the specific device.
deviceTypeBusy Checks the busy status for all devices of the specific type.
displaySLMImage Display the waiting image on the SLM.
enableContinuousFocus Enables or disables the operation of the continuous focusing hardware device.
enableDebugLog Enable or disable logging of debug messages.
enableFeature Enable or disable the given Core feature.
enableStderrLog Enables or disables log message display on the standard console.
events ✨ Signaler for core events.
fixImage ✨ Fix img shape/dtype based on self.getNumberOfComponents().
fullFocus Performs focus acquisition and lock for the one-shot focusing device.
getAPIVersionInfo Returns the module and device interface versions.
getAdapterObject ✨ Return an Adapter object bound to library_name on this core.
getAllowedPropertyValues Returns all valid values for the specified property.
getAutoFocusDevice Returns the label of the currently selected auto-focus device.
getAutoFocusOffset Measures offset for the one-shot focusing device.
getAutoShutter Returns the current setting of the auto-shutter option.
getAvailableConfigGroups Returns the names of all defined configuration groups
getAvailableConfigs Returns all defined configuration (preset) names in a given group
getAvailableDeviceDescriptions Get descriptions for available devices from the specified library.
getAvailableDeviceTypes Get type information for available devices from the specified library.
getAvailableDevices Get available devices from the specified device library.
getAvailablePixelSizeConfigs Returns all defined resolution preset names
getBufferFreeCapacity Returns the number of images that can be added to the buffer without
getBufferTotalCapacity Returns the total number of images that can be stored in the buffer
getBytesPerPixel How many bytes for each pixel.
getCameraChannelName Returns the name of the requested channel as known by the default camera
getCameraChannelNames ✨ Convenience method to call getCameraChannelName for all camera channels.
getCameraDevice Returns the label of the currently selected camera device.
getChannelGroup Returns the group determining the channel selection.
getCircularBufferMemoryFootprint Returns the size of the Circular Buffer in MB
getConfigData Return the configuration object for a given configGroup and configName.
getConfigGroupObject ✨ Return a ConfigGroup object bound to group_name on this core.
getConfigGroupState Return the state of the devices included in the specified group.
getConfigGroupStateFromCache Return the state of the system cache, for the devices in the specified group.
getConfigState Return state of devices included in the specified configuration.
getCoreErrorText Returns a pre-defined error test with the given error code
getCurrentConfig Returns the current configuration (preset) for a given group.
getCurrentConfigFromCache Returns the configuration for a given group based on the data in the cache.
getCurrentFocusScore Returns the focus score from the default focusing device measured at the
getCurrentPixelSizeConfig
getDeviceAdapterNames Return the names of discoverable device adapters.
getDeviceAdapterSearchPaths Return the current device adapter search paths.
getDeviceDelayMs Reports action delay in milliseconds for the specific device.
getDeviceDescription Returns description text for a given device label. "Description" is determined
getDeviceInitializationState Queries the initialization state of the given device.
getDeviceLibrary Returns device library (aka module, device adapter) name.
getDeviceName Returns device name for a given device label.
getDeviceObject ✨ Return a Device object bound to device_label on this core.
getDevicePropertyNames Returns all property names supported by the device.
getDeviceSchema ✨ Return JSON-schema describing device device_label and its properties.
getDeviceType Return device type for a given device.
getExposure
getExposureSequenceMaxLength Gets the maximum length of a camera's exposure sequence.
getFocusDevice Returns the label of the currently selected focus device.
getFocusDirection Return device type for a given device.
getGalvoChannel Get the name of the active galvo channel (for a multi-laser galvo device).
getGalvoDevice Returns the label of the currently selected Galvo device.
getGalvoPosition
getGalvoXMinimum Get the Galvo x minimum
getGalvoXRange Get the Galvo x range
getGalvoYMinimum Get the Galvo y minimum
getGalvoYRange Get the Galvo y range
getImage Return the internal image buffer.
getImageBitDepth How many bits of dynamic range are to be expected from the camera.
getImageBufferSize Returns the size of the internal image buffer.
getImageHeight Vertical dimension of the image buffer in pixels.
getImageProcessorDevice Returns the label of the currently selected image processor device.
getImageWidth Horizontal dimension of the image buffer in pixels.
getInstalledDeviceDescription Returns description from the specified peripheral on hubLabel device.
getInstalledDevices Performs auto-detection and loading of child devices that are attached to a
getLastFocusScore Returns the latest focus score from the focusing device.
getLastImage Gets the last image from the circular buffer.
getLastImageAndMD ✨ Return last image from the circular buffer along with metadata.
getLastImageMD
getLoadedDevices Returns an array of labels for currently loaded devices.
getLoadedDevicesOfType Returns an array of labels for currently loaded devices of specific type.
getLoadedPeripheralDevices Return labels of all loaded peripherals of hubLabel device.
getMagnificationFactor Returns the product of all Magnifiers in the system or 1.0 when none is found.
getMultiROI Get multiple ROIs from the current camera device.
getNBeforeLastImageAndMD ✨ Return image taken n images ago along with associated metadata.
getNBeforeLastImageMD Returns a pointer to the pixels of the image that was inserted n images ago.
getNumberOfCameraChannels Returns the number of simultaneous channels the default camera is returning.
getNumberOfComponents Returns the number of components the default camera is returning.
getNumberOfStates Returns the total number of available positions (states).
getOrGuessChannelGroup ✨ Get the channelGroup or find a likely set of candidates.
getParentLabel Returns parent device. Returns empty string if no parent is found.
getPhysicalCameraDevice ✨ Return the name of the actual camera device for a given channel index.
getPixelSizeAffine
getPixelSizeAffineByID Returns the Affine Transform to related camera pixels with stage movement for
getPixelSizeConfigData Return the configuration object for a given pixel size preset configName.
getPixelSizeUm
getPixelSizeUmByID Returns the pixel size in um for the requested pixel size group
getPosition
getPrimaryLogFile Return the name of the primary Core log file.
getProperty Returns the property value for the specified device.
getPropertyFromCache Returns the cached property value for the specified device.
getPropertyLowerLimit Returns the property lower limit value, if the property has limits - 0
getPropertyObject ✨ Return a DeviceProperty object bound to a device/property on this core.
getPropertySequenceMaxLength Queries device property for the maximum number of events that can be put
getPropertyType Return the intrinsic property type for a given device and property.
getPropertyUpperLimit Returns the property upper limit value, if the property has limits - 0
getROI
getRemainingImageCount Returns number ofimages available in the Circular Buffer
getSLMBytesPerPixel Returns the number of bytes per SLM pixel
getSLMDevice Returns the label of the currently selected SLM device.
getSLMExposure Returns the exposure time that will be used by the SLM for illumination
getSLMHeight Returns the height (in "pixels") of the SLM
getSLMNumberOfComponents Returns the number of components (usually these depict colors) of the SLM.
getSLMSequenceMaxLength For SLMs that support sequences, returns the maximum length of the sequence
getSLMWidth Returns the width (in "pixels") of the SLM
getSerialPortAnswer Continuously read from the serial port until the terminating sequence is
getShutterDevice Returns the label of the currently selected shutter device.
getShutterOpen
getStageSequenceMaxLength Gets the maximum length of a stage's position sequence.
getState Returns the current state (position) on the specific device.
getStateFromLabel Obtain the state for a given label.
getStateLabel Returns the current state as the label (string).
getStateLabels Return labels for all states
getSystemState Return the entire system state.
getSystemStateCache Return the entire system state from cache.
getTaggedImage ✨ Return getImage as named tuple with metadata.
getTags ✨ Return a dict of metadata tags for the state of the core.
getTimeoutMs Get the timeout for all wait commands.
getVersionInfo Displays core version.
getXPosition
getXYPosition
getXYStageDevice Returns the label of the currently selected XYStage device.
getXYStageSequenceMaxLength Gets the maximum length of an XY stage's position sequence.
getYPosition
getZPosition ✨ Obtains the current position of the Z axis of the Z stage in microns.
guessObjectiveDevices ✨ Find any loaded devices that are likely to be an Objective/Nosepiece.
hasProperty Checks if device has a property with a specified name.
hasPropertyLimits Queries device if the specific property has limits.
home Perform a hardware homing operation for an XY or focus/Z stage.
incrementalFocus Performs incremental focus for the one-shot focusing device.
initializeAllDevices Calls Initialize() method for each loaded device.
initializeCircularBuffer Initialize circular buffer based on the current camera settings.
initializeDevice Initializes specific device.
instance ✨ Return the global singleton instance of CMMCorePlus.
isBufferOverflowed Indicates whether the circular buffer is overflowed
isConfigDefined Checks if the configuration already exists within a group.
isContinuousFocusDrive Check if a stage has continuous focusing capability.
isContinuousFocusEnabled Checks if the continuous focusing hardware device is ON or OFF.
isContinuousFocusLocked Returns the lock-in status of the continuous focusing device.
isExposureSequenceable Queries camera if exposure can be used in a sequence
isFeatureEnabled Return whether the given Core feature is currently enabled.
isGroupDefined Checks if the group already exists.
isMultiROIEnabled Queries the camera to determine if multiple ROIs are currently set.
isMultiROISupported Queries the camera to determine if it supports multiple ROIs.
isPixelSizeConfigDefined Checks if the Pixel Size Resolution already exists
isPropertyPreInit Tells us whether the property must be defined prior to initialization.
isPropertyReadOnly Tells us whether the property can be modified.
isPropertySequenceable Queries device if the specified property can be used in a sequence
isSequenceRunning
isStageLinearSequenceable Queries if the stage can be used in a linear sequence.
isStageSequenceable Queries stage if it can be used in a sequence
isXYStageSequenceable Queries XY stage if it can be used in a sequence
iterConfigGroups ✨ Iterate ConfigGroup objects for all configs.
iterDeviceAdapters ✨ Iterate over all available device adapters.
iterDevices ✨ Iterate over currently loaded devices.
iterProperties ✨ Iterate over currently loaded (device_label, property_name) pairs.
loadDevice Load a device from the plugin library.
loadExposureSequence Transfer a sequence of exposure times to the camera.
loadGalvoPolygons Load a set of galvo polygons to the device
loadPropertySequence Transfer a sequence of events/states/whatever to the device.
loadSLMSequence Load a sequence of images into the SLM
loadStageSequence Transfer a sequence of events/states/whatever to the device.
loadSystemConfiguration Load a system config file conforming to the MM .cfg format.
loadSystemState Loads the system configuration from the text file conforming to the
loadXYStageSequence Transfer a sequence of stage positions to the xy stage.
logMessage
mda ✨ Return the MDARunner for this CMMCorePlus instance.
noop A static method that does nothing.
objective_device_pattern ✨ Pattern used to guess objective device labels.
pointGalvoAndFire Set the Galvo to an x,y position and fire the laser for a predetermined duration.
popNextImage Gets and removes the next image from the circular buffer.
popNextImageAndMD ✨ Gets and removes the next image (and metadata) from the circular buffer.
popNextImageMD
popNextTaggedImage ✨ Return popNextImageAndMD as named tuple with metadata.
prepareSequenceAcquisition Prepare the camera for the sequence acquisition to save the time in the
readFromSerialPort Reads the contents of the Rx buffer.
registerCallback Register a callback (listener class).
register_mda_engine ✨ Set the MDA Engine to be used on run_mda.
renameConfig Renames a configuration within a specified group.
renameConfigGroup Renames a configuration group.
renamePixelSizeConfig Renames a pixel size configuration.
reset Unloads all devices from the core, clears all configuration data and property
runGalvoPolygons Run a loop of galvo polygons
runGalvoSequence Run a sequence of galvo positions
run_mda ✨ Run a sequence of useq.MDAEvent on a new thread.
saveSystemConfiguration Saves the current system configuration to a text file.
saveSystemState Saves the current system state to a text file of the MM specific format.
setAdapterOrigin
setAdapterOriginXY
setAutoFocusDevice Sets the current auto-focus device.
setAutoFocusOffset Applies offset the one-shot focusing device.
setAutoShutter Set shutter to automatically open and close when an image is acquired.
setCameraDevice Sets the current camera device.
setChannelGroup Specifies the group determining the channel selection.
setCircularBufferMemoryFootprint Reserve memory for the circular buffer.
setConfig Applies a configuration to a group.
setContext ✨ Set core properties in a context restoring the initial values on exit.
setDeviceAdapterSearchPaths Set the device adapter search paths.
setDeviceDelayMs Overrides the built-in value for the action delay.
setExposure
setFocusDevice Set the current Focus Device and emit a propertyChanged signal.
setFocusDirection Set the focus direction of a stage.
setGalvoDevice Sets the current galvo device.
setGalvoIlluminationState Set the galvo's illumination state to on or off
setGalvoPolygonRepetitions Set the number of times to loop galvo polygons
setGalvoPosition Set the Galvo to an x,y position.
setGalvoSpotInterval Set the SpotInterval for the specified galvo device.
setImageProcessorDevice Sets the current image processor device.
setMultiROI Set multiple ROIs for the current camera device.
setOrigin
setOriginX
setOriginXY
setOriginY
setParentLabel Sets parent device label
setPixelSizeAffine Sets the raw affine transform for the specific pixel size configuration.
setPixelSizeConfig Applies a Pixel Size Configuration.
setPixelSizeUm Set pixel size in microns for the specified resolutionID.
setPosition Set position of the stage in microns.
setPrimaryLogFile
setProperty Set property named propName on device label to propValue.
setROI Set the camera Region of Interest (ROI).
setRelativePosition
setRelativeXYPosition
setRelativeXYZPosition ✨ Sets the relative XYZ position in microns.
setSLMDevice Sets the current slm device.
setSLMExposure For SLM devices with build-in light source (such as projectors),
setSLMImage
setSLMPixelsTo
setSerialPortCommand Send string to the serial device and return an answer.
setSerialProperties Sets all com port properties in a single call.
setShutterDevice the current shutter device.
setShutterOpen Open or close the currently selected or shutterLabel shutter.
setStageLinearSequence Loads a linear sequence (defined by stepsize and nr. of steps) into the device.
setState Set state (by position) on stateDeviceLabel, with reliable event emission.
setStateLabel Set state (by label) on stateDeviceLabel, with reliable event emission.
setSystemState Sets all properties contained in the Configuration object.
setTimeoutMs Sets the timeout for all wait commands.
setXYPosition Sets the position of the XY stage in microns.
setXYStageDevice Sets the current XY device.
setZPosition ✨ Set the position of the current focus device in microns.
sleep Waits (blocks the calling thread) for specified time in milliseconds.
snap ✨ Snap and return an image.
snapImage Acquires a single image with current settings.
startContinuousSequenceAcquisition Start a ContinuousSequenceAcquisition.
startExposureSequence Starts an ongoing sequence of triggered exposures in a camera.
startPropertySequence Starts an ongoing sequence of triggered events in a property of a device.
startSLMSequence Starts the sequence previously uploaded to the SLM
startSecondaryLogFile
startSequenceAcquisition Starts streaming camera sequence acquisition.
startStageSequence Starts an ongoing sequence of triggered events in a stage.
startXYStageSequence Starts an ongoing sequence of triggered events in an XY stage.
state ✨ Return info on the current state of the core.
stderrLogEnabled Indicates whether logging output goes to stdErr
stop Stop the XY or focus/Z stage motors
stopExposureSequence Stops an ongoing sequence of triggered exposures in a camera.
stopPropertySequence Stops an ongoing sequence of triggered events in a property of a device.
stopSLMSequence Stops the SLM sequence if previously started
stopSecondaryLogFile Stop capturing logging output into an additional file.
stopSequenceAcquisition Stops streaming camera sequence acquisition.
stopStageSequence Stops an ongoing sequence of triggered events in a stage.
stopXYStageSequence Stops an ongoing sequence of triggered events in an XY stage.
supportsDeviceDetection Return whether or not the device supports automatic device detection (i.e.
systemBusy Checks the busy status of the entire system.
systemConfigurationFile ✨ Return the path to the last loaded system configuration file, or None.
this
thisown
unloadAllDevices Unload all devices from the core and reset all configuration data.
unloadDevice Unloads the device from the core and adjusts all configuration data.
unloadLibrary Forcefully unload a library.
updateCoreProperties Updates CoreProperties (currently all Core properties are devices types) with
updateSystemStateCache Updates the state of the entire hardware.
usesDeviceDelay Signals if the device will use the delay setting or not.
waitForConfig Blocks until all devices included in the configuration become ready.
waitForDevice Waits (blocks the calling thread) until the specified device becomes non-busy.
waitForDeviceType Blocks until all devices of the specific type become ready (not-busy).
waitForSystem Blocks until all devices in the system become ready (not-busy).
writeToSerialPort Sends an array of characters to the serial port and returns immediately.

pymmcore_plus.CMMCorePlus #

Wrapper for CMMCore with extended functionality.

Parameters:

Name Type Description Default
mm_path str | None, optional

Path to the Micro-Manager installation. If None (default), will use the return value of pymmcore_plus.find_micromanager.

None
adapter_paths Sequence[str], optional

Paths to search for device adapters, by default ()

()

canSequenceEvents(e1: MDAEvent, e2: MDAEvent, cur_length: int = -1) -> bool #

Check whether two useq.MDAEvent are sequenceable by this core instance.

Micro-manager calls hardware triggering "sequencing". Two events can be sequenced if all device properties that are changing between the first and second event support sequencing.

If cur_length is provided, it is used to determine if the sequence is "full" (i.e. the sequence is already at the maximum length) as determined by the ...SequenceMaxLength() method corresponding to the device property.

See: https://micro-manager.org/Hardware-based_Synchronization_in_Micro-Manager

✨ This method is new in CMMCorePlus.

Parameters:

Name Type Description Default
e1 MDAEvent

The first event.

required
e2 MDAEvent

The second event.

required
cur_length int

The current length of the sequence. Used when checking .get<...>SequenceMaxLength for a given property. If the current length is greater than the max length, the events cannot be sequenced. By default -1, which means the current length is not checked.

-1

Returns:

Type Description
bool

True if the events can be sequenced, False otherwise.

Examples:

Note

The results here will depend on the current state of the core and devices.

>>> from useq import MDAEvent
>>> core = CMMCorePlus.instance()
>>> core.loadSystemConfiguration()
>>> core.canSequenceEvents(MDAEvent(), MDAEvent())
True
>>> core.canSequenceEvents(MDAEvent(x_pos=1), MDAEvent(x_pos=2))
False
>>> core.canSequenceEvents(
...     MDAEvent(channel={'config': 'DAPI'}),
...     MDAEvent(channel={'config': 'FITC'})
... )
False

channelGroup_pattern() -> Pattern property writable #

The regex pattern used to identify channel groups.

✨ *This property is new in CMMCorePlus.

It is the regex used by getOrGuessChannelGroup to find a config group likely to be a channel group in getAvailableConfigGroups if getChannelGroup returns None.

By default:

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

defineConfig(groupName: str, configName: str, deviceLabel: str | None = None, propName: str | None = None, value: str | None = None) -> None #

Defines a configuration.

Why Override?
To emit a configDefined event. Also, if groupName is not a defined group, then defineConfigGroup(groupName) is called.

definePixelSizeConfig(*args: str, **kwargs: str) -> None #

Defines an empty pixel size entry.

Why Override?
To emit a pixelSizeChanged event.

deleteConfig(groupName: str, configName: str, deviceLabel: str | None = None, propName: str | None = None) -> None #

Delete configName from groupName.

Why Override?
To emit a configDeleted event.

deleteConfigGroup(group: str) -> None #

Deletes an entire configuration group.

Why Override?
To emit a configGroupDeleted event.

deletePixelSizeConfig(resolutionID: str) -> None #

Delete the pixel size configuration for the given resolutionID.

Why Override?
To emit a pixelSizeChanged event.

describe(sort: str | None = None) -> None #

Print information table with the current configuration.

Intended to provide a quick overview of the microscope configuration during interactive terminal usage.

✨ This method is new in CMMCorePlus.

detectDevice(deviceLabel: str) -> 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.

Why Override?
The returned pymmcore_plus.DeviceDetectionStatus enum is more interpretable than the raw int returned by pymmcore

events() -> PCoreSignaler property #

Signaler for core events.

✨ This method is new in CMMCorePlus.

This attribute allows connecting callbacks to various events that occur within the core. See pymmcore_plus.core.events.PCoreSignaler documentation for details of the available signals, and how to connect to them.

fixImage(img: np.ndarray, ncomponents: int | None = None) -> np.ndarray #

Fix img shape/dtype based on self.getNumberOfComponents().

✨ This method is new in CMMCorePlus.

convert images with n_components > 1 to a shape (w, h, num_components) and dtype img.dtype.itemsize//ncomp

Parameters:

Name Type Description Default
img np.ndarray

input image

required
ncomponents int, optional

number of components in the image, by default self.getNumberOfComponents()

None

Returns:

Type Description
np.ndarray

output image (possibly new shape and dtype)

getAdapterObject(library_name: str) -> DeviceAdapter #

Return an Adapter object bound to library_name on this core.

✨ This method is new in CMMCorePlus.

Adapter objects are a convenient object oriented way to interact with device adapters. They allow you to call any method on CMMCore that normally requires a library_name as the first argument as an argument-free method on the Adapter object.

getAutoFocusOffset() -> float #

getCameraChannelNames() -> tuple[str, ...] #

Convenience method to call getCameraChannelName for all camera channels.

✨ This method is new in CMMCorePlus.

getConfigData(configGroup: str, configName: str, *, native: bool = False) -> Configuration | pymmcore.Configuration #

Return the configuration object for a given configGroup and configName.

Why Override?
The pymmcore_plus.Configuration object returned when native=False (the default) provides a nicer Mapping interface. Pass native=True to get the original pymmcore.Configuration object.

getConfigGroupObject(group_name: str, allow_missing: bool = False) -> ConfigGroup #

Return a ConfigGroup object bound to group_name on this core.

✨ This method is new in CMMCorePlus.

ConfigGroup objects are a convenient object oriented way to interact with configuration groups (i.e. groups of Configuration Presets in Micro-Manager). They allow you to call any method on CMMCore that normally requires a groupName as the first argument as an argument-free method on the ConfigGroup object.

Parameters:

Name Type Description Default
group_name str

Configuration group name to get a config group object for.

required
allow_missing bool

If False and the ConfigGroup does not exist, a KeyError will be raised. By default False.

False

Returns:

Type Description
ConfigGroup

ConfigGroup object bound to group_name on this core.

getConfigGroupState(group: str, *, native: bool = False) -> Configuration | pymmcore.Configuration #

Return the state of the devices included in the specified group.

Why Override?
The pymmcore_plus.Configuration object returned when native=False (the default) provides a nicer Mapping interface. Pass native=True to get the original pymmcore.Configuration object.

getConfigGroupStateFromCache(group: str, *, native: bool = False) -> Configuration | pymmcore.Configuration #

Return the state of the system cache, for the devices in the specified group.

Why Override?
The pymmcore_plus.Configuration object returned when native=False (the default) provides a nicer Mapping interface. Pass native=True to get the original pymmcore.Configuration object.

getConfigState(group: str, config: str, *, native: bool = False) -> Configuration | pymmcore.Configuration #

Return state of devices included in the specified configuration.

Why Override?
The pymmcore_plus.Configuration object returned when native=False (the default) provides a nicer Mapping interface. Pass native=True to get the original pymmcore.Configuration object.

getDeviceInitializationState(label: str) -> DeviceInitializationState #

Queries the initialization state of the given device.

Why Override?
The returned pymmcore_plus.DeviceInitializationState enum is more interpretable than the raw int returned by pymmcore

getDeviceObject(device_label: str) -> Device #

Return a Device object bound to device_label on this core.

✨ This method is new in CMMCorePlus.

Device objects are a convenient object oriented way to interact with devices. They allow you to call any method on CMMCore that normally requires a deviceLabel as the first argument as an argument-free method on the Device object.

Parameters:

Name Type Description Default
device_label str

Device label to get a device object for.

required

Examples:

>>> core = CMMCorePlus()
>>> cam = core.getDeviceObject("DemoCamera")
>>> cam.isLoaded()
False
>>> cam.load("DemoCamera", "DCam")
>>> cam.isLoaded()
True
>>> cam.initialize()

get the device schema

>>> cam.schema()
{
    'title': 'DCam',
    'description': 'Demo camera',
    'type': 'object',
    'properties': {
        'HubID': {'type': 'string', 'readOnly': True, 'default': ''},
        'MaximumExposureMs': {'type': 'number', 'preInit': True},
        'TransposeCorrection': {'type': 'boolean'},
        'TransposeMirrorX': {'type': 'boolean'},
        'TransposeMirrorY': {'type': 'boolean'},
        'TransposeXY': {'type': 'boolean'}
    }
}

getDeviceSchema(device_label: str) -> DeviceSchema #

Return JSON-schema describing device device_label and its properties.

✨ This method is new in CMMCorePlus. It provides a convenient way to get all of the information about a device in a single call.

Returns:

Type Description
DeviceSchema

JSON-schema describing device device_label and its properties.

Examples:

>>> core = CMMCorePlus()
>>> core.loadDevice("DemoCamera", "DemoCamera", "DCam")
>>> core.getDeviceSchema("DemoCamera")
{
    'title': 'DCam',
    'description': 'Demo camera',
    'type': 'object',
    'properties': {
        'HubID': {'type': 'string', 'readOnly': True, 'default': ''},
        'MaximumExposureMs': {'type': 'number', 'preInit': True},
        'TransposeCorrection': {'type': 'boolean'},
        'TransposeMirrorX': {'type': 'boolean'},
        'TransposeMirrorY': {'type': 'boolean'},
        'TransposeXY': {'type': 'boolean'}
    }
}

getDeviceType(label: str) -> DeviceType #

Return device type for a given device.

Why Override?
The returned pymmcore_plus.Device enum is more interpretable than the raw int returned by pymmcore

getFocusDirection(stageLabel: str) -> FocusDirection #

Return device type for a given device.

Why Override?
The returned pymmcore_plus.FocusDirection enum is more interpretable than the raw int returned by pymmcore

getImage(numChannel: int | None = None, *, fix: bool = True) -> np.ndarray #

Return the internal image buffer.

Why Override?
To fix the shape of images with n_components > 1 (like RGB images)

Parameters:

Name Type Description Default
numChannel int, optional

The camera channel to get the image from. If None, (the default), then Multi-Channel cameras will return the content of the first channel.

None
fix bool, default

If True (the default), then images with n_components > 1 (like RGB images) will be reshaped to (w, h, n_components) using fixImage.

True

getLastImageAndMD(channel: int | None = None, slice: int | None = None, *, fix: bool = True) -> tuple[np.ndarray, Metadata] #

Return last image from the circular buffer along with metadata.

✨ This method is new in CMMCorePlus.

This is a convenience method that is very similar to getLastImageMD, except that it doesn't require instantiating a MetaData object first. It returns a tuple containing the image and a pymmcore_plus.Metadata object.

It also adds a fix parameter, which reshapes multi-component images (like RGB images) to (w, h, n_components) using fixImage by default.

Parameters:

Name Type Description Default
channel int, optional

Channel index, by default None

None
slice int, optional

Slice index, by default None

None
fix bool, default

If True (the default), then images with n_components > 1 (like RGB images) will be reshaped to (w, h, n_components) using fixImage.

True

Returns:

Type Description
tuple[np.ndarray, Metadata]

Image and metadata

getMultiROI(*_: Any) -> tuple[list[int], list[int], list[int], list[int]] #

Get multiple ROIs from the current camera device.

Will fail if the camera does not support multiple ROIs. Will return empty vectors if multiple ROIs are not currently being used.

Why Override?
So that the user doesn't need to pass in four empty pymmcore.UnsignedVector() objects.

getNBeforeLastImageAndMD(n: int, *, fix: bool = True) -> tuple[np.ndarray, Metadata] #

Return image taken n images ago along with associated metadata.

✨ This method is new in CMMCorePlus.

This is a convenience method that is very similar to getNBeforeLastImageMD, except that it doesn't require instantiating a MetaData object first. It returns a tuple containing the image and a pymmcore_plus.Metadata object.

It also adds a fix parameter, which reshapes multi-component images (like RGB images) to (w, h, n_components) using fixImage by default.

Parameters:

Name Type Description Default
n int

The number of images ago to retrieve. 0 is the last image, 1 is the image before that, etc.

required
fix bool, default

If True (the default), then images with n_components > 1 (like RGB images) will be reshaped to (w, h, n_components) using fixImage.

True

getOrGuessChannelGroup() -> list[str] #

Get the channelGroup or find a likely set of candidates.

✨ This method is new in CMMCorePlus.

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)

getPhysicalCameraDevice(channel_index: int = 0) -> str #

Return the name of the actual camera device for a given channel index.

✨ This method is new in CMMCorePlus. It provides a convenience for accessing the name of the actual camera device when using the multi-camera utility.

getPixelSizeConfigData(configName: str, *, native: bool = False) -> Configuration | pymmcore.Configuration #

Return the configuration object for a given pixel size preset configName.

Why Override?
The pymmcore_plus.Configuration object returned when native=False (the default) provides a nicer Mapping interface. Pass native=True to get the original pymmcore.Configuration object.

getPropertyObject(device_label: str, property_name: str) -> DeviceProperty #

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

✨ This method is new in CMMCorePlus.

DeviceProperty objects are a convenient object oriented way to interact with a specific device properties. They allow you to call any method on CMMCore that normally requires a deviceLabel and propertyName as the first two arguments as an argument-free method on the DeviceProperty object.

Parameters:

Name Type Description Default
device_label str

Device label to get a property object for.

required
property_name str

Property name to get a property object for.

required

Examples:

>>> core = CMMCorePlus()
>>> core.loadDevice("DemoCamera", "DemoCamera", "DCam")
>>> core.initializeDevice("DemoCamera")
>>> core.setCameraDevice("DemoCamera")
>>> exposure = core.getPropertyObject("DemoCamera", "Exposure")
>>> exposure.type()
<PropertyType.Float: 2>
>>> exposure.upperLimit()
10000.0

get/set property values easily:

>>> exposure.value
10.0
>>> exposure.value = 5.0
>>> exposure.value
5.0
>>> core.getExposure()  # changes reflected in core
5.0

getPropertyType(label: str, propName: str) -> PropertyType #

Return the intrinsic property type for a given device and property.

Why Override?
The returned pymmcore_plus.PropertyType enum is more interpretable than the raw int returned by pymmcore

getSystemState(*, native: bool = False) -> Configuration | pymmcore.Configuration #

Return the entire system state.

Why Override?
The pymmcore_plus.Configuration object returned when native=False (the default) provides a nicer Mapping interface. Pass native=True to get the original pymmcore.Configuration object.

getSystemStateCache(*, native: bool = False) -> Configuration | pymmcore.Configuration #

Return the entire system state from cache.

Why Override?
The pymmcore_plus.Configuration object returned when native=False (the default) provides a nicer Mapping interface. Pass native=True to get the original pymmcore.Configuration object.

getTaggedImage(channel_index: int = 0) -> TaggedImage #

Return getImage as named tuple with metadata.

✨ This method is new in CMMCorePlus. It returns an object similar to MMCoreJ.getTaggedImage().

getTags(meta: Metadata | None = None, channel_index: int | None = None) -> dict[str, Any] #

Return a dict of metadata tags for the state of the core.

NOTE: this function is pretty slow, and is potentially called on every frame of an acquisition. It would be nice to determine what is absolutely necessary, and possible allow the user to specify what they want to include.

✨ This method is new in CMMCorePlus. It returns only the .tags attribute of what you would get with getTaggedImage() or popNextTaggedImage().

getZPosition() -> float #

Obtains the current position of the Z axis of the Z stage in microns.

✨ This method is new in CMMCorePlus: added to complement getXPosition and getYPosition

Note

This is simply an alias for getPosition], which returns the position of the current focus device when called without arguments.

guessObjectiveDevices() -> list[str] #

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

✨ This method is new in CMMCorePlus.

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)

instance() -> CMMCorePlus classmethod #

Return the global singleton instance of CMMCorePlus.

✨ This method is new in CMMCorePlus.

In many cases, a single instance of CMMCorePlus is all that will be created in a given session. This class method provides a convenient way to access that instance.

Tip

Creating/accessing a CMMCorePlus object using CMMCorePlus.instance() is a convenient way to access the same core instance from multiple places in your code. All widgets in pymmcore-widgets also use CMMCorePlus.instance() by default, so any widgets you use will automatically connect to the same core instance without any additional configuration.

Attempts are made to make it thread-safe. But please open an issue if you find any problems.

iterConfigGroups() -> Iterator[ConfigGroup] #

Iterate ConfigGroup objects for all configs.

✨ This method is new in CMMCorePlus.

Yields:

Type Description
ConfigGroup

ConfigGroup objects

iterDeviceAdapters(adapter_pattern: str | re.Pattern | None = None, *, as_object: bool = True) -> Iterator[DeviceAdapter] | Iterator[str] #

Iterate over all available device adapters.

✨ This method is new in CMMCorePlus.

It offers a convenient way to iterate over available device adaptor libraries, optionally filtering adapter library name. It can also yield Adapter objects if as_object is True (the default)

Parameters:

Name Type Description Default
adapter_pattern str | None

Device adapter name or pattern to filter by, by default all device adapters will be yielded.

None
as_object bool, optional

If True, Adapter objects will be yielded instead of library name strings. By default True

True

Yields:

Type Description
Device | str

Device objects (if as_object==True) or device label strings.

iterDevices(device_type: int | Iterable[int] | None = None, device_label: str | re.Pattern | None = None, device_adapter: str | re.Pattern | None = None, *, as_object: bool = True) -> Iterator[Device] | Iterator[str] #

Iterate over currently loaded devices.

✨ This method is new in CMMCorePlus.

It offers a convenient way to iterate over loaded devices, optionally filtering by DeviceType and/or device label. It can also yield Device objects if as_object is True (the default).

Parameters:

Name Type Description Default
device_type DeviceType | None

DeviceType to filter by, by default all device types will be yielded.

None
device_label str | None

Device label to filter by, by default all device labels will be yielded.

None
device_adapter str | None

Device adapter library to filter by, by default devices from all libraries will be yielded.

None
as_object bool, optional

If True, Device objects will be yielded instead of device label strings. By default True

True

Yields:

Type Description
Device | str

Device objects (if as_object==True) or device label strings.

iterProperties(property_type: int | Iterable[int] | None = None, property_name_pattern: str | re.Pattern | None = None, *, device_type: int | Iterable[int] | None = None, device_label: str | re.Pattern | None = None, has_limits: bool | None = None, is_read_only: bool | None = None, is_sequenceable: bool | None = None, as_object: bool = True) -> Iterator[DeviceProperty] | Iterator[tuple[str, str]] #

Iterate over currently loaded (device_label, property_name) pairs.

✨ This method is new in CMMCorePlus.

It offers a convenient way to iterate over loaded devices, optionally filtering by DeviceType and/or device label. It can also yields DeviceProperty objects if as_object is True (the default).

Parameters:

Name Type Description Default
property_type int | Sequence[int] | None

PropertyType (or types) to filter by, by default all property types will be yielded.

None
property_name_pattern str | re.Pattern | None

Property name to filter by, by default all property names will be yielded. May be a compiled regular expression or a string, in which case it will be compiled with re.IGNORECASE.

None
device_type DeviceType | None

DeviceType to filter by, by default all device types will be yielded.

None
device_label str | None

Device label to filter by, by default all device labels will be yielded.

None
has_limits bool | None

If provided, only properties with hasPropertyLimits matching this value will be yielded.

None
is_read_only bool | None

If provided, only properties with isPropertyReadOnly matching this value will be yielded.

None
is_sequenceable bool | None

If provided only properties with isPropertySequenceable matching this value will be yielded.

None
as_object bool, optional

If True, DeviceProperty objects will be yielded instead of (device_label, property_name) tuples. By default True

True

Yields:

Type Description
DeviceProperty | tuple[str, str]

DeviceProperty objects (if as_object==True) or 2-tuples of (device_name, property_name)

loadDevice(label: str, moduleName: str, deviceName: str) -> None #

Load a device from the plugin library.

Why Override?
To add much better error messages in the case of failure.

Parameters:

Name Type Description Default
label str

Name to be assigned to the device during this core session.

required
moduleName str

The name of the device adapter module (short name, not full file name). See pymmcore.CMMCore.getDeviceAdapterNames for a list of valid module names.

required
deviceName str

the name of the device. The name must correspond to one of the names recognized by the specific plugin library. See pymmcore.CMMCore.getAvailableDevices for a list of valid device names.

required

loadSystemConfiguration(fileName: str | Path = 'MMConfig_demo.cfg') -> None #

Load a system config file conforming to the MM .cfg format.

https://micro-manager.org/Micro-Manager_Configuration_Guide#configuration-file-syntax

For relative paths, the current working directory is first checked, then the then device adapter path is checked.

Why Override?
This method overrides the default implementation to A) allow loading the MMConfig_demo.cfg file by default, B) to provide more flexible path declarations and C) better error messages when the file cannot be found.

mda() -> MDARunner property #

Return the MDARunner for this CMMCorePlus instance.

✨ This method is new in CMMCorePlus.

objective_device_pattern() -> Pattern property writable #

Pattern used to guess objective device labels.

✨ *This property is new in CMMCorePlus.

It is the regex used by guessObjectiveDevices to find any devices that are likely to be objective devices.

By default:

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

popNextImage(*, fix: bool = True) -> np.ndarray #

Gets and removes the next image from the circular buffer.

Why Override?
to add the fix parameter, which reshapes multi-component images (like RGB images) to (w, h, n_components) using fixImage by default.

Parameters:

Name Type Description Default
fix bool, default

If True (the default), then images with n_components > 1 (like RGB images) will be reshaped to (w, h, n_components) using fixImage.

True

popNextImageAndMD(channel: int = 0, slice: int = 0, *, fix: bool = True) -> tuple[np.ndarray, Metadata] #

Gets and removes the next image (and metadata) from the circular buffer.

✨ This method is new in CMMCorePlus.

This is a convenience method that is very similar to popNextImageMD, except that it doesn't require instantiating a MetaData object first. It returns a tuple containing the image and a pymmcore_plus.Metadata object.

It also adds a fix parameter, which reshapes multi-component images (like RGB images) to (w, h, n_components) using fixImage by default.

Parameters:

Name Type Description Default
channel int, optional

Channel index, by default None

0
slice int, optional

Slice index, by default None

0
fix bool, default

If True (the default), then images with n_components > 1 (like RGB images) will be reshaped to (w, h, n_components) using fixImage.

True

Returns:

Type Description
tuple[np.ndarray, Metadata]

Image and metadata

popNextTaggedImage(channel_index: int = 0) -> TaggedImage #

Return popNextImageAndMD as named tuple with metadata.

✨ This method is new in CMMCorePlus. It returns an object similar to MMCoreJ.popNextTaggedImage().

register_mda_engine(engine: PMDAEngine) -> None #

Set the MDA Engine to be used on run_mda.

✨ This method is new in CMMCorePlus.

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:

Name Type Description Default
engine PMDAEngine

Any object conforming to the PMDAEngine protocol.

required

run_mda(events: Iterable[MDAEvent], *, output: SingleOutput | Sequence[SingleOutput] | None = None, block: bool = False) -> Thread #

Run a sequence of useq.MDAEvent on a new thread.

✨ This method is new in CMMCorePlus.

The currently registered MDAEngine (core.mda.engine) 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:

Name Type Description Default
events Iterable[useq.MDAEvent]

An iterable of useq.MDAEvent to execute. This may be an instance of useq.MDASequence, or any other iterable of useq.MDAEvent.

required
output SingleOutput | Sequence[SingleOutput] | None, optional

The output handler(s) to use. If None, no output will be saved. "SingleOutput" can be any of the following:

  • A string or Path to a directory to save images to. A handler will be created automatically based on the extension of the path.
  • A handler object that implements the DataHandler protocol, currently meaning it has a frameReady method. See mda_listeners_connected for more details.
  • A sequence of either of the above. (all will be connected)
None
block bool, optional

If True, block until the sequence is complete, by default False.

False

Returns:

Type Description
Thread

The thread the sequence is running on. Use thread.join() to block until done, or thread.is_alive() to check if the sequence is complete.

saveSystemConfiguration(filename: str) -> None #

Saves the current system configuration to a text file.

Why Override?
To also save pixel size configurations.

setAutoFocusOffset(offset: float) -> None #

Applies offset the one-shot focusing device.

In micro-manager, there is some variability in the way that autofocus devices are implemented. Some have a separate offset device, while others can directly set the offset of an associated device. As a result, calling setAutoFocusOffset, may or may not do anything depending on the current autofocus device.

This method attempts to detect known autofocus devices and

setAutoShutter(state: bool) -> None #

Set shutter to automatically open and close when an image is acquired.

Why Override?
To emit an autoShutterSet event.

setChannelGroup(channelGroup: str) -> None #

Specifies the group determining the channel selection.

...and send a channelGroupChanged signal.

setConfig(groupName: str, configName: str) -> None #

Applies a configuration to a group.

Why Override?
The native onConfigGroupChanged callback is not always called whenever CMMCore.setConfig has been called. We override here to emit a configSet event whenever setConfig is called. See https://github.com/micro-manager/mmCoreAndDevices/issues/25 for details.

setContext(**kwargs: Any) -> Iterator[None] #

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

✨ This method is new in CMMCorePlus.

Parameters:

Name Type Description Default
**kwargs Any

Keyword arguments may be any Name for which get<Name> and set<Name> methods exist. For example, setContext(exposure=10) will call setExposure(10) when entering the context and setExposure(<initial>) when exiting the context.

{}

Examples:

core = CMMCorePlus.instance()

with core.setContext(autoShutter=False):
    assert not core.getAutoShutter()
    # do other stuff
    ...

# autoShutter is restored to its original value when the context exits
assert core.getAutoShutter()

setDeviceAdapterSearchPaths(paths: Sequence[str]) -> None #

Set the device adapter search paths.

Why Override?
In cases where MM device adapters use dynamically loaded libraries, the device adapter search paths must also be added to the PATH environment variable (e.g. https://github.com/micro-manager/pymmcore/issues/28). This method overrides the default implementation to ensure that the PATH environment variable is updated when the device adapter search paths are changed.

setFocusDevice(focusLabel: str) -> None #

Set the current Focus Device and emit a propertyChanged signal.

setPixelSizeUm(resolutionID: str, pixSize: float) -> None #

Set pixel size in microns for the specified resolutionID.

Why Override?
To emit a pixelSizeChanged event.

setPosition(*args: Any, **kwargs: Any) -> None #

Set position of the stage in microns.

Why Override?
To add a lock to prevent concurrent calls across threads.

setProperty(label: str, propName: str, propValue: bool | float | int | str) -> None #

Set property named propName on device label to propValue.

Why Override?
In MMCore, the calling of the onPropertyChanged callback is left to the underlying device adapter, which means it is not always called. This method overrides the default implementation to ensure that events.propertyChanged is always emitted when setProperty has been called and the property Value has actually changed.

setROI(*args: Any, **kwargs: Any) -> None #

Set the camera Region of Interest (ROI).

Why Override?
To emit a roiSet event.

setRelativeXYZPosition(dx: float = 0, dy: float = 0, dz: float = 0) -> None #

Sets the relative XYZ position in microns.

✨ This method is new in CMMCorePlus.

This is a convenience method that calls setXYPosition and setZPosition with the current position as the starting point.

Parameters:

Name Type Description Default
dx float, optional

The relative change in X position, by default 0

0
dy float, optional

The relative change in Y position, by default 0

0
dz float, optional

The relative change in Z position, by default 0

0

setShutterOpen(*args: Any, **kwargs: Any) -> None #

Open or close the currently selected or shutterLabel shutter.

Why Override?
To emit a propertyChanged event.

setState(stateDeviceLabel: str, state: int) -> None #

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

Why Override?
In MMCore, the calling of the onPropertyChanged callback is left to the underlying device adapter, which means it is not always called. This method overrides the default implementation to ensure that events.propertyChanged is always emitted when setProperty has been called and the property Value has actually changed.

setStateLabel(stateDeviceLabel: str, stateLabel: str) -> None #

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

Why Override?
In MMCore, the calling of the onPropertyChanged callback is left to the underlying device adapter, which means it is not always called. This method overrides the default implementation to ensure that events.propertyChanged is always emitted when setProperty has been called and the property Value has actually changed.

setXYPosition(*args: Any, **kwargs: Any) -> None #

Sets the position of the XY stage in microns.

Why Override?
To add a lock to prevent concurrent calls across threads.

setZPosition(val: float) -> None #

Set the position of the current focus device in microns.

✨ This method is new in CMMCorePlus: added to complement setXYPosition

Note

This is simply an alias for setPosition, which returns the position of the current focus device when called with a single argument.

snap(numChannel: int | None = None, *, fix: bool = True) -> np.ndarray #

Snap and return an image.

✨ This method is new in CMMCorePlus.

Convenience for calling self.snapImage() followed by returning the value of self.getImage().

Parameters:

Name Type Description Default
numChannel int, optional

The camera channel to get the image from. If None, (the default), then Multi-Channel cameras will return the content of the first channel.

None
fix bool, default

If True (the default), then images with n_components > 1 (like RGB images) will be reshaped to (w, h, n_components) using fixImage.

True

Returns:

Name Type Description
img np.ndarray

snapImage() -> None #

Acquires a single image with current settings.

Why Override?
To add a lock to prevent concurrent calls across threads.

startContinuousSequenceAcquisition(intervalMs: float = 0) -> None #

Start a ContinuousSequenceAcquisition.

Why Override?
To emit a startContinuousSequenceAcquisition event.

startSequenceAcquisition(*args: Any, **kwargs: Any) -> None #

Starts streaming camera sequence acquisition.

This command does not block the calling thread for the duration of the acquisition.

Why Override?
To emit a startSequenceAcquisition event.

state(*, cached: bool = True, include_time: bool = False, **_kwargs: Any) -> SummaryMetaV1 #

Return info on the current state of the core.

stopSequenceAcquisition(cameraLabel: str | None = None) -> None #

Stops streaming camera sequence acquisition.

(for a specified camera if cameraLabel is provided.)

Why Override?
To emit a stopSequenceAcquisition event.

systemConfigurationFile() -> str | None #

Return the path to the last loaded system configuration file, or None.

✨ This method is new in CMMCorePlus.

unloadAllDevices() -> None #

Unload all devices from the core and reset all configuration data.

Why Override?
To add logging.


Info

The pymmcore.CMMCore methods below are available as inherited methods, but are not reimplemented in the CMMCorePlus subclass. They are documented here for completeness.

pymmcore.CMMCore #

addGalvoPolygonVertex(galvoLabel: str, polygonIndex: int, x: float, y: float) -> None #

Add a vertex to a galvo polygon.

clearCircularBuffer() -> None #

Removes all images from the circular buffer.

clearROI() -> None #

Set the region of interest of the current camera to the full frame.

debugLogEnabled() -> bool #

Indicates if logging of debug messages is enabled

defineConfigGroup(groupName: str) -> None #

Creates an empty configuration group.

defineStateLabel(stateDeviceLabel: DeviceLabel | str, state: int, stateLabel: str) -> None #

Defines a label for the specific state.

deleteGalvoPolygons(galvoLabel: DeviceLabel | str) -> None #

Remove all added polygons

deviceBusy(label: DeviceLabel | str) -> bool #

Checks the busy status of the specific device.

deviceTypeBusy(devType: DeviceType) -> bool #

Checks the busy status for all devices of the specific type.

displaySLMImage(slmLabel: DeviceLabel | str) -> None #

Display the waiting image on the SLM.

enableContinuousFocus(enable: bool) -> None #

Enables or disables the operation of the continuous focusing hardware device.

enableDebugLog(enable: bool) -> None #

Enable or disable logging of debug messages.

enableFeature(name: Literal['StrictInitializationChecks'] | str, enable: bool) -> None #

Enable or disable the given Core feature.

Core features control whether experimental functionality (which is subject to breaking changes) is exposed, or whether stricter API usage is enforced.

Currently switchable features:

  • "StrictInitializationChecks" (default: disabled) When enabled, an exception is thrown when an operation requiring an initialized device is attempted on a device that is not successfully initialized. When disabled, no exception is thrown and a warning is logged (and the operation may potentially cause incorrect behavior or a crash).

enableStderrLog(enable: bool) -> None #

Enables or disables log message display on the standard console.

fullFocus() -> None #

Performs focus acquisition and lock for the one-shot focusing device.

getAPIVersionInfo() -> str #

Returns the module and device interface versions.

getAllowedPropertyValues(label: DeviceLabel | str, propName: PropertyName | str) -> Tuple[str, ...] #

Returns all valid values for the specified property.

getAutoFocusDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected auto-focus device.

Returns empty string if no auto-focus device is selected.

getAutoShutter() -> bool #

Returns the current setting of the auto-shutter option.

getAvailableConfigGroups() -> Tuple[ConfigGroupName, ...] #

Returns the names of all defined configuration groups

getAvailableConfigs(configGroup: ConfigGroupName | str) -> Tuple[ConfigPresetName, ...] #

Returns all defined configuration (preset) names in a given group

getAvailableDeviceDescriptions(library: AdapterName | str) -> Tuple[str, ...] #

Get descriptions for available devices from the specified library.

getAvailableDeviceTypes(library: AdapterName | str) -> Tuple[int, ...] #

Get type information for available devices from the specified library.

getAvailableDevices(library: AdapterName | str) -> Tuple[DeviceName, ...] #

Get available devices from the specified device library.

getAvailablePixelSizeConfigs() -> Tuple[PixelSizeConfigName, ...] #

Returns all defined resolution preset names

getBufferFreeCapacity() -> int #

Returns the number of images that can be added to the buffer without overflowing.

getBufferTotalCapacity() -> int #

Returns the total number of images that can be stored in the buffer

getBytesPerPixel() -> int #

How many bytes for each pixel.

getCameraChannelName(channelNr: int) -> str #

Returns the name of the requested channel as known by the default camera

getCameraDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected camera device.

Returns empty string if no camera device is selected.

getChannelGroup() -> ConfigGroupName | Literal[''] #

Returns the group determining the channel selection.

Returns empty string if no channel group is selected.

getCircularBufferMemoryFootprint() -> int #

Returns the size of the Circular Buffer in MB

getCoreErrorText(code: int) -> str #

Returns a pre-defined error test with the given error code

getCurrentConfig(groupName: ConfigGroupName | str) -> ConfigPresetName | Literal[''] #

Returns the current configuration (preset) for a given group.

Returns empty string if no configuration is selected.

getCurrentConfigFromCache(groupName: ConfigGroupName | str) -> ConfigPresetName | Literal[''] #

Returns the configuration for a given group based on the data in the cache.

getCurrentFocusScore() -> float #

Returns the focus score from the default focusing device measured at the current Z position.

getDeviceAdapterNames() -> Tuple[AdapterName, ...] #

Return the names of discoverable device adapters.

getDeviceAdapterSearchPaths() -> Tuple[str, ...] #

Return the current device adapter search paths.

getDeviceDelayMs(label: DeviceLabel | str) -> float #

Reports action delay in milliseconds for the specific device.

getDeviceDescription(label: DeviceLabel | str) -> str #

Returns description text for a given device label. "Description" is determined by the library and is immutable.

getDeviceLibrary(label: DeviceLabel | str) -> AdapterName #

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

getDeviceName(label: DeviceLabel | str) -> DeviceName #

Returns device name for a given device label.

getDevicePropertyNames(label: DeviceLabel | str) -> Tuple[PropertyName, ...] #

Returns all property names supported by the device.

getExposureSequenceMaxLength(cameraLabel: DeviceLabel | str) -> int #

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

getFocusDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected focus device.

Returns empty string if no focus device is selected.

getGalvoChannel(galvoLabel: DeviceLabel | str) -> str #

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

getGalvoDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected Galvo device.

Returns empty string if no Galvo device is selected.

getGalvoXMinimum(galvoLabel: DeviceLabel | str) -> float #

Get the Galvo x minimum

getGalvoXRange(galvoLabel: DeviceLabel | str) -> float #

Get the Galvo x range

getGalvoYMinimum(galvoLabel: DeviceLabel | str) -> float #

Get the Galvo y minimum

getGalvoYRange(galvoLabel: DeviceLabel | str) -> float #

Get the Galvo y range

getImageBitDepth() -> int #

How many bits of dynamic range are to be expected from the camera.

getImageBufferSize() -> int #

Returns the size of the internal image buffer.

getImageHeight() -> int #

Vertical dimension of the image buffer in pixels.

getImageProcessorDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected image processor device.

Returns empty string if no image processor device is selected.

getImageWidth() -> int #

Horizontal dimension of the image buffer in pixels.

getInstalledDeviceDescription(hubLabel: DeviceLabel | str, peripheralLabel: DeviceName | str) -> str #

Returns description from the specified peripheral on hubLabel device.

getInstalledDevices(hubLabel: DeviceLabel | str) -> Tuple[DeviceName, ...] #

Performs auto-detection and loading of child devices that are attached to a Hub device.

Raises RuntimeError if hubLabel is not a hub device.

getLastFocusScore() -> float #

Returns the latest focus score from the focusing device.

getLastImage() -> np.ndarray #

Gets the last image from the circular buffer.

getLoadedDevices() -> Tuple[DeviceLabel, ...] #

Returns an array of labels for currently loaded devices.

getLoadedDevicesOfType(devType: DeviceType) -> Tuple[DeviceLabel, ...] #

Returns an array of labels for currently loaded devices of specific type.

getLoadedPeripheralDevices(hubLabel: DeviceLabel | str) -> Tuple[DeviceLabel, ...] #

Return labels of all loaded peripherals of hubLabel device.

Returns empty tuple if hubLabel is not a hub device, or even if hubLabel is not the name of any device.

getMagnificationFactor() -> float #

Returns the product of all Magnifiers in the system or 1.0 when none is found. This is used internally by GetPixelSizeUm

getNBeforeLastImageMD(n: int, md: Metadata) -> np.ndarray #

Returns a pointer to the pixels of the image that was inserted n images ago. Also provides all metadata associated with that image

getNumberOfCameraChannels() -> int #

Returns the number of simultaneous channels the default camera is returning.

getNumberOfComponents() -> int #

Returns the number of components the default camera is returning.

getNumberOfStates(stateDeviceLabel: DeviceLabel | str) -> int #

Returns the total number of available positions (states).

getParentLabel(peripheralLabel: DeviceLabel | str) -> DeviceLabel | Literal[''] #

Returns parent device. Returns empty string if no parent is found.

getPixelSizeAffineByID(resolutionID: PixelSizeConfigName | str) -> AffineTuple #

Returns the Affine Transform to related camera pixels with stage movement for the requested pixel size group. The raw affine transform without correction for binning and magnification will be returned.

getPixelSizeUmByID(resolutionID: PixelSizeConfigName | str) -> float #

Returns the pixel size in um for the requested pixel size group

getPrimaryLogFile() -> str #

Return the name of the primary Core log file.

getProperty(label: DeviceLabel | str, propName: PropertyName | str) -> str #

Returns the property value for the specified device.

The return value will always be a string. Use getPropertyType to determine the correct type.

getPropertyFromCache(deviceLabel: DeviceLabel | str, propName: PropertyName | str) -> str #

Returns the cached property value for the specified device.

getPropertyLowerLimit(label: DeviceLabel | str, propName: PropertyName | str) -> float #

Returns the property lower limit value, if the property has limits - 0 otherwise.

getPropertySequenceMaxLength(label: DeviceLabel | str, propName: PropertyName | str) -> int #

Queries device property for the maximum number of events that can be put in a sequence

getPropertyUpperLimit(label: DeviceLabel | str, propName: PropertyName | str) -> float #

Returns the property upper limit value, if the property has limits - 0 otherwise.

getRemainingImageCount() -> int #

Returns number ofimages available in the Circular Buffer

getSLMBytesPerPixel(slmLabel: DeviceLabel | str) -> int #

Returns the number of bytes per SLM pixel

getSLMDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected SLM device.

Returns empty string if no SLM device is selected.

getSLMExposure(slmLabel: DeviceLabel | str) -> float #

Returns the exposure time that will be used by the SLM for illumination

getSLMHeight(slmLabel: DeviceLabel | str) -> int #

Returns the height (in "pixels") of the SLM

getSLMNumberOfComponents(slmLabel: DeviceLabel | str) -> int #

Returns the number of components (usually these depict colors) of the SLM.

For instance, an RGB projector will return 3, but a grey scale SLM returns 1

getSLMSequenceMaxLength(slmLabel: DeviceLabel | str) -> int #

For SLMs that support sequences, returns the maximum length of the sequence that can be uploaded to the device

getSLMWidth(slmLabel: DeviceLabel | str) -> int #

Returns the width (in "pixels") of the SLM

getSerialPortAnswer(portLabel: str, term: str) -> str #

Continuously read from the serial port until the terminating sequence is encountered.

getShutterDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected shutter device.

Returns empty string if no shutter device is selected.

getStageSequenceMaxLength(stageLabel: DeviceLabel | str) -> int #

Gets the maximum length of a stage's position sequence.

getState(stateDeviceLabel: DeviceLabel | str) -> int #

Returns the current state (position) on the specific device.

getStateFromLabel(stateDeviceLabel: DeviceLabel | str, stateLabel: StateLabel | str) -> int #

Obtain the state for a given label.

getStateLabel(stateDeviceLabel: DeviceLabel | str) -> StateLabel #

Returns the current state as the label (string).

getStateLabels(stateDeviceLabel: DeviceLabel | str) -> Tuple[StateLabel, ...] #

Return labels for all states

getTimeoutMs() -> int #

Get the timeout for all wait commands.

(Default is 5000 ms)

getVersionInfo() -> str #

Displays core version.

getXYStageDevice() -> DeviceLabel | Literal[''] #

Returns the label of the currently selected XYStage device.

Returns empty string if no XYStage device is selected.

getXYStageSequenceMaxLength(xyStageLabel: DeviceLabel | str) -> int #

Gets the maximum length of an XY stage's position sequence.

hasProperty(label: DeviceLabel | str, propName: PropertyName | str) -> bool #

Checks if device has a property with a specified name.

hasPropertyLimits(label: DeviceLabel | str, propName: PropertyName | str) -> bool #

Queries device if the specific property has limits.

home(xyOrZStageLabel: DeviceLabel | str) -> None #

Perform a hardware homing operation for an XY or focus/Z stage.

incrementalFocus() -> None #

Performs incremental focus for the one-shot focusing device.

initializeAllDevices() -> None #

Calls Initialize() method for each loaded device.

initializeCircularBuffer() -> None #

Initialize circular buffer based on the current camera settings.

initializeDevice(label: DeviceLabel | str) -> None #

Initializes specific device.

isBufferOverflowed() -> bool #

Indicates whether the circular buffer is overflowed

isConfigDefined(groupName: str, configName: str) -> bool #

Checks if the configuration already exists within a group.

If either the groupName or configName are not recognized, returns False.

isContinuousFocusDrive(stageLabel: DeviceLabel | str) -> bool #

Check if a stage has continuous focusing capability.

(positions can be set while continuous focus runs).

isContinuousFocusEnabled() -> bool #

Checks if the continuous focusing hardware device is ON or OFF.

isContinuousFocusLocked() -> bool #

Returns the lock-in status of the continuous focusing device.

isExposureSequenceable(cameraLabel: DeviceLabel | str) -> bool #

Queries camera if exposure can be used in a sequence

isFeatureEnabled(name: str) -> bool #

Return whether the given Core feature is currently enabled.

See enableFeature() for the available features.

Raises RuntimeError if the feature name is not recognized.

isGroupDefined(groupName: str) -> bool #

Checks if the group already exists.

isMultiROIEnabled() -> bool #

Queries the camera to determine if multiple ROIs are currently set.

isMultiROISupported() -> bool #

Queries the camera to determine if it supports multiple ROIs.

isPixelSizeConfigDefined(resolutionID: str) -> bool #

Checks if the Pixel Size Resolution already exists

isPropertyPreInit(label: DeviceLabel | str, propName: PropertyName | str) -> bool #

Tells us whether the property must be defined prior to initialization.

isPropertyReadOnly(label: DeviceLabel | str, propName: PropertyName | str) -> bool #

Tells us whether the property can be modified.

isPropertySequenceable(label: DeviceLabel | str, propName: PropertyName | str) -> bool #

Queries device if the specified property can be used in a sequence

isStageLinearSequenceable(stageLabel: DeviceLabel | str) -> bool #

Queries if the stage can be used in a linear sequence.

A linear sequence is defined by a stepsize and number of slices

isStageSequenceable(stageLabel: DeviceLabel | str) -> bool #

Queries stage if it can be used in a sequence

isXYStageSequenceable(xyStageLabel: DeviceLabel | str) -> bool #

Queries XY stage if it can be used in a sequence

loadExposureSequence(cameraLabel: DeviceLabel | str, exposureSequence_ms: Sequence[float]) -> None #

Transfer a sequence of exposure times to the camera.

loadGalvoPolygons(galvoLabel: DeviceLabel | str) -> None #

Load a set of galvo polygons to the device

loadPropertySequence(label: DeviceLabel | str, propName: PropertyName | str, eventSequence: Sequence[str]) -> None #

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

This should only be called for device-properties that are sequenceable

loadSLMSequence(slmLabel: DeviceLabel | str, imageSequence: List[bytes]) -> None #

Load a sequence of images into the SLM

loadStageSequence(stageLabel: DeviceLabel | str, positionSequence: Sequence[float]) -> None #

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

This should only be called for device-properties that are sequenceable

loadSystemState(fileName: str) -> None #

Loads the system configuration from the text file conforming to the MM specific format.

loadXYStageSequence(xyStageLabel: DeviceLabel | str, xSequence: Sequence[float], ySequence: Sequence[float]) -> None #

Transfer a sequence of stage positions to the xy stage.

xSequence and ySequence must have the same length. This should only be called for XY stages that are sequenceable

noop() -> None #

A static method that does nothing.

pointGalvoAndFire(galvoLabel: DeviceLabel | str, x: float, y: float, pulseTime_us: float) -> None #

Set the Galvo to an x,y position and fire the laser for a predetermined duration.

prepareSequenceAcquisition(cameraLabel: DeviceLabel | str) -> None #

Prepare the camera for the sequence acquisition to save the time in the

StartSequenceAcqusition() call which is supposed to come next.

readFromSerialPort(portLabel: str) -> List[str] #

Reads the contents of the Rx buffer.

registerCallback(cb: MMEventCallback) -> None #

Register a callback (listener class).

renameConfig(groupName: ConfigGroupName | str, oldConfigName: ConfigPresetName | str, newConfigName: str) -> None #

Renames a configuration within a specified group.

The command will fail if the configuration was not previously defined.

renameConfigGroup(oldGroupName: ConfigGroupName | str, newGroupName: str) -> None #

Renames a configuration group.

renamePixelSizeConfig(oldConfigName: PixelSizeConfigName | str, newConfigName: str) -> None #

Renames a pixel size configuration.

reset() -> None #

Unloads all devices from the core, clears all configuration data and property blocks.

runGalvoPolygons(galvoLabel: DeviceLabel | str) -> None #

Run a loop of galvo polygons

runGalvoSequence(galvoLabel: DeviceLabel | str) -> None #

Run a sequence of galvo positions

saveSystemState(fileName: str) -> None #

Saves the current system state to a text file of the MM specific format.

setAutoFocusDevice(focusLabel: DeviceLabel | str) -> None #

Sets the current auto-focus device.

setCameraDevice(cameraLabel: DeviceLabel | str) -> None #

Sets the current camera device.

setCircularBufferMemoryFootprint(sizeMB: int) -> None #

Reserve memory for the circular buffer.

setDeviceAdapterSearchPaths(paths: Sequence[str]) -> None #

Set the device adapter search paths.

setDeviceDelayMs(label: DeviceLabel | str, delayMs: float) -> None #

Overrides the built-in value for the action delay.

setFocusDirection(stageLabel: DeviceLabel | str, sign: int) -> None #

Set the focus direction of a stage.

setGalvoDevice(galvoLabel: DeviceLabel | str) -> None #

Sets the current galvo device.

setGalvoIlluminationState(galvoLabel: DeviceLabel | str, on: bool) -> None #

Set the galvo's illumination state to on or off

setGalvoPolygonRepetitions(galvoLabel: DeviceLabel | str, repetitions: int) -> None #

Set the number of times to loop galvo polygons

setGalvoPosition(galvoLabel: DeviceLabel | str, x: float, y: float) -> None #

Set the Galvo to an x,y position.

setGalvoSpotInterval(galvoLabel: DeviceLabel | str, pulseTime_us: float) -> None #

Set the SpotInterval for the specified galvo device.

setImageProcessorDevice(procLabel: DeviceLabel | str) -> None #

Sets the current image processor device.

setMultiROI(xs: Sequence[int], ys: Sequence[int], widths: Sequence[int], heights: Sequence[int]) -> None #

Set multiple ROIs for the current camera device.

Will fail if the camera does not support multiple ROIs, any widths or heights are non-positive, or if the vectors do not all have the same length.

setParentLabel(deviceLabel: DeviceLabel | str, parentHubLabel: DeviceLabel | str) -> None #

Sets parent device label

setPixelSizeAffine(resolutionID: PixelSizeConfigName | str, affine: Sequence[float]) -> None #

Sets the raw affine transform for the specific pixel size configuration.

The affine transform consists of the first two rows of a 3x3 matrix, the third row is alsways assumed to be 0.0 0.0 1.0.

setPixelSizeConfig(resolutionID: PixelSizeConfigName | str) -> None #

Applies a Pixel Size Configuration.

setSLMDevice(slmLabel: DeviceLabel | str) -> None #

Sets the current slm device.

setSLMExposure(slmLabel: DeviceLabel | str, exposure_ms: float) -> None #

For SLM devices with build-in light source (such as projectors), this will set the exposure time, but not (yet) start the illumination

setSerialPortCommand(portLabel: str, command: str, term: str) -> None #

Send string to the serial device and return an answer.

setSerialProperties(portName: str, answerTimeout: str, baudRate: str, delayBetweenCharsMs: str, handshaking: str, parity: str, stopBits: str) -> None #

Sets all com port properties in a single call.

setShutterDevice(shutterLabel: DeviceLabel | str) -> None #

the current shutter device.

setStageLinearSequence(stageLabel: DeviceLabel | str, dZ_um: float, nSlices: int) -> None #

Loads a linear sequence (defined by stepsize and nr. of steps) into the device.

setSystemState(conf: Configuration) -> None #

Sets all properties contained in the Configuration object.

setTimeoutMs(timeoutMs: int) -> None #

Sets the timeout for all wait commands.

(Default is 5000 ms)

setXYStageDevice(xyStageLabel: DeviceLabel | str) -> None #

Sets the current XY device.

sleep(intervalMs: float) -> None #

Waits (blocks the calling thread) for specified time in milliseconds.

startExposureSequence(cameraLabel: DeviceLabel | str) -> None #

Starts an ongoing sequence of triggered exposures in a camera.

This should only be called for cameras where exposure time is sequenceable

startPropertySequence(label: DeviceLabel | str, propName: PropertyName | str) -> None #

Starts an ongoing sequence of triggered events in a property of a device.

This should only be called for device-properties that are sequenceable

startSLMSequence(slmLabel: DeviceLabel | str) -> None #

Starts the sequence previously uploaded to the SLM

startStageSequence(stageLabel: DeviceLabel | str) -> None #

Starts an ongoing sequence of triggered events in a stage.

This should only be called for stages

startXYStageSequence(xyStageLabel: DeviceLabel | str) -> None #

Starts an ongoing sequence of triggered events in an XY stage.

This should only be called for stages

stderrLogEnabled() -> bool #

Indicates whether logging output goes to stdErr

stop(xyOrZStageLabel: DeviceLabel | str) -> None #

Stop the XY or focus/Z stage motors

stopExposureSequence(cameraLabel: DeviceLabel | str) -> None #

Stops an ongoing sequence of triggered exposures in a camera.

This should only be called for cameras where exposure time is sequenceable

stopPropertySequence(label: DeviceLabel | str, propName: PropertyName | str) -> None #

Stops an ongoing sequence of triggered events in a property of a device.

This should only be called for device-properties that are sequenceable

stopSLMSequence(slmLabel: DeviceLabel | str) -> None #

Stops the SLM sequence if previously started

stopSecondaryLogFile(handle: int) -> None #

Stop capturing logging output into an additional file.

stopStageSequence(stageLabel: DeviceLabel | str) -> None #

Stops an ongoing sequence of triggered events in a stage.

This should only be called for stages that are sequenceable

stopXYStageSequence(xyStageLabel: DeviceLabel | str) -> None #

Stops an ongoing sequence of triggered events in an XY stage.

This should only be called for stages that are sequenceable

supportsDeviceDetection(deviceLabel: DeviceLabel | str) -> bool #

Return whether or not the device supports automatic device detection (i.e.

systemBusy() -> bool #

Checks the busy status of the entire system.

unloadDevice(label: DeviceLabel | str) -> None #

Unloads the device from the core and adjusts all configuration data.

unloadLibrary(moduleName: AdapterName | str) -> None #

Forcefully unload a library.

updateCoreProperties() -> None #

Updates CoreProperties (currently all Core properties are devices types) with the loaded hardware.

updateSystemStateCache() -> None #

Updates the state of the entire hardware.

usesDeviceDelay(label: DeviceLabel | str) -> bool #

Signals if the device will use the delay setting or not.

waitForConfig(group: ConfigGroupName | str, configName: ConfigPresetName | str) -> None #

Blocks until all devices included in the configuration become ready.

waitForDevice(label: DeviceLabel | str) -> None #

Waits (blocks the calling thread) until the specified device becomes non-busy.

waitForDeviceType(devType: DeviceType) -> None #

Blocks until all devices of the specific type become ready (not-busy).

waitForSystem() -> None #

Blocks until all devices in the system become ready (not-busy).

writeToSerialPort(portLabel: str, data: bytes) -> None #

Sends an array of characters to the serial port and returns immediately.


TypedDicts#

pymmcore_plus.core._mmcore_plus.DeviceSchema #

JSON schema dict describing a device.

description: str class-attribute #

properties: dict[str, PropertySchema] class-attribute #

title: str class-attribute #

type: str class-attribute #

pymmcore_plus.core._mmcore_plus.PropertySchema #

JSON schema dict describing a device property.

default: Any class-attribute #

enum: list class-attribute #

maximum: float class-attribute #

minimum: float class-attribute #

preInit: bool class-attribute #

readOnly: bool class-attribute #

sequenceMaxLength: int class-attribute #

sequenceable: bool class-attribute #

type: str class-attribute #