Developing Fiji in Eclipse

QR for this page

From Fiji

Jump to: navigation, search
Source code
Project management
Coding style
Writing plugins
Contributing to a plugin
Distributing your plugins
Development lifecycle
Hands-on debugging
Adding new ops
Adding new formats
Using native libraries
ImageJ 1.x plugins
Building Fiji from source
Developing Fiji
Fiji + Eclipse
Contribution requirements
Supported compilers

Remember: if in doubt, be part of the community by asking and answering questions on the Mailing Lists.


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.


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
  6. awesome shortcuts
  7. vrapper - you don't have to abandon the command-line experience

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 the source code you want to build

Please look at this tutorial to find out how to check out and build individual parts of Fiji.

Create the Eclipse Projects

First, clone your project(s) of interest from (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 defines the command name:
    // Plugins, "My shiny new plugin", the.current.PluginClass"My shiny new plugin", "plugin parameters");

The format of plugin parameters can be determined by using the macro recorder, or just pass null if your plugin opens a dialog. For more complex plugins that are not macro recordable, you can pass empty strings to the run method - it will still launch an ImageJ instance with your plugin on the classpath.

If your plugin does not depend on fiji-lib by default, you can add it using maven. Just paste the following block into your pom.xml dependencies:


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");;

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.