[ImageJ-devel] Auto-Documentation of Processing Chain: Extension of @Parameter Annotation

[Johannes Schindelin]

Hi,

On Tue, 8 Mar 2011, Oliver Gress wrote:

> we have developed a way for automatic documentation of the processing 
> chain of an image or other results in ImageJ. For improved integration 
> with IJ, we would like to discuss a modification/extension of the 
> @Parameter annotation in IJ-Dev.

Great!

Somebody made a similar thing (chaining plugins) on top of the Parameter 
framework, but unfortunately did so in a manner that cannot be merged back 
easily. So I appreciate very much your willingness to work on getting your 
enhancements included!

> The basic concept is to consider each processing step as an "operator", 
> that takes some input and computes results, which might become input to 
> another operator. Such an operator may be an ImageJ plugin or any java 
> class that satisfies the specification.
> 
> The specific interface of such an operator is described by inputs,
> parameters, supplementals and outputs. 
>
> Inputs and outputs are used to trace the processing chain, from which a
> "history" graph is created.
>
> Parameters are inputs that are not traced but recorded. Supplementals
> are not recorded at all and are intended for parameters that have no
> effect on the results (e.g. a verbose flag).

Sounds good!

> We employ java annotations to determine the above interpretation of the 
> fields of a class and thus the interface of an operator. At the moment, 
> we use our own annotation class, because @Parameter from IJ-Dev does not 
> allow the detailed categorization of arguments that would be required by 
> our concept. It only allows to specify if an argument is output or not.
>
> I know that @Parameter is intended to describe the parameters of a
> plugin, e.g. to create a parameter dialog automatically. 

Yes, but also more:

http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=imagej2/.git;a=blob;f=core/plugin/src/main/java/imagej/plugin/Parameter.java;h=fcf73c23565abd8a359a0422bfd8f4503f450154;hb=83c6c9241723d64c3c97ea2e9c150548f568771b

> I'd like to ask if the idea of @Parameter could be extended to a more 
> general point of view:
> 
> Would it be possible to extend or modify the @Parameter annotation to 
> categorize a field as input, output, parameter or supplemental? Our 
> annotation also takes an "explanation" string to describe the parameter 
> in human-readable form, but it is not essential for the automatic 
> documentation.

Sure, as long as you make those fields optional, the @Parameter can be 
enhanced. If you're working with Git, you might use our mirror at 
git://pacific.mpi-cbg.de/imagej2/.git, otherwise work with with Subversion 
on http://dev.imagejdev.org/svn/imagej/trunk.

> We would really like to merge these annotations, because the processing 
> chain documentation could be easily employed by IJ plugins that use the 
> @Parameter annotation and no additional annotation would be necessary.
> 
> Another question: Is there any interest in an automatic documentation of 
> the processing chain?

I think that this is a good idea, but it can be taken a bit further:

	http://imageflow.danielsenff.de/

Note that ImageFlow is only intended for macros, and as such is not easily 
extended to real script languages or on-the-fly construction of Java 
classes. But it is a start.

> I have uploaded an excerpt of our manual for further reading on the
> operator and history concept:
> http://users.informatik.uni-halle.de/~gress/mitobo_manual_excerpt.pdf
> The manual is rewritten at the moment, therefore only an excerpt. If you
> find a link to our website, please don't refer to the resources that can
> be found there because they are outdated. There will be a new version
> soon (depending on the annotation issue).

This is interesting. Any chance that all components become Open Source? I 
am especially intrigued by the mention of CellSegmentation in the 
manual...

BTW you might also be interested in having a look at Imglib. It is still 
in a stabilizing phase, but the base concepts are described here:

http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=imglib.git;a=blob_plain;f=imglib/doc/imglib2.svg;hb=imglib2

Basically, you will never need 4-nested loops to do neighborhood 
operations again :-)

Ciao,
Johannes