pymmcore-plus 0.13.3

pymmcore superset providing improved APIs, event handling, and a pure python acquisition engine

pymmcore-plus

pymmcore-plus extends pymmcore (python bindings for the C++ micro-manager core) with a number of features designed to facilitate working with Micro-manager in pure python/C environments.

• pymmcore_plus.CMMCorePlus is a drop-in replacement subclass of pymmcore.CMMCore that provides a number of helpful overrides and additional convenience functions beyond the standard CMMCore API. See CMMCorePlus documentation for details.
• pymmcore-plus includes an acquisition engine that drives micro-manager for conventional multi-dimensional experiments. It accepts an MDASequence from useq-schema for experiment design/declaration.
• Adds a callback system that adapts the CMMCore callback object to an existing python event loop (such as Qt, or perhaps asyncio/etc...). The CMMCorePlus class also fixes a number of "missed" events that are not currently emitted by the CMMCore API.

Documentation

https://pymmcore-plus.github.io/pymmcore-plus/

Why not just use pymmcore directly?

pymmcore is (and should probably remain) a thin SWIG wrapper for the C++ code at the core of the Micro-Manager project. It is sufficient to control micromanager via python, but lacks some "niceties" that python users are accustomed to. This library:

• extends the pymmcore.CMMCore object with additional methods
• fixes emission of a number of events in MMCore.
• provide proper python interfaces for various objects like Configuration and Metadata.
• provides an object-oriented API for Devices and their properties.
• uses more interpretable Enums rather than int for various constants
• improves docstrings and type annotations.
• generally feel more pythonic (note however, camelCase method names from the CMMCore API are not substituted with snake_case).

How does this relate to Pycro-Manager?

Pycro-Manager is an impressive library written by Henry Pinkard designed to make it easier to work with and control the Java Micro-manager application using python. As such, it requires Java to be installed and running in the background (either via the micro-manager GUI application directly, or via a headless process). The python half communicates with the Java half using ZeroMQ messaging.

In brief: while Pycro-Manager provides a python API to control the Java Micro-manager application (which in turn controls the C++ core), pymmcore-plus provides a python API to control the C++ core directly, without the need for Java in the loop. Each has its own advantages and disadvantages! With pycro-manager you immediately get the entire existing micro-manager ecosystem and GUI application. With pymmcore-plus you don't need to install Java, and you have direct access to the memory buffers used by the C++ core.

Quickstart

Install

from pip

pip install pymmcore-plus

# or, add the [cli] extra if you wish to use the `mmcore` command line tool:
pip install "pymmcore-plus[cli]"

# add the [io] extra if you wish to use the tiff or zarr writers
pip install "pymmcore-plus[io]"

from conda

conda install -c conda-forge pymmcore-plus

dev version from github

pip install 'pymmcore-plus[cli] @ git+https://github.com/pymmcore-plus/pymmcore-plus'

Usually, you'll then want to install the device adapters. Assuming you've installed with pip install "pymmcore-plus[cli]", you can run:

mmcore install

(you can also download these manually from micro-manager.org)

See installation documentation for more details.

Usage

Then use the core object as you would pymmcore.CMMCore... but with more features :smile:

from pymmcore_plus import CMMCorePlus

core = CMMCorePlus()
...

Examples

See a number of usage examples in the documentation.

You can find some basic python scripts in the examples directory of this repository

Contributing

Contributions are welcome! See contributing guide.