Edit page History How do I edit this website?

Version 2.0 API Transition Guide

One of the major changes in 2.0 is a restructuring of the API. In 1.4, most of the functionality of the API was in a single module, ScriptInterface. In 2.0, the API has been subdivided, and some methods have been replaced by new techniques for accomplishing similar tasks. This page runs down the list of methods in 1.4’s ScriptInterface and tells you how to perform the equivalent task in 2.0.

CompatibilityInterface, AcquisitionManager, Application, and PositionListManager

First, note that the CompatibilityInterface, AcquisitionManager, Application, and PositionListManager modules contain many old methods from ScriptInterface, unmodified. These methods work as they did in 1.4, and include the following:

You can access the CompatibilityInterface by calling the Studio’s () compat method, the AcquisitionManager by calling the Studio’s () acquisitions method, the Application by calling the Studio’s () app method, and the PositionListManager by calling the Studio’s () positions method. The Studio in turn is available in the BeanShell window as “mm”, and is provided to plugins when they are initialized.

acquisitionExists

In 1.4, Micro-Manager maintained a registry of all “open” datasets (a.k.a. acquisitions), using a unique string key for each one. In 2.0, such a registry no longer exists. Any code that creates a new Datastore (the 2.0 equivalent to a 1.4 acquisition) is responsible for holding onto references to it, destroying it, recreating it, etc.

It is theoretically possible to find Datastores by way of their DisplayWindows, the windows that show images from the Datastore. You can ask the DisplayManager for a list of all DisplayWindows, and ask each DisplayWindow for its Datastore using the getDatastore method. However, remember that Datastores are not required to have any DisplayWindows (and also that it is possible to have multiple DisplayWindows for a single Datastore). If you really need your code to find a Datastore created by someone else’s code, then you should find a better way for the two components to talk to each other.

addImageToAcquisition

In 2.0, third-party code is responsible for maintaining its own Datastores (the rough equivalent of 1.4 acquisitions), and can freely add images to Datastores themselves using the putImage method.

addMMBackgroundListener

This method was used as part of 1.4’s day/night system for enabling low-contrast displays for use in darkrooms. 2.0 uses a different system that works automatically across the entire program; there is no need for individual components to register themselves. Thus this method is obsolete.

addMMListener / removeMMListener

These methods allowed code to listener for code event callbacks by implementing the MMListener interface, which is no longer in the API in 2.0. Instead, you can listen for events that correspond to each of the callbacks (for example, PropertyChangedEvent instead of the old propertyChangedAlert method), by using 2.0’s event publishing system. Remember to annotate the method that listens to the event, with a Subscribe annotation, and to register your object for event notifications via the EventManager accessible via () Studio.events().

addToAlbum

The “album” Datastore is now available via the Studio’s () album method, and you can freely add images to it yourself (see the addImageToAcquisition notes above)

autostretchCurrentWindow

You can now autostretch individual DisplayWindows using their autostretch method. Thus this method can be replaced by calling displays().getCurrentWindow().autostretch().

clearMessageWindow

This method was moved to the ScriptController object accessible via the Studio’s () scripter method.

closeAcquisition

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains responsibility for all open datasets. If you want to clean up a Datastore, you must remove all references to that Datastore from memory. Micro-Manager will not maintain open references itself except via any DisplayWindows you may have requested be created. You can close all open DisplayWindows for a given Datastore via the DisplayManager’s closeDisplaysFor method.

closeAcquisitionWindow

See the notes on closeAcquisition, above.

closeAllAcquisitions

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains a listing of all “acquisitions”. Third-party code can freely create new Datastores and Micro-Manager will not be able to “see” them. Thus this method is impossible to implement in 2.0.

However, if you just want to clean up the UI, then the DisplayManager has a closeAllDisplayWindows method.

createAcquisition

You can request your own new Datastores (the rough equivalent of 1.4 acquisition objects) via the DataManager’s various “createDatastore” methods (e.g. () createRAMDatastore, createMultipageTIFFDatastore, and createSinglePlaneTIFFSeriesDatastore).

displayImage

This has been replaced by DisplayManager’s show method. Note that this method creates a new Datastore to store the image in. The old behavior of showing images in the Snap/Live Window is no longer possible.

enableLiveMode

This has been replaced by SnapLiveManager’s setLiveMode method. You should also be aware of the setSuspended method if you need to briefly stop live mode, only to resume it later.

enableRoiButtons

This method was removed because it is unused by all known third-party code.

getAcqDlg

This method was deprecated in 1.4, and has been removed in 2.0.

getAcquisition

This method was deprecated in 1.4 and has been removed in 2.0.

getAcquisitionPath

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

You can access the save path for a Datastore via its () getSavePath method.

getAcquisitionImageBitDepth

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Image bit depth is now a property of the Image objects in the Datastore, and is theoretically not required to be the same for all Images in that Datastore (though in practice we do not expect varying bit depths to work right now). You can get the bit depth for an Image by asking for its Metadata (via the () getMetadata method) and then calling the Metadata’s () getBitDepth method.

