How to make a customized command plugin for Fiji ImageJ?

[xp1632]

• We have example plugin project for ImageJ 1.x plugin: https://github.com/imagej/example-legacy-plugin
• We have example command project for ImageJ2 plugin: https://github.com/imagej/example-imagej2-command

[xp1632]

https://imagej.net/develop/plugins

[xp1632]

What's a plugin?

• ImageJ is built on the SciJava Common plugin framework.
• A plugin is a Java class annotated with the @Plugin annotation

• Classes annotated in this way are automatically discovered and indexed when the application is launched by a user

  Plugin Types

• To allow efficient retrieval of plugins, each class is annotated with specific type
• Typically the type is a Java Interface

@Plugin(type=Service.class)
public class MyService implements Service { }

Plugin priority

• When in the Context there're more than one match of plugin
• plugin classes are returned in the order of priority of @Plugin annotation

@Plugin(priority=224)
public class SpecialService implements Service { }

[xp1632]

SciJava plugin framework:

• Context:
• Each application is responsible for creating its own Context to

• manage plugins and contextual state

• In ImageJ, Context is automatically created when the application starts up.
• Creating your own Context would cause problem as it will be another container than ImageJ is using.
• Plugin instances within the common Context are provided automatically by the framework

• ---

- Typically ImageJ plugin developers will be writing :

• Service and/or

• Command plugins

• If we would like to use another service or plugins in customized plugin:

• we should ask our Context for an instance instead of manually creating it. Because manually creating it would disconnect us from our application Context

• Here's how we ask our Context for LogService:

@Plugin
public class MyPlugin {

  // This @Parameter notation is 'asking' the Context
  // for an instance of LogService.
  @Parameter
  private LogService logService;

  public void log(String message) {
    // Just use the LogService!
    // There is no need to construct it, since the Context
    // has already provided an appropriate instance.
    logService.info(message);
  }
}

• we ask for an instance by adding @Parameter annotation and desired type

[xp1632]

- Reason that new Myplugin() we used doesn't work:

• In normal case, the way of using a method in Java or Groovy is to new a class, then call the method in the class

• However, in SciJava framework, we also need to consider Context:

• When MyPlugin class in the above is manually constructed via new MyPlugin()

• the LogService parameter will be null

• Automatic population only occurs if the plugin instance itself is retrieved via framework

• When we need to manually construct a plugin instance, we need to reconnect to current Context via injection mechanism:

public class MyService {

  // This service will manually create plugin instances
  // So, we need a reference to our containing Context
  // Then we can use it to inject our plugins.
  @Parameter
  private Context context;

  public void doStuff() {
    // Manually create a plugin instance
    // It is not connected to a Context yet
    MyPlugin plugin = new MyPlugin();

    // Inject the plugin instance with our Context,
    // so the logService field of the plugin will be
    // populated.
    context.inject(plugin);

    // Now that our plugin is injected, we can use
    // it with the knowledge that its parameters
    // have been populated
    plugin.log("Success!");
  }
}

• in the above code, we inject MyPlugin in current Context, and you can see
• the LogService we defined in MyPlugin can be used in MyService now

[xp1632]

Services Plugins in SciJava :

• Services provide two important functions to the SciJava framework:

• utility method and persistent state

• If we need a reusable Java method throughout the SciJava framework, we could create a Service to provide this functionality

• If we need to track Context-wide variables or configuration, Service should be used to encapsulate the state.

Plugin Service

https://github.com/scijava/scijava-common/blob/scijava-common-2.47.0/src/main/java/org/scijava/plugin/PluginService.java

• Services often build on reuse functionality defined in each other
• Plugin Service takes charge of retrieving and working with plugin instances

• To reuse a plugin in other services, we use @Parameter annotation instead of creating a new instance manually just like we said in here

Plugin Manual Register on jupyter:

• In the creating new Op plugin example here
• Op development has same structure of annotation as @Plugin and @Parameter because Op is also a plugin.
• The most important part is :
  • we need to manually register the new plugin on jupyter because

    // The @Plugin annotation is processed by the javac compiler,
    // which is used to generate the metadata in class bytecode.
    // Unfortunately, the Groovy compiler doesn't invoke the javac
    // compiler, so we need to register the plugin manually!
    narfInfo = new PluginInfo(Narf.class, Op.class)
    ij.plugin().addPlugin(narfInfo)
    narfInfo

after registration then we can execute our op:

// Execute our Op and get the result
result = ij.op().run("narf", "Put some trousers on")

---

The ij.plugin().addPlugin() is from the PluginService in SciJava framework

• other plugin operations are :

[xp1632]

- Command Plugins in SciJava

