Acquisition (AcqEngJ 0.34.2 API)

java.lang.Object
- org.micromanager.acqj.main.Acquisition

All Implemented Interfaces:

AcquisitionAPI

Direct Known Subclasses:

XYTiledAcquisition
```
public class Acquisition
extends Object
implements AcquisitionAPI
```
This is the main class for using AcqEngJ. AcquisitionAPI defines its public API. A full usage example can be found in example/FullExample.java

Field Summary

Fields
Modifier and Type	Field and Description
`protected CountDownLatch`	`abortRequested_`
`mmcorej.CMMCore`	`core_`
`protected AcqEngJDataSink`	`dataSink_`
`boolean`	`debugMode_`
`protected CountDownLatch`	`eventsFinished_`
`protected LinkedBlockingDeque<mmcorej.TaggedImage>`	`firstDequeue_`
`protected String`	`slm_`
`protected boolean`	`started_`
`protected mmcorej.org.json.JSONObject`	`summaryMetadata_`
`protected String`	`xyStage_`
`protected String`	`zStage_`

Fields inherited from interface org.micromanager.acqj.api.AcquisitionAPI
AFTER_CAMERA_HOOK, AFTER_EXPOSURE_HOOK, AFTER_HARDWARE_HOOK, BEFORE_HARDWARE_HOOK, EVENT_GENERATION_HOOK

Constructor Summary