If you need to get a single image out of a Datastore, you can call its () getAnyImage method.

getAcquisitionImageByteDepth

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Image byte depth is now a property of the Image objects in the Datastore, and is theoretically not required to be the same for all Images in that Datastore (though in practice we do not expect varying byte depths to work right now). You can get the byte depth for a single image by calling its () getBytesPerPixel method.

If you need to get a single image out of a Datastore, you can call its () getAnyImage method.

getAcquisitionImageCache

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

The Datastore functions as the equivalent of 1.4’s image cache. You can ask it for images using its getImage method.

getAcquisitionImageHeight

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Image height is now a property of the Image objects in the Datastore, and is theoretically not required to be the same for all Images in that Datastore (though in practice we do not expect varying image heights to work right now). You can get the height for a single image by calling its () getHeight method.

If you need to get a single image out of a Datastore, you can call its () getAnyImage method.

getAcquisitionImageWidth

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Image width is now a property of the Image objects in the Datastore, and is theoretically not required to be the same for all Images in that Datastore (though in practice we do not expect varying image widths to work right now). You can get the width for a single image by calling its () getWidth method.

If you need to get a single image out of a Datastore, you can call its () getAnyImage method.

getAcquisitionMultiCamNumChannels

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

In 2.0 this method is not available. You may try to replicate it by comparing the number of channels in the Datastore (via its getAxisLength method) to the number of unique cameras declared by the Metadatas of the various images (see () Metadata.getCamera). You can iterate over all images in the Datastore via the () getUnorderedImageCoords method combined with the getImage method.

getAcquisitionPath

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

The path of a Datastore’s saved location on disk is accessible via its () getSavePath method.

getAutofocus

Use AutofocusManager.getAutofocusMethod instead.

getAutofocusManager

Use Studio.getAutofocusManager instead.

getBackgroundColor

As discussed in the notes for addMMBackgroundListener, background color selection is now handled automatically. Thus this method is no longer needed. However, if you need to manually set colors for the few edge cases where colors are not handled automatically, you should investigate the ApplicationSkin module.

getBackgroundStyle

This method was replaced by the ApplicationSkin.getSkin method.

getCacheForWindow

This has been replaced by the DisplayWindow’s () getDatastore method.

getCurrentAlbum

The Album Datastore can be accessed via the Studio’s () album method.

getMMCore

The Micro-Manager Core object can be accessed via the Studio’s () core method.

getROI

Use the Core’s () getROI method.

getSnapLiveWin

This has been replaced by the SnapLiveManager’s () getDisplay method. You can access the SnapLiveManager via the Studio’s () live method.

Please note that the snap/live display is prone to being destroyed and recreated. It is not recommended that you keep references to the snap/live window in memory; request it anew each time you need it.

getUniqueAcquisitionName

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Consequently, there is no need to generate unique acquisition names.

getXYPosListDlg

This method was deprecated in 1.4 and has been removed in 2.0

getXYStageName

This information can be accessed via the Core’s () getXYStageDevice method. The Core in turn can be accessed via the Studio’s () core method.

initializeAcquisition

The metadata set by this method is now handled automatically when images are saved; consequently, it is no longer needed.

installAutofocusPlugin

AutofocusPlugins should now be compiled and annotated with the @Plugin annotation (as described in MMPlugin). If this is done and the resulting jar file is included in the mmautofocus directory of your ImageJ installation, then the plugin will automatically be detected at runtime. There is no mechanism for loading a plugin after µManager’s initialization has completed.

isLiveModeOn

This method has been replaced by the SnapLiveManager’s isLiveModeOn method. The SnapLiveManager in turn can be accessed via Studio’s live method.

Note that if you just want to temporarily suspend live mode, to resume it later, then you can make use of the SnapLiveManager’s setSuspended method.

logError

Replaced by the LogManager’s logError method (and similarly for the variants on this method). The LogManager can be accessed via the Studio’s () logs method.

logMessage

As with logError, replaced by the LogManager’s logMessage method.

logStartupProperties

This method was removed as it is unused by all known third-party code.

message

Replaced by the ScriptController’s message method. The ScriptController in turn can be accessed via the Studio’s () scripter method.

openAcquisition

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

You can request new Datastores via the DataManager’s various “createDatastore” methods (e.g. () createRAMDatastore, createMultipageTIFFDatastore, and createSinglePlaneTIFFSeriesDatastore). If you use a file-backed Datastore, then images will automatically be saved to disk as you add them to the Datastore, though you should make certain to call the Datastore’s () freeze method when you are done to ensure that saving completes successfully.

If you wish to view the images in the Datastore, use the DisplayManager’s createDisplay method. The DisplayManager in turn can be accessed via the Studio’s () displays method.

In any case, there is no need to specify the dimensionality of the dataset ahead of time as was the case with openAcquisition

openAcquisitionData

