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

[Oliver Greß]

Hi Curtis and Johannes,

at first, thanks for your replies and openness to extend the @Parameter
annotation.

I didn't want to respond to your mails separately, thus I copied some
parts and added my comments:


>         Would it be possible to extend or modify the @Parameter
>         annotation to
>         categorize a field as input, output, parameter or
>         supplemental?
> 
> Certainly! How about a "visibility" enum with values: NORMAL
> (default), TRANSIENT (for no history), and INVISIBLE (for no recording
> nor history). If anyone has an idea for better names, I'm all ears. In
> the meantime, I have committed an initial version of this enum to SVN
> and updated the Parameter class:
> 
>   http://dev.imagejdev.org/trac/imagej/changeset/2413

Great, I think that's sufficient for our needs in conjunction with the
"output" field. I'll have to discuss it with our group and let you know
if we need anything else.



>         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, I have added a "String description" field to @Parameter, which
> should serve:
> 
>   http://dev.imagejdev.org/trac/imagej/changeset/2412

I think this description field is a good thing anyway, e.g. to show
tooltips (as you mentioned below) in the GUI or to create
plugin/module/operator description in any other way.



>         Another question: Is there any interest in an automatic
>         documentation of
>         the processing chain?
> 
> I think so, but am not sure what you mean. Could you elaborate? What I
> would like to see is a way for plugins to self-document their
> parameters more thoroughly (tooltips etc.), similar to how the
> Bio-Formats Importer plugin works in ImageJ 1.x now. This would reduce
> the need for external wiki pages about plugins in many cases.

Our framework was not intended to give a description of a plugin, but to
record, which plugins/operators were run to create certain results. For
the visualization of that processing chain we wanted of course some
description for better interpretation of the resulting graphs.
The interface of operators (e.g a plugin) is well defined by the
operator's annotated fields. The use of reflections makes it possible to
obtain an operator's interface whenever required. We use it to record
the provenance of resulting data, but it could also be used to tell a
tool like your module framework or ImageFlow, which plugins/operators
can be connected in which way.



> Lastly, I will second Johannes's question: are you planning to open
> source this work? Or is it already available somewhere? Would you be
> interested in integrating it into ImageJ2 core?

We are planning to release a new version by the end of March. 
We have a version online, which is very outdated. We changed a lot since
that version like use of annotations etc. I'd rather wait for the new
version to make it public. I'm going to announce it here as soon as we
have all the resources updated and online.
The code is open source (GPL 3) and we tried to develop it with a
possible integration with IJ2 in mind.



> 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 :-)

We are really interested in Imglib and I attended the corresponding
workshop at the IJ conference last year. I talked to Stephan Preibisch
and he told me, that the lib is still under heavy development. Therefore
we decided to stick with the extension of IJ image types that we
developed.
But that happened last autumn, we should definitely get an update on the
Imglib project.
Anyway, our framework is capable of recording the data provenance of
almost any object, it does not depend on any fixed image
representations. 



Best regards,
Oliver