search

micro-manager / mmCoreAndDevices

Micro-Manager's device control layer, written in C++
40 stars 108 forks source link

Expand on description of autofocus methods #156

Open ianhi opened 2 years ago

ianhi commented 2 years ago

In particular I'm not sure what things like "the one-shot focusing device" is referring to: https://github.com/micro-manager/mmCoreAndDevices/blob/5e132fad7feee8ec6e0af4ceb7aff84efc503b3a/MMCore/MMCore.cpp#L7071-L7073

It would also be great to have a bit more explanation as to the difference between fullFocus and incrementalFocus (although for the TE2000 at least they seem to be equivalent.

marktsuchida commented 2 years ago

It's hard to definitively document a vague API, but the short story is that incrementalFocus was intended for software autofocus and does not make sense with hardware focus-maintenance devices (PerfectFocus, DefiniteFocus, AFC, ZDC, CRISP). We should probably mark it deprecated, and remove it soon.

The beginning of the problem was when two different concepts -- autofocus and focus-maintenance -- were jumbled together. Currently all "autofocus" devices in C++ device adapters are actually focus-maintenance devices. (Although in theory it is possible to have true hardware AF, and some of the newer stands might have functions in this direction.)

There used to be a C++ device adapter that performed software autofocus (with very leaky abstractions -- I shuddered at the thought of a device adapter taking control of the whole microscope with no mechanism of monitoring its actions from the application). This has been removed, and all extant device adapters simply forward IncrementalFocus() to FullFocus() (correct) or implement the former as a no-op (probably not so correct).

In the Java autofocus plugins, for the simpler software AF methods that performs a linear Z stack to find the max-scoring slice, incremental focus might be implemented as a cycle with a reduced Z range -- to be used when maintaining, rather than initially finding, the focus at a position.

ianhi commented 2 years ago

Thanks mark this is really helpful! One thing that I'm realizing I'm not totally clear on is the distinction between autofocus and focus-maintenance. I think I've only ever heard these systems referred to in conversation as autofocus. Is there a clear technical distinction?

marktsuchida commented 2 years ago

Some vendors make a point of not calling their system "autofocus", which I think makes sense, but it is also true that the lines do blur a little. It may not be the only way to organize the concepts, because every system is subtly different.

In my view the main difference is that focus-maintenance uses the position of a reflective interface (e.g. glass surface) as input data, whereas autofocus uses the specimen image as input data.

An example of hardware AF is what you see in DSLRs, but this is also image-based (with special optics).

Knowing where the reflective surface lies does not (in general) tell you where the desired focus is (maybe the user wants to focus 5 um above the bottom of the dish), so typically the user needs to initially specify where the desired offset is. It is possible that a microscopist would like a system where image-based autofocus is run initially to determine the plane (e.g. Z midpoint of nuclei in each field of view), but reflection-based maintenance is used to keep a constant offset throughout a time series experiment.