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

Import Fiji projects via File>Import>Maven>Existing Maven Project. You can either:

  • Import all Fiji projects. You can use Fiji's src-plugins/ directory as the base, and it will discover all the projects automatically. This is a simple way to import everything. However, you will need a reasonably large machine or else your Eclipse might choke a bit, as there are over 100 projects.
  • Cherry-pick relevant projects. You can select a subfolder of src-plugins/ as the base, and it will import only that project. This is a fast way to import only what you need. You can repeat the process to import any projects desired.

After finishing this, Eclipse builds the Fiji projects. There should not be any error message but several thousands of warnings that mostly come from Java1.4-style code or not unnecessary imports, variables or methods in the sources of authors who do not use an IDE 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. Just copy it into a newly created sub-directory of src-plugins/. By convention, that sub-directory should have the base name of the .jar file to be generated.

The format of such a pom.xml is described briefly on our 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 ImageJ2's Maven repository (note: if your firewall does not allow you to access port 8081, you can access a slightly "crippled" version here.

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.

Once you want to make the new plugin part of the complete Fiji Build, add the sub-directory to the <modules> section of src-plugins/pom.xml.