What is the current recommended documentation to write extensions?

imagej
plugin
macro
scripting
script-parameters

#1

Hi everyone,

At Light Microscopy Australia 2019, I am co-organising a one day satellite symposium on bioimage analysis. After a keynote by @royerloic (:wave:), we will have a “tools” session where we present various open source tools for image analysis. I’m aiming for this session to highlight the advantage of open source when developing your own workflows, and serve as a gentle on-ramp for people to move from analysis to development.

As regards Fiji, various bits of documentation have warnings that they might be outdated, see e.g. Plugin Design Guidelines. My impression from lurking on the gitter imglib2 channel is that all these things are evolving rapidly so I wanted to query the community on the latest information on the best way to do this. Specific questions:

  • If I only point people to one document on Fiji plugin/command development, what should it be?
  • Is there a documented gentle path to go from macro recording -> script (preferably in the user’s preferred language, Jython would of course be my top choice :wink: -> command in the GUI -> more full-featured plugin?
  • If not, would anyone care to volunteer to write it? I think it would be enormously valuable. :wink:
  • for the last step above, what kind of things could you do with “real”, Java plugin development compared to a script with parameters? (ie should most users worry about this?)

I’d like the talk to be appealing to boldly-enterprising-curious-biologists, rather than programmers, so I think that this “Writing plugins” page would be too intimidating to start with. “Script parameters” is more in line with what I would like to point people to, but then I would need instructions for turning scripts into plugins and distributing said plugins.

Thanks to @imagejan @axtimwalde @bogovicj and @ctrueden for already chiming in on gitter, and encouraging this post.


Grid overlay plugin in GUI application for FIJI
#2

I second using the tutorials repository with a special emphasis on the Groovy based Jupyter notebooks.

Groovy provides a scripting environment using a Java-compatible syntax. If one could hack together a Groovy script, it would be mostly a copy and paste operation to go to a formal Java plugin.

If you want to focus on scripting, then starting at Scripting Basics might work. However, the scripting basics below are ImageJ1 based, which will still work but is not the future API.

If this is part of a larger tools session, it is very likely that Jupyter notebooks will already be featured as part of a Python-based presentation. Perhaps together with the other speakers during this session you could come up with a common setup using conda.


#3

About the same where you would go for C or C++ in Python, everything that needs to be fast such as looping over pixels, implementing basic algorithms like watershed, ad-hoc sparse convolution, distance transforms, non-trivial geometric transformations, … i.e. everything interesting ;).

@albertcardona 's Weaver can fix this [https://www.ini.uzh.ch/~acardona/fiji-tutorial/#imglib2-vol4d-visualization].


#4

Hi @jni

I am reasonably sure you know about the jython scripting tutorial for ImageJ/Fiji: https://www.ini.uzh.ch/~acardona/fiji-tutorial. In there, I describe how to use the macro recorder to discover what plugins are being invoked by UI commands, and also to use them for setting up script one-liners that do the same thing.

In general:

  1. If your macro has more than about 10 lines, one should write a script.
  2. I would favor teaching how to write functions, and then how to compose a script from a bunch of functions.
  3. If your script is to do any pixel-wise edits, likely java is better suited. As @axtimwalde pointed out, one can kludge in a-la python’s ancient weaver package a snippet of java code (without generics!) to do low-level operations without the overhead costs of jython, and get away with it for most purposes. If the snippet becomes the whole program, then a java plugin should be written instead–for one, it will have proper syntax highlighting.
  4. jypiter notebooks are a good way to present data to others in polished form. They are a terrible way to learn how to code, or to develop a script. Instead, use e.g. the Fiji Script Editor (“File - New - Script”).
  5. If a script involves loading images over the network, or large images, or any other costly executions separable from the rest of the program, it’s easier to develop the code incrementally in a script interpreter. (Fiji’s Script Editor recently got incremental evaluation powers but this feature isn’t released yet).

#5

Thanks @markkitt, @axtimwalde, and @albertcardona!

Thanks, that’s exactly the right way to put this rule of thumb for my brain. =) But I do think you can do many interesting things by composing existing operations. =)

Don’t worry Albert, we are in complete agreement with this. =) Chris Holdgraf has a nice succinct way to describe this: notebooks are a communication tool that you can also use for coding, rather than a coding tool that you can also use for communication.

I haven’t found a good way to go from run("Function name...") to actual_function(...). Possibly this is now easier than it used to be, with @haesleinhuepf’s auto code completion?

Might it happen before March? =)

This is exactly the sort of thing I’m reluctant to point people to. =) However, the tutorials repo is nice and modern, and is a great place to point people to after the caveats @albertcardona pointed out are made clear.

I’m still left wondering what the best way for people to share their Fiji scripts is…? I know that they can drop scripts into the Plugins folder, but this seems fiddly, especially in macOS where you have to “show package contents”. Is there a menu command to “save to plugins directory” or “save as plugin” or somesuch? Otherwise I just saw the Update site documentation and it seems pretty comprehensive, thanks!


#6

Hey @jni

as you were asking for the barrier between analysis and development: I just want to add a link to an online-tutorial a visiting student did at some point at MPI CBG (in Pavel Tomancaks lab). It’s about how to make your first ImageJ/Fiji plugin in 5 minutes:

@albertcardona

I wonder what “incremental evaluation power” means. I hereby volunteer as tester. Please let me know as soon as there is something to play with! :wink:

Cheers,
Robert


#7

you’ve thrown a “bomb” exploded in a lot of curiosity :sunglasses::crazy_face:


#8

Hi @emartini @haesleinhuepf

The Script Editor supported selecting text and evaluating it with “Run” or control+R, but the result of the evaluation was thrown away. Now, the Script Editor can do that or, via the “persistent” checkbox, make the results of the evaluation persist. To access those results, a command prompt becomes available.

Note that the command prompt is a fully capable scripting interpreter, sharing the script engine with the main script window when in “persistent” mode. This removes the need for e.g. copy-pasting code from the Script Editor to e.g. the Jython Interpreter, a pattern I’ve seen one time too many in myself and others.

Note also that, when in “persistent” mode, the evaluated code from the Script Editor main script window is not pasted into the output area nor is available via page up/down keys in the command prompt. Perhaps it should, for consistency, but currently it doesn’t. What you can access is the top-level functions, classes, and variables that were declared in the executed snippet.

Unrelated, the Script Editor now has a file system tree from which scripts can be opened via double-click, and images open in ImageJ/Fiji itself. Drag and drop from the tree into the main script text area will paste the path at the text caret position. And the choice of listed top-level folders in the file system tree will be persisted when Fiji is closed.

This file system tree and the persistent mode are helpful for development of scripts and for every day execution of scripts in the lab. After having been using it for a month, I can’t understand why I didn’t implement these features earlier.

These capabilities are currently available as a PR: https://github.com/scijava/script-editor/pull/28 or from my personal github fork of the script-editor repository.