org.micromanager.acquisition

Interface AcquisitionManager

public interface AcquisitionManager

This interface provides access to methods related to the acquisition engine for performing experiments. You can access it using Studio.acquisitions() or Studio.getAcquisitionManager().

Method Summary

Modifier and Type	Method and Description
void	abortAcquisition() Abort any ongoing acquisition as soon as possible, without user dialog.
void	attachRunnable(int frame, int position, int channel, int slice, java.lang.Runnable runnable) Attach a runnable to the acquisition engine.
ChannelSpec.Builder	channelSpecBuilder() Provides and empty ChannelSpec Builder.
void	clearRunnables() Remove runnables from the acquisition engine.
Metadata	generateMetadata(Image image, boolean includeHardwareState) Generate a new Metadata that contains pre-populated fields based on the current state of the program and the provided Image.
SummaryMetadata	generateSummaryMetadata() Generate a new SummaryMetadata that contains pre-populated fields based on the current state of the program.
SequenceSettings	getAcquisitionSettings() Return current acquisition settings as shown in the Multi-D Acquisition dialog.
void	haltAcquisition() Halt any ongoing acquisition as soon as possible, prompting users with a dialog for confirmation.
boolean	isAcquisitionRunning() Returns true when an acquisition is currently running (note: this function will not return true if live mode, snap, or "Camera --> Album" is currently running.
boolean	isOurAcquisition(java.lang.Object source) Test the provided Object, and return true if it corresponds to the "source" object that Micro-Manager's acquisition system uses when publishing AcquisitionStartedEvent and AcquisitionEndedEvent.
boolean	isPaused() Returns true if the acquisition is currently paused.
void	loadAcquisition(java.lang.String path) Load a file containing a SequenceSettings object, and apply the settings found in it to the Multi-D Acquisition (MDA) dialog.
SequenceSettings	loadSequenceSettings(java.lang.String path) Load a SequenceSettings file and return the SequenceSettings object.
Datastore	runAcquisition() Executes Acquisition with settings as in the MDA dialog.
Datastore	runAcquisition(java.lang.String name, java.lang.String root) Executes Acquisition with current settings but allows for changing the data path.
Datastore	runAcquisitionNonblocking() As runAcquisition, but will return as soon as the acquisition is set up and started; useful for code that wants access to the Datastore for the acquisition before it finishes.
Datastore	runAcquisitionWithSettings(SequenceSettings settings, boolean shouldBlock) Execute an acquisition using the provided SequenceSettings.
void	saveSequenceSettings(SequenceSettings settings, java.lang.String path) Save the provided SequenceSettings object to disk at the specified path.
SequenceSettings.Builder	sequenceSettingsBuilder() Provides an empty Sequence Settings Builder.
void	setAcquisitionSettings(SequenceSettings settings) Apply new acquisition settings.
void	setPause(boolean state) Pause/Unpause a running acquisition.
java.util.List<Image>	snap() Snap images using the current camera(s) and return them.

Method Detail

sequenceSettingsBuilder

SequenceSettings.Builder sequenceSettingsBuilder()

Provides an empty Sequence Settings Builder.

channelSpecBuilder

ChannelSpec.Builder channelSpecBuilder()

Provides and empty ChannelSpec Builder.

runAcquisition

Datastore runAcquisition()
                  throws java.lang.IllegalThreadStateException

Executes Acquisition with settings as in the MDA dialog. Will open the Acquisition Dialog if it is not open yet. Returns after Acquisition finishes and the data processing pipeline has finished processing all images. Note that this function should not be executed on the EDT (which is the thread running the UI).

Returns:

The Datastore containing the images from the acquisition.

Throws:

java.lang.IllegalThreadStateException - if the acquisition is started on the EDT

runAcquisition

Datastore runAcquisition(java.lang.String name,
                         java.lang.String root)
                  throws java.lang.IllegalThreadStateException

Executes Acquisition with current settings but allows for changing the data path. Will open the Acquisition Dialog when it is not open yet. Returns after Acquisition finishes. Note that this function should not be executed on the EDT (which is the thread running the UI).

Parameters:

name - Name of this acquisition.

root - Place in the file system where data can be stored.

Returns:

The Datastore containing the images from the acquisition.

Throws:

java.lang.IllegalThreadStateException - if the acquisition is started on the EDT.

runAcquisitionNonblocking

Datastore runAcquisitionNonblocking()
                             throws java.lang.IllegalThreadStateException

As runAcquisition, but will return as soon as the acquisition is set up and started; useful for code that wants access to the Datastore for the acquisition before it finishes.

Returns:

The Datastore containing the images from the acquisition.

Throws:

java.lang.IllegalThreadStateException - if the acquisition is started on the EDT

runAcquisitionWithSettings

Datastore runAcquisitionWithSettings(SequenceSettings settings,
                                     boolean shouldBlock)
                              throws java.lang.IllegalThreadStateException

Execute an acquisition using the provided SequenceSettings. This function should not be called on the EDT.

Parameters:

settings - SequenceSettings to use for the acquisition, or null to use the settings in the MDA dialog.

shouldBlock - if true, the method will block until the acquisition is completed.

Returns:

The Datastore containing the images from the acquisition.

Throws:

java.lang.IllegalThreadStateException - if the acquisition is started on the EDT.

haltAcquisition

void haltAcquisition()

Halt any ongoing acquisition as soon as possible, prompting users with a dialog for confirmation.

abortAcquisition

void abortAcquisition()

Abort any ongoing acquisition as soon as possible, without user dialog.

loadAcquisition

void loadAcquisition(java.lang.String path)
              throws java.io.IOException

Load a file containing a SequenceSettings object, and apply the settings found in it to the Multi-D Acquisition (MDA) dialog. Will open the dialog if it is not currently open.

Parameters:

path - File path to the SequenceSettings object.

Throws:

java.io.IOException - if the sequence settings cannot be loaded.

loadSequenceSettings

SequenceSettings loadSequenceSettings(java.lang.String path)
                               throws java.io.IOException

Load a SequenceSettings file and return the SequenceSettings object. The settings will *not* be applied to the Multi-D Acquisition dialog.

Parameters:

path - File path to the SequenceSettings object.

Throws:

java.io.IOException - if there was an error reading the file.

saveSequenceSettings

void saveSequenceSettings(SequenceSettings settings,
                          java.lang.String path)
                   throws java.io.IOException

Save the provided SequenceSettings object to disk at the specified path.

Parameters:

settings - SequenceSettings object to save.

path - Path to save the SequenceSettings to.

Throws:

java.io.IOException - if there was an error writing the file to disk.

isAcquisitionRunning

boolean isAcquisitionRunning()

Returns true when an acquisition is currently running (note: this function will not return true if live mode, snap, or "Camera --> Album" is currently running.

Returns:

true when an acquisition is currently running

setPause

void setPause(boolean state)

Pause/Unpause a running acquisition.

Parameters:

state - true if paused, false if no longer paused

isPaused

boolean isPaused()

Returns true if the acquisition is currently paused.

Returns:

true if paused, false if not paused

attachRunnable

void attachRunnable(int frame,
                    int position,
                    int channel,
                    int slice,
                    java.lang.Runnable runnable)

Attach a runnable to the acquisition engine. Each index (f, p, c, s) can be specified. Passing a value of -1 should result in the runnable being attached at all values of that index. For example, if the first argument is -1, then the runnable should execute at every frame.

Parameters:

frame - 0-based frame number

position - 0-based position number

channel - 0-based channel number

slice - 0-based (z) slice number

runnable - code to be run

clearRunnables

void clearRunnables()

Remove runnables from the acquisition engine.

getAcquisitionSettings

SequenceSettings getAcquisitionSettings()

Return current acquisition settings as shown in the Multi-D Acquisition dialog.

Returns:

acquisition settings instance

setAcquisitionSettings

void setAcquisitionSettings(SequenceSettings settings)

Apply new acquisition settings.

Parameters:

settings - acquisition settings

snap

java.util.List<Image> snap()
                    throws java.lang.Exception

Snap images using the current camera(s) and return them. See also SnapLiveManager.snap(), which can be safely called when live mode is on, and may optionally display images in the Snap/Live View.

Returns:

A list of images acquired by the snap.

Throws:

java.lang.Exception - If there is an error when communicating with the Core (for example, because Live mode is on), or if the current hardware configuration contains no cameras.

generateSummaryMetadata

SummaryMetadata generateSummaryMetadata()

Generate a new SummaryMetadata that contains pre-populated fields based on the current state of the program. The following fields will be set: userName, profileName, microManagerVersion, metadataVersion, computerName.

Returns:

A pre-populated SummaryMetadata.

generateMetadata

Metadata generateMetadata(Image image,
                          boolean includeHardwareState)
                   throws java.lang.Exception

Generate a new Metadata that contains pre-populated fields based on the current state of the program and the provided Image. The Image's Metadata will be used as a base, with the following fields overwritten based on the image properties and current hardware state, if possible: binning, bitDepth, camera, pixelType, receivedTime (to the current time), uuid, xPositionUm, yPositionUm, zPositionUm. Note that stage positions are based on cached values, and may be inaccurate if the cache has not been refreshed since the last time the stage moved.

Additionally, if the includeHardwareState boolean is set to true, then the current state of the system state cache (i.e. Micro-Manager's understanding of all device property values) will be included in the scopeData property. As with the stage positions, these values do not necessarily reflect reality; they are just the last-known values in the cache.

Parameters:

image - Image whose metadata should be populated.

includeHardwareState - if true, then the scopeData field will be populated in the result Metadata.

Returns:

A pre-populated Metadata.

Throws:

java.lang.Exception - If there were any errors communicating with the Core to get required values.

isOurAcquisition

boolean isOurAcquisition(java.lang.Object source)

Test the provided Object, and return true if it corresponds to the "source" object that Micro-Manager's acquisition system uses when publishing AcquisitionStartedEvent and AcquisitionEndedEvent. In other words, you can use this method to determine if an acquisition originated from Micro-Manager.

Parameters:

source - Result of calling getSource() on an AcquisitionStartedEvent or AcquisitionEndedEvent.

Returns:

true if acquisition was started by Micro-Manager, false if it was started elsewhere (e.g. by a plugin or other third-party code).