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

[Curtis Rueden]

Hi Oliver,

Good to hear from you again. Sorry for the long delay in reply, and thanks
for checking out the ImageJ2 plugin framework.

First, a little background: as Johannes mentioned, there has been initial
development of a "workflow engine" for ImageJ2:


http://dev.imagejdev.org/trac/imagej/browser/trunk/extra/workflow/src/main/java/imagej/workflow

We have begun a reconciliation of the workflow engine with the plugin
framework. Essentially, the toplevel idea is that of a "module" with inputs
and outputs; see:


http://dev.imagejdev.org/trac/imagej/browser/trunk/core/plugin/src/main/java/imagej/module

The plugin framework implements the module interfaces, while providing the
annotations needed to make writing standalone plugins easy:


http://dev.imagejdev.org/trac/imagej/browser/trunk/core/plugin/src/main/java/imagej/plugin

The workflow engine was used to create a proof-of-concept UI called Workflow
Pipes (similar to the ImageFlow project mentioned by Johannes) for
graphically connecting together plugins into a directed object graph. In the
future, we hope to flesh out this UI further and include with core ImageJ.

Anyway, none of this work precludes your implementation from being useful as
well, since our focus was not on data provenance at all yet (though we are
very interested in supporting it).

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

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

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.
>

Great, please let us know what else you need to make this happen!

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.

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?

Regards,
Curtis

P.S. Sorry I have not had time to read over your manual. As we pursue this
functionality further, hopefully I'll learn more about your data provenance
model.

On Tue, Mar 8, 2011 at 6:26 AM, Oliver Gress <
oliver.gress at informatik.uni-halle.de> wrote:

> Hi all,
>
> 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.
>
> 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).
>
> 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.
> 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.
>
> 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 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).
>
> Our annotation can be found here:
> http://users.informatik.uni-halle.de/~gress/MTBArgumentAnnotation.java
>
>
> Best regards
> Oliver
>
>
>
>
>
> _______________________________________________
> ImageJ-devel mailing list
> ImageJ-devel at imagejdev.org
> http://imagejdev.org/mailman/listinfo/imagej-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://imagej.net/pipermail/imagej-devel/attachments/20110317/a924b08d/attachment.html>