Replaced by DataManager’s loadData method. The DataManager in turn can be accessed via the Studio’s () data method.

promptToSaveAcquisition

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Replaced by the Datastore’s save method.

registerForEvents

Moved to the EventManager, which can be accessed via the Studio’s () events method.

removeMMBackgroundListener

As discussed in addMMBackgroundListener above, day/night changes now happen automatically, so this method is obsolete.

saveConfigPresets

While this method still exists (as part of the Application module), it now two parameters: a path string to save the config to, and a boolean for whether to allow overwriting of existing files. The old functionality that displayed a save dialog has been removed.

setAcquisitionAddImageAsynchronous

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

As you now have complete control over adding images to your Datastores, it is up to you to implement asynchronous image-adding if you need it.

setAcquisitionProperty

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Arbitrary metadata storage is available for both SummaryMetadata and individual image Metadata via their respective userData fields.

setBackgroundStyle

This method was replaced by the ApplicationSkin.setSkin method.

setChannelColor

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in. Likewise, you are responsible for keeping track of any associated DisplayWindows open for a given Datastore. However, for managed Datastores, you can request all open DisplayWindows via the DisplayManager’s getDisplays method.

Channel color is a property of the DisplaySettings for a given DisplayWindow. You can create a new DisplaySettings with adjusted channel colors (e.g. by using the () copy method), and then cause a DisplayWindow to use the new channel color via its setDisplaySettings method.

The above logic relies on you understanding the use of Builder patterns. See Using_Builders for more information.

setChannelContrast

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in. Likewise, you are responsible for keeping track of any associated DisplayWindows open for a given Datastore. However, for managed Datastores, you can request all open DisplayWindows via the DisplayManager’s getDisplays method.

Channel contrast settings are properties of the DisplaySettings for a given DisplayWindow. You can create a new DisplaySettings with adjusted contrast (e.g. by using the () copy method), and then cause a DisplayWindow to use the new channel color via its setDisplaySettings method.

The above logic relies on you understanding the use of Builder patterns. See Using_Builders for more information.

setChannelName

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Channel names are a property of the SummaryMetadata associated with a given Datastore. You can access the SummaryMetadata using the Datastore’s () getSummaryMetadata method, make a copy with the () copy method, adjust the channel names to suit, and then cause the Datastore to use the new summary metadata using the setSummaryMetadata method.

The above logic relies on you understanding the use of Builder patterns. See Using_Builders for more information.

setContrastBasedOnFrame

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in. Likewise, you are responsible for keeping track of any associated DisplayWindows open for a given Datastore. However, for managed Datastores, you can request all open DisplayWindows via the DisplayManager’s getDisplays method.

This method is not available in 2.0. However, you can replicate its functionality for a given DisplayWindow by combining the SetDisplayedImageTo method of DisplayWindow and the shouldAutostretch field of the DisplaySettings.

setConfigChanged

This method was removed as it is unused by all known third-party code.

setImageProperty

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

Arbitrary metadata storage is available for both SummaryMetadata and individual image Metadata via their respective userData fields.

setImageSavingFormat

When saving the contents of a Datastore, you must specify the format you want to use in the form of a Datastore.SaveMode. Alternately, if you want to show the user a save-file dialog, then that dialog will include a file format dropdown menu that they can use to decide which format to use. The dropdown menu (and the MDA dialog’s save-files section) will automatically default to the format the user last used to save files.

setRelativeStagePosition

This functionality be accessed via the Core’s () setRelativePosition method. The Core in turn can be accessed via the Studio’s () core method.

setRelativeXYStagePosition

This functionality can be accessed via the Core’s () setRelativeXYPosition method. The Core in turn can be accessed via the Studio’s () core method.

setStagePosition

This functionality can be accessed via the Core’s () setPosition method. The Core in turn can be accessed via the Studio’s () core method.

setXYOrigin

This functionality can be accessed via the Core’s () setOriginXY method. The Core in turn can be accessed via the Studio’s () core method.

setXYStagePosition

This functionality can be accessed via the Core’s () setXYPosition method. The Core in turn can be accessed via the Studio’s () core method.

showError

Moved to the LogManager object, which can be accessed via the Studio’s logs method.

showMessage

Moved to the LogManager object, which can be accessed via the Studio’s logs method.

showXYPositionList

For consistency, this method was renamed to () showPositionList in PositionListManager.

sleep

This method has been removed. Use Thread.sleep instead.

snapAndAddImage

As discussed in the notes on acquisitionExists, above, Micro-Manager no longer maintains records on any acquisition objects; you are responsible for maintaining your own references to the Datastore that your data is in.

You can replicate the functionality of this method through a combination of the SnapLiveManager’s snap method and the Datastore’s putImage method. The SnapLiveManager can be accessed from the Studio’s () live method.

snapSingleImage

Replaced by the SnapLiveManager’s snap method.

unregisterForEvents

Moved to the EventManager object, which can be accessed via the Studio’s () events method.