micro-manager/acqengj

Java-based acquisition engine for Micro-manager

Micro-Manager

Micro-Manager is an application to control microscope hardware, such as cameras, xy-stages, filter wheels, etc. It includes a hardware abstraction layer written in C++ and a user interface written in Java (Swing).

Go to micro-manager.org for documentation and binary downloads.

For support, see Micro-Manager Community.

The Micro-Manager community welcomes you! For our governance structures, go here

Source code

This repository contains the Java projects that make up the Micro-Manager "MMStudio" GUI application. The device control layer is written in C++ and found in a separate repository, mmCoreAndDevices, which is currently a git submodule of this repository.

To checkout both repositories together:

git clone --recurse-submodules https://github.com/micro-manager/micro-manager.git

If you will be making changes to the code, make sure to enable pre-commit hooks as described in doc/pre-commit.md.

Branches

• main - the main branch of development (Micro-Manager 2.x)
• svn-mirror - git-svn mirror of the Micro-Manager 1.4 Subversion repository

Other branches are not official.

Developer information

For license information, please see doc/copyright.txt.

For build instructions, please see the doc/how-to-build.md.

Additional information is available on the Micro-Manager website at https://micro-manager.org

Contributing

Start here: https://micro-manager.org/Building_and_debugging_Micro-Manager_source_code

acqengj's Issues

TaggedImageProcessor and Acquisition

Hi!

I have long wanted to switch our acquisition plugin from the standard MM acquisitions to AcqEngJ. However, I am having a hard time figuring out how to use a TaggedImageProcessor correctly. Let's say I have a set-up like this:

Engine engine = new Engine(studio.core());
	
// create sink and acquisition
SimpleSink sink = new SimpleSink(); // just counts images
Acquisition acq = new Acquisition(sink);
		
// create processor
SimpleProcessor q = new SimpleProcessor();
		
// create acquisition event list
ArrayList<AcquisitionEvent> list = new ArrayList<AcquisitionEvent>();
for(int i=0; i<10; i++) {
	AcquisitionEvent a = new AcquisitionEvent(acq);
	a.setExposure(50);
	a.setTimeIndex(i);
	list.add(a);
}

// start acquisition?
acq.submitEventIterator(list.iterator());
		
// adding processor after the acquisition has started leads to missing frames in the processor
acq.addImageProcessor(q);
		
// finish
acq.finish();

The SimpleProcessor.setDequeues looks like this:

int counter  = 0;
while(true) {			
	TaggedImage newImage = source.pollFirst();
	if(newImage != null) {
		if (newImage.tags == null && newImage.pix == null) {
			System.out.println("[proc] done");
			break;
		}
			
		sink.add(newImage);
		System.out.println("[proc] pass on image "+counter++);
	}
}

Since acq.addImageProcessor calls setDequeues, calling it before acq.submitEventIterator causes the while loop to block the thread. If I call acq.addImageProcessor after acq.submitEventIterator then I miss frames.

So a bunch of questions:

• Have I been doing things wrong? And are there examples somewhere of correct implementations?
• Would it make sense to only instantiate the queues/deques in Acquisition.addImageProcessor and to put the calls to TaggedImageProcessor.setDequeues before running events?
• From an API point of view, I would not expect submitEventIterator to start iterating over the events right away. I guess that Acquisition is designed so that events can be added any time and there can be pauses between batch of events. But a global switch (e.g. start()) could be useful in that case to set up processors, while not changing the behaviour afterwards. Not sure if what I mean is clear!

Thanks!!

Documentation improvement

Some more documentation of this engine would be nice. I just started looking at the api to figure out how to send it a "recipe" of a desired acquisition (for instance, a time lapse with a z-stack in two channels at each time point), but it is not clear to me how to send such instructions to the "Engine" object (which would be step 1 in using this to replace the current engine in Micro-Manager). There are quite a few classes in the api, but it is not obvious what these are or what they can be used for.

Some more javadoc, and possibly a few simple examples would go a long way.

Consider using nanotime() rather than currentMillis()

Nanotime() is guaranteed monotonic, and has a much higher resolution than currentTimeMillis(). See: http://pzemtsov.github.io/2017/07/23/the-slow-currenttimemillis.html

AcqEngMetadata: facilitate writing code by either making keys public or adding "has" functions

AcqEngMetadata has very nice "get" and "set" functions for most (all?) properties. However, if the metadata lack the key that one looks for, a RunTimeException will be thrown. This makes it cumbersome to write code checking for multiple keys, since each "get" function needs to be wrapped in a try-catch block. Either adding "has" functions for all keys (probably the preferred way), or making the keys public so that the calling code can check itself whether the key is present will make the calling code easier to write and much more performant (as Exceptions are expensive).

Inconsistency in AcqEngMetadata handling of axisPosition.

AcqEngMetadata.setAxisPosition(JSONObject tags, String axis, Object position) allows addition of either a String or an integer to the JSONObject metadat. When retrieving these with AcqEngMetadata.getAxisPosition(JSONObject tags, String axis), only an integer value is allowed, i.e. a String will throw a JSONException.

This currently causes the acquisition with multiple channels to fail in Micro-Manager.

Would it make more sense to have two functions, one to get the axisposition by index, the other to get the axisposition by name? How do I force the acquisition engine to insert the channel index rather than channel name?

Better support for sequence acquisitions

Trying to figure out the best way to generically support application (like @dpshepherd's light sheet) alongside the current paradigm in the Clojure acquisition engine where the camera is the master and there is no timing.

As I understand it, @dpshepherd's sets the camera to respond to an external trigger, calls core.startSequenceAcquisition, then sends out a custom command to a piece of hardware which handles synchronization externally.

I think this should be fairly easy to make generic, but that probably depends on how camera device adapters behave. @nicost, do you know if core.startSequenceAcquisition usually work with external triggers like this (if the adapter implemented correctly)?

Update to use snapImage instead of running sequences

When acquiring a single image, it is best to use core.snapImage instead of sequence acquisitions. This is because many cameras need to "prepare" to go from one mode to the other, and many device adapters default to the Snap mode