Constructors
Constructor and Description
`Acquisition(AcqEngJDataSink sink)` Primary constructor for creating Acquisitons.
`Acquisition(AcqEngJDataSink sink, boolean initialize)` Version in which initialization can be handled by a subclass
`Acquisition(AcqEngJDataSink sink, Consumer<mmcorej.org.json.JSONObject> summaryMetadataProcessor)` Version of the constructor that accepts a function that can modify SummaryMetadata as needed

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`abort()` Cancel any pending events and shutdown
`void`	`abort(Exception e)` Auto abort caused by an exception during acquisition
`void`	`addAcqNotificationListener(AcqNotificationListener listener)` Add a AcqNotificationListener to receive asynchronous notifications about the acquisition
`void`	`addHook(AcquisitionHook h, int type)` Add a an arbitrary piece of code (i.e.
`void`	`addImageMetadataProcessor(Consumer<mmcorej.org.json.JSONObject> processor)` Add a Consumer that will receive the metadata JSONObject for each image that is generated and modify it as needed.
`void`	`addImageProcessor(TaggedImageProcessor p)` Add an image processor for modifying images before saving or diverting them to some other purpose
`void`	`addTagsToTaggedImage(mmcorej.org.json.JSONObject tags, HashMap<String,String> moreTags)` Add provided tags (Key-Value pairs of type String) to the Tagged Image tags.
`void`	`addToImageMetadata(mmcorej.org.json.JSONObject tags)`
`void`	`addToOutput(mmcorej.TaggedImage ti)`
`boolean`	`anythingAcquired()` Returns true once any data has been acquired
`boolean`	`areEventsFinished()` returns true if all acquisition events have been processed and hardware control is complete.
`void`	`blockUnlessAborted(long timeout_ms)`
`void`	`blockUntilEventsFinished(Double timeoutSeconds)` Blcok until all acquisitions events are finished or timeout is reached
`void`	`checkForExceptions()` Throws an exception if an exception occured on a thread managed by the acquisiton
`void`	`finish()` Signal the acquisition to complete once all events are done
`Iterable<AcquisitionHook>`	`getAfterCameraHooks()`
`Iterable<AcquisitionHook>`	`getAfterExposureHooks()`
`Iterable<AcquisitionHook>`	`getAfterHardwareHooks()`
`Iterable<AcquisitionHook>`	`getBeforeHardwareHooks()`
`AcqEngJDataSink`	`getDataSink()` Don't delete, called by python side
`Iterable<AcquisitionHook>`	`getEventGenerationHooks()`
`int`	`getImageTransferQueueCount()`
`int`	`getImageTransferQueueSize()`
`long`	`getStartTime_ms()`
`mmcorej.org.json.JSONObject`	`getSummaryMetadata()` Get the summary metadata for this acquisition
`protected void`	`initialize()` 1) Get the names of core devices to be used in acquisition.
`boolean`	`isAbortRequested()` Has abort been called?
`boolean`	`isDebugMode()` Should debug logging be printed
`boolean`	`isPaused()` return if acquisition is paused (i.e.
`boolean`	`isStarted()` return if acquisition is started by the first call to submitEventIterator
`void`	`postNotification(AcqNotification notification)`
`void`	`setDebugMode(boolean debug)` Don't delete, called by python side
`void`	`setPaused(boolean pause)` Pause or unpause
`void`	`setStartTime_ms(long time)`
`void`	`start()` Call to ready acquisition to start receiving acquisiton events.
`Future`	`submitEventIterator(Iterator<AcquisitionEvent> evt)` Submit a list of acquisition events for acquisition.
`void`	`waitForCompletion()` Block until acquisition finished and all resources complete.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - xyStage_
```
protected String xyStage_
```
  - zStage_
```
protected String zStage_
```
  - slm_
```
protected String slm_
```
  - eventsFinished_
```
protected volatile CountDownLatch eventsFinished_
```
  - abortRequested_
```
protected volatile CountDownLatch abortRequested_
```
  - summaryMetadata_
```
protected mmcorej.org.json.JSONObject summaryMetadata_
```
  - dataSink_
```
protected AcqEngJDataSink dataSink_
```
  - core_
```
public final mmcorej.CMMCore core_
```
  - firstDequeue_
```
protected LinkedBlockingDeque<mmcorej.TaggedImage> firstDequeue_
```
  - debugMode_
```
public boolean debugMode_
```
  - started_
```
protected volatile boolean started_
```
- Constructor Detail
  - Acquisition
```
public Acquisition(AcqEngJDataSink sink)
```
    Primary constructor for creating Acquisitons. If DataSink is null, then a TaggedImageProcessor that diverts the images to custom downstream processing must be implemented. After this constructor returns, the Acquisiton will be ready to be given instructions by calling submitEventIterator. However, if any acquisition hooks or image processors are desired, they should be added before the first call of submitEventIterator
  - Acquisition
```
public Acquisition(AcqEngJDataSink sink,
                   Consumer<mmcorej.org.json.JSONObject> summaryMetadataProcessor)
```
    Version of the constructor that accepts a function that can modify SummaryMetadata as needed
  - Acquisition
```
public Acquisition(AcqEngJDataSink sink,
                   boolean initialize)
```
    Version in which initialization can be handled by a subclass
- Method Detail
  - postNotification
```
public void postNotification(AcqNotification notification)
```
  - addAcqNotificationListener
```
public void addAcqNotificationListener(AcqNotificationListener listener)
```
    Description copied from interface: AcquisitionAPI
    
    Add a AcqNotificationListener to receive asynchronous notifications about the acquisition
    
    Specified by:
    
    addAcqNotificationListener in interface AcquisitionAPI
  - getDataSink
```
public AcqEngJDataSink getDataSink()
```
    Don't delete, called by python side
    
    Specified by:
    
    getDataSink in interface AcquisitionAPI
    
    Returns:
  - setDebugMode
```
public void setDebugMode(boolean debug)
```
    Don't delete, called by python side
    
    Specified by:
    
    setDebugMode in interface AcquisitionAPI
  - isDebugMode
```
public boolean isDebugMode()
```
    Description copied from interface: AcquisitionAPI
    
    Should debug logging be printed
    
    Specified by:
    
    isDebugMode in interface AcquisitionAPI
  - isAbortRequested
```
public boolean isAbortRequested()
```
    Description copied from interface: AcquisitionAPI
    
    Has abort been called?
    
    Specified by:
    
    isAbortRequested in interface AcquisitionAPI
  - abort
```
public void abort(Exception e)
```
    Auto abort caused by an exception during acquisition
    
    Specified by:
    
    abort in interface AcquisitionAPI
    
    Parameters:
    
    e -
  - checkForExceptions
```
public void checkForExceptions()
                        throws Exception
```
    Description copied from interface: AcquisitionAPI
    
    Throws an exception if an exception occured on a thread managed by the acquisiton
    
    Specified by:
    
    checkForExceptions in interface AcquisitionAPI
    
    Throws:
    
    Exception
  - abort
```
public void abort()
```
    Description copied from interface: AcquisitionAPI
    
    Cancel any pending events and shutdown
    
    Specified by:
    
    abort in interface AcquisitionAPI
  - addToImageMetadata
```
public void addToImageMetadata(mmcorej.org.json.JSONObject tags)
```
  - addTagsToTaggedImage
```
public void addTagsToTaggedImage(mmcorej.org.json.JSONObject tags,
                                 HashMap<String,String> moreTags)
                          throws mmcorej.org.json.JSONException
```
    Add provided tags (Key-Value pairs of type String) to the Tagged Image tags. These will appear as JSONObjects under the key: "Tags".
    
    Parameters:
    
    tags - Tagged Image tags
    
    moreTags - User-provided tags as Key-Value pairs
    
    Throws:
    
    mmcorej.org.json.JSONException
  - submitEventIterator
```
public Future submitEventIterator(Iterator<AcquisitionEvent> evt)
```
    Description copied from interface: AcquisitionAPI
    
    Submit a list of acquisition events for acquisition. Acquisition engine will automatically optimize over this list (i.e. implement hardware sequencing). If start() has not already been called on the acquisition, it will automatically be called here
    
    Specified by:
    
    submitEventIterator in interface AcquisitionAPI
  - addImageProcessor
```
public void addImageProcessor(TaggedImageProcessor p)
```
    Description copied from interface: AcquisitionAPI
    
    Add an image processor for modifying images before saving or diverting them to some other purpose
    
    Specified by:
    
    addImageProcessor in interface AcquisitionAPI
  - addHook
```
public void addHook(AcquisitionHook h,
                    int type)
```
    Description copied from interface: AcquisitionAPI
    
    Add a an arbitrary piece of code (i.e. a hook) to be executed at a specific time in the acquisition loop
    
    Specified by:
    
    addHook in interface AcquisitionAPI
    
    Parameters:
    
    h - Code to run
    
    type - BEFORE_HARDWARE_HOOK, AFTER_HARDWARE_HOOK, AFTER_SAVE_HOOK
  - waitForCompletion
```
public void waitForCompletion()
```
    Description copied from interface: AcquisitionAPI
    
    Block until acquisition finished and all resources complete.
    
    Specified by:
    
    waitForCompletion in interface AcquisitionAPI
  - initialize
```
protected void initialize()
```
    1) Get the names of core devices to be used in acquisition. 2) Create Summary metadata. 3) Initialize data sink.
  - start