• Whereas Services provide internal functionality, Commands are plugins to be executed one-off, typically interacting with users to achieve desired outcome

• Commands expose functionality and algorithms in a way that can be consumed by non-developers

• Commands are created and executed on demand while Service is instantiated when Context startup

• In Commands, we often declare @Parameeters that cannot be automatically by Context, for example, file path

• Command Execution and Parameter Acquisition

• When a Command is executed, it goes through pre-processing steps to populate @Parameters using associated Context

• If any parameters are left unresolved and a UI is available, the framework will automatically build and display a dialog to get user input

---

This way, input harvest is decoupled from functional operation

• which means Commands can typically run headlessly

• A common pattern in Command development is to wrap Service functionality.

• For example,

• To open an image from a path

• Developers can directly use [DatasetIOService](https://github.com/scifio/scifio/blob/scifio-0.25.0/src/main/java/io/scif/services/DatasetIOService.java)

• Users can get same functionality from menu via [OpenDataset command](https://github.com/imagej/imagej-plugins-commands/blob/imagej-plugins-commands-0.6.0/src/main/java/net/imagej/plugins/commands/io/OpenDataset.java), where the DatasetIOService is wrapped in the command

[xp1632]

Plugins reference repository:

• Looking for services in javadoc

• Check main plugins and plugin definition at imagej-common and scijava-common

  - Main plugin types:

• Ops: reusable image processing algorithms

• Image formats: support new types of images in ImageJ

• Converters, Input Preprocessors, Displays

[xp1632]

Now we show the real development process of a ImageJ2 plugin:

1. plugin template for imageJ2 : https://github.com/imagej/example-imagej2-command

• we clone this repo and open it with VS code that has maven/java extensions installed

• GaussFilter.java is where we write our plugin functional content

• pom.xml is where we write the dependencies, groupId, names, authors so the maven could manage the import for us

2. Read and edit the plugin content GaussFilter.java

Import Part

• We first check the import part:
• The imports for our ImageJ2 template are:
• net.imagej and net.imglib2 are typical packages for ImageJ2

---

• For comparison, the packages for ImageJ1.x plugin template are:
• ij.IJ and ij.ImageJ, ij.xx are typical packages for ImageJ1

---

@Plugin @Parameter Annotation part

• The GaussinFilter plugin is not simple enough, let's start with a simple HelloWorld.java Plugin

• @Plugin annotation lets ImageJ know that this is a plugin

• Command Plugins are the most common one which take inputs and produce outputs, our plugin HelloWorld implements based on Command class _

• @Parameter annotation lets ImageJ know the inputs of this plugin, in HelloWorld, we only used string parameters.

• If we want to use more complex method such as the Services in Scijava framework, we can also annotate it with @Parameter, the ImageJ context would automatically create an instance of that Service for us. I'll show this in the next example GaussianFilter Plugin. _

• The run() method of every Command, is the entry point for ImageJ, which is what is called when the user clicks the menu entry of this plugin.

---

main() for fast testing

• In the main() method, we create an ImageJ content and call the plugin, so we could fast test it in our IDE.

[xp1632]

Gaussian Filter Plugin illustration:

• the complexity of GaussianFilter plugin is that, it uses other Services in Scijava framework:

• 

• As we mentioned here, we should not manually create a Service, we should annotate it with @Parameter and the ImageJ context would create the instance for us.

• As in the picture, the UIService and OpService are annotated with @Parameter,

• we can just use their functions in the following run() method

  

- In run() method,

• we defined a image, a list of sigmas for Gaussian,
• a container list for RandomAccessibleInterval(which is a image type in ImageJ2) results of filtered images
  • we called the filter().gauss() from opService we declared earlier
  • We showed the result by the uiService we declared earlier

---

- In main() method

• for fast testing plugins in our IDE, Run Java, then you can check the performance of plugin in imageJ context
• we first create an ImageJ context
  • we show the UI for choose dataset image
  • we open the file by scifio()
  • we show the dataset
  • we run our plugin by ij.command().run(GaussFiltering.class, true);

[xp1632]

3. Export customized Plugin into a jar file:

To build a Maven project into a JAR file in Visual Studio Code, you can use the integrated terminal and the Maven command line tool. Here are the steps:

1. Open the integrated terminal in Visual Studio Code. You can do this by going to the View menu and selecting Terminal, or by pressing `Ctrl+`` (backtick).

2. Navigate to the root directory of your Maven project (the directory that contains the pom.xml file). You can do this with the cd command. For example, if your project is in a directory called my-project, you would type cd my-project.

3. Run the mvn package command. This command will compile your code, run any tests, and package the compiled code into a JAR file. The JAR file will be created in the target directory of your project.