Coming from Micro-Manager¶

If you've used Micro-Manager's Java application (MMStudio), much of what you know carries over. pymmcore-plus uses the same C++ core (MMCore) and the same device adapters as MMStudio, and it reads the same configuration files. What's different is everything above the core. In place of MMStudio's Java GUI and acquisition engine, you get a Python object (CMMCorePlus), an acquisition engine written in Python, and (if you want a GUI) widgets and applications written in Python.

One program at a time¶

pymmcore-plus doesn't connect to a running copy of Micro-Manager; it replaces it. Each program loads its own copy of the core, and the core opens your devices itself (serial ports, camera drivers, etc...). Most devices can only be opened by one program at a time, so if MMStudio has your configuration loaded, loading it again from Python will usually fail (and if it doesn't, the two programs will be fighting over the same hardware). So please close MMStudio before you load your configuration in Python, and vice versa. (The demo devices don't mind, so it's fine to have both open while you're trying things out.)

If you want to keep using the classic Java-based MMStudio application and control it from Python at the same time, that's what Pycro-Manager is for (see below).

Where things went¶

If you'd rather have all of this in one window, pymmcore-gui is our (work in progress) pure-Python replacement for MMStudio.

Scripts¶

CMMCorePlus has the same methods as the core object (mmc) in MMStudio's script panel, so Beanshell scripts translate to Python almost line by line:

mmc.setConfig("Channel", "FITC");
mmc.setExposure(50);
mmc.snapImage();
img = mmc.getImage();

from pymmcore_plus import CMMCorePlus

mmc = CMMCorePlus.instance()
mmc.loadSystemConfiguration()  # (1)!
mmc.setConfig("Channel", "FITC")
mmc.setExposure(50)
mmc.snapImage()
img = mmc.getImage()  # a numpy array

A few things are different: images come back as numpy arrays (rather than Java arrays), lists of strings come back as Python tuples (rather than StrVectors), and CMMCorePlus adds a number of conveniences on top (like snap(), which does the last two lines in one go). The mm object (MMStudio's own API for displays, data stores, the acquisition manager, etc...) is part of the Java GUI, so it has no equivalent here.

If you're working inside one of our applications, the core is already there for you. In pymmcore-gui's console it's called mmc (just like in MMStudio), and in napari-micromanager's console it's mmcore.

How is this different from Pycro-Manager?¶

A common question about pymmcore-plus and related libraries is how they differ from Pycro-Manager, another Python library written by Henry Pinkard for working with Micro-Manager.

The two projects are not mutually exclusive! They aim to support different use cases.

The primary difference is that Pycro-Manager (with its default Java backend) controls Micro-Manager via a ZMQ-based connection to a remote Java process in which the Micro-Manager GUI is running (or a headless Java process if the GUI is not running). The Java process in turn communicates with the C++ core driving the hardware.

pymmcore-plus aims to remove the need for a Java process by communicating directly with the C++ core (via the pymmcore library), and re-implementing any necessary event-based or GUI-based functionality in pure Python or C.

The advantage of Pycro-Manager is that you get the entire Java-based Micro-Manager ecosystem, including the well-established GUI and plugins. A potential disadvantage (depending on your needs) is that it requires a Java runtime environment and cross-process communication, which adds complexity and has performance implications.

pymmcore-plus was designed to let you control a microscope via Python without any need for Java or interprocess communication. Note, however, that you will be sacrificing the MMStudio GUI! See pymmcore-gui, napari-micromanager and pymmcore-widgets for our ongoing efforts to implement a complete Python-based GUI for Micro-Manager.