```
public void start()
```
    Description copied from interface: AcquisitionAPI
    
    Call to ready acquisition to start receiving acquisiton events. No more hooks or image processors should be added after this has been called This method is no longer needed, because it is called automatically when the first call to submitEventIterator is made
    
    Specified by:
    
    start in interface AcquisitionAPI
  - getStartTime_ms
```
public long getStartTime_ms()
```
  - setStartTime_ms
```
public void setStartTime_ms(long time)
```
  - isPaused
```
public boolean isPaused()
```
    Description copied from interface: AcquisitionAPI
    
    return if acquisition is paused (i.e. not acquiring new data but not finished)
    
    Specified by:
    
    isPaused in interface AcquisitionAPI
    
    Returns:
  - isStarted
```
public boolean isStarted()
```
    Description copied from interface: AcquisitionAPI
    
    return if acquisition is started by the first call to submitEventIterator
    
    Specified by:
    
    isStarted in interface AcquisitionAPI
  - setPaused
```
public void setPaused(boolean pause)
```
    Description copied from interface: AcquisitionAPI
    
    Pause or unpause
    
    Specified by:
    
    setPaused in interface AcquisitionAPI
  - getSummaryMetadata
```
public mmcorej.org.json.JSONObject getSummaryMetadata()
```
    Description copied from interface: AcquisitionAPI
    
    Get the summary metadata for this acquisition
    
    Specified by:
    
    getSummaryMetadata in interface AcquisitionAPI
    
    Returns:
  - anythingAcquired
