Developing Fiji in Eclipse

QR for this page

From Fiji

Jump to: navigation, search

Purpose

The purpose of this tutorial is to get you started hacking on Fiji's source code (i.e., the core Fiji plugins) inside the Eclipse IDE. If what you need is to develop a new plugin for ImageJ, you do not actually need Fiji's source. Rather, see these resources:

See also Developing Fiji for a more general tutorial unspecific to the Eclipse IDE.

Introduction

Eclipse is a powerful Integrated Development Environment (a so-called IDE) primarily intended to develop Java projects. It is similar to NetBeans and IntelliJ.

The advantages of using an IDE like Eclipse for developing:

  1. it is easy to access documentation about classes (i.e. javadocs): just point your cursor over the name of the class and hit Shift+F2.
  2. you can use code-completion: just type the start of the class name, variable, method, etc you want to use and hit Ctrl+Space.
  3. compile errors are listed in a concise list; double-clicking on a line in that list will move the cursor to the problem.
  4. you can debug your program interactively: just open the main class (i.e. a class having a public static void main(String[] args) method) and go to Run>Debug As>Java Application. This will switch to a different window layout (the Debug perspective) which offers you a range of views that are useful for debugging such as: local variables, thread stack traces, etc. You can interrupt the program at any time by clicking on the pause symbol and inspect the current state, single-step through the code and even to a limited amount replace code on-the-fly
  5. the most important version control systems can be accessed easily

Where there are advantages, there are also disadvantages. For example, Eclipse is quite big a program and requires a lot of resources, RAM and screen size in particular.

One other shortcoming -- Eclipse's unwillingness to let the developer specify that the source code is to be packaged into .jar files automatically -- was fixed by us by using Maven in conjunction with Eclipse (and luckily Netbeans and IntelliJ support Maven projects, too, so we now really only have to support one way to specify dependencies).

Install Eclipse

Install Eclipse using your preferred package manager or download the appropriate binaries of the Eclipse IDE for Java Developers. Launch Eclipse and decide for a workspace location (e.g. ~/workspace). Usually, current Java works just fine, but for some developers, Eclipse is not stable with Sun/Oracle Java 6. That is, you will eventually have to install Java 5 as an alternative JRE and make a custom launcher for Eclipse, e.g.

/usr/lib/jvm/java-1.5.0-sun/bin/java -cp /usr/lib/eclipse/startup.jar org.eclipse.core.launcher.Main

Install Git

Install Git using your preferred package manager or download from the Git website.

Checkout Fiji

Do not clone Fiji into your Eclipse workspace. We are using Maven to manage our projects and Eclipse tries very hard to interfere with this when it is allowed to.

cd ~/
git clone git://github.com/fiji/fiji


This will create the folder ~/fiji/ where you have the core Fiji repository (you will initialize your Eclipse workspace in ~/workspace/ later).

Should you want to work on source code that is not part of the core Fiji repository, you can check out submodules you want to work with. Note: Not all repositories we reference in submodules are handled by Maven.

Create the Eclipse Projects

First, clone your project(s) of interest from https://github.com/fiji. (If you want to clone them en masse, one way is using the myrepos command line tool.)

Once you have the projects cloned, you can import them into Eclipse via the File>Import>Maven>Existing Maven Project command.

After finishing this, Eclipse builds the Fiji projects. There should not be any build errors, but it is normal to see a large number of warnings. These mostly come from Java1.4-style code or unnecessary imports, variables or methods in the sources of authors who do not use an IDE such as Eclipse and thus have no automatic assistance at cleaning up. All these warnings can be ignored, having no effect on the functionality of the code.

Running and Debugging

The major problem when debugging is that ImageJ 1.x expects all the plugins' .jar files to live in a sub-directory plugins/ in the ImageJ root directory. We can trick ImageJ by setting the property ij.dir to the location of the .jar file generated by m2e. The convenience class fiji.Debug in the fiji-lib component lets you do that without any pain:

import fiji.Debug; // requires fiji-lib as a dependency

[...]

public static void main(String[] args) {
    // requires a plugins.config in src/main/resources/ that has a line like:
    // Plugins, "My shiny new plugin", the.current.PluginClass
    Debug.run("My shiny new plugin");
}


To debug classes of type PlugInFilter, use the Debug.runFilter(imagePath, plugin, parameters) method instead.

Note: if you do not even require ImageJ 1.x to really know about your plugin (i.e. the plugin does not have to show up in the menus for the testing/debugging to work), you can also do something like this instead:

public static void main(String[] args) {
    new ImageJ();
    ImagePlus image = IJ.openImage("/path/to/fiji/samples/clown.jpg");
    IJ.runPlugIn(image, "fiji.My_Beautiful_Plugin", "parameter=Hello");
    image.show();
    WindowManager.addWindow(image.getWindow());
}


Adding new plugins

The easiest method is to start with a minimal project, renamed to the desired name of your plugin. By convention, the project directory should match the base name of the .jar file to be generated.

The format of such a pom.xml is described briefly on the Maven page.

Most importantly, you will need to adjust the artifactId and the dependencies section. Should you require a dependency that is not used in Fiji yet, you might want to search for the appropriate groupId and version in the ImageJ Maven repository.

Next, you will put your Java sources into src/main/java/ and adjust src/main/resources/plugins.config.

After that, ask Eclipse to import it: File>Import>Maven>Import Existing Maven Project.