```
public boolean anythingAcquired()
```
    Description copied from interface: AcquisitionAPI
    
    Returns true once any data has been acquired
    
    Specified by:
    
    anythingAcquired in interface AcquisitionAPI
    
    Returns:
  - addImageMetadataProcessor
```
public void addImageMetadataProcessor(Consumer<mmcorej.org.json.JSONObject> processor)
```
    Description copied from interface: AcquisitionAPI
    
    Add a Consumer that will receive the metadata JSONObject for each image that is generated and modify it as needed. Metadata can also be modified through an ImageProcessor. This method is more lightweight--it should not be doing an significant computation, unlike Image Processors, which run // * /on their own dedicated Thread()
    
    Specified by:
    
    addImageMetadataProcessor in interface AcquisitionAPI
  - getEventGenerationHooks
```
public Iterable<AcquisitionHook> getEventGenerationHooks()
```
  - getBeforeHardwareHooks
```
public Iterable<AcquisitionHook> getBeforeHardwareHooks()
```
  - getAfterHardwareHooks
```
public Iterable<AcquisitionHook> getAfterHardwareHooks()
```
  - getAfterCameraHooks
```
public Iterable<AcquisitionHook> getAfterCameraHooks()
```
  - getAfterExposureHooks
```
public Iterable<AcquisitionHook> getAfterExposureHooks()
```
  - addToOutput
```
public void addToOutput(mmcorej.TaggedImage ti)
```
  - finish
```
public void finish()
```
    Description copied from interface: AcquisitionAPI
    
    Signal the acquisition to complete once all events are done
    
    Specified by:
    
    finish in interface AcquisitionAPI
  - areEventsFinished
```
public boolean areEventsFinished()
```
    Description copied from interface: AcquisitionAPI
    
    returns true if all acquisition events have been processed and hardware control is complete. This does not, however signal that all images are finished writing to disk (if DataSink is not null). This occurs after events are finished, and the DataSink should provide that information directly
    
    Specified by:
    
    areEventsFinished in interface AcquisitionAPI
    
    Returns:
  - blockUntilEventsFinished
```
public void blockUntilEventsFinished(Double timeoutSeconds)
                              throws InterruptedException
```
    Description copied from interface: AcquisitionAPI
    
    Blcok until all acquisitions events are finished or timeout is reached
    
    Specified by:
    
    blockUntilEventsFinished in interface AcquisitionAPI
    
    Throws:
    
    InterruptedException
  - getImageTransferQueueSize
```
public int getImageTransferQueueSize()
```
  - getImageTransferQueueCount
```
public int getImageTransferQueueCount()
```
  - blockUnlessAborted
```
public void blockUnlessAborted(long timeout_ms)
```

Class Acquisition

Field Summary

Fields inherited from interface org.micromanager.acqj.api.AcquisitionAPI

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

xyStage_

zStage_

slm_

eventsFinished_

abortRequested_

summaryMetadata_

dataSink_

core_

firstDequeue_

debugMode_

started_

Constructor Detail

Acquisition

Acquisition

Acquisition

Method Detail

postNotification

addAcqNotificationListener

getDataSink

setDebugMode

isDebugMode

isAbortRequested

abort

checkForExceptions

abort

addToImageMetadata

addTagsToTaggedImage

submitEventIterator

addImageProcessor

addHook

waitForCompletion

initialize

start

getStartTime_ms

setStartTime_ms

isPaused

isStarted

setPaused

getSummaryMetadata

anythingAcquired

addImageMetadataProcessor

getEventGenerationHooks

getBeforeHardwareHooks

getAfterHardwareHooks

getAfterCameraHooks

getAfterExposureHooks

addToOutput

finish

areEventsFinished

blockUntilEventsFinished

getImageTransferQueueSize

getImageTransferQueueCount

blockUnlessAborted