Developing ImageJ in Eclipse
Template:Development This article explains how to install, configure and use Eclipse to develop ImageJ components and plugins. Directions correspond to Eclipse 4.4 Luna, and may need adjustment for other versions.
Contents
Initial setup
Install the Java Development Kit
- Download and install the Java Development Kit (JDK) from the Java web site.
Install and configure Eclipse
Install Eclipse
- Download "Eclipse IDE for Java Developers" from the Eclipse web site.
- Unpack the archive to a location of your choice.
Configure Eclipse for your platform
![]() Avoid permissions issues. We recommend installing Eclipse outside of the Program Files directory. E.g.: C:\Users\frood\Programs\eclipse , where C:\Users\frood is your user directory.
Configure Eclipse. After installing Eclipse, you will need to configure it to know about your JDK. Use Wordpad to edit the Now update Eclipse's JRE to be JDK-aware:
|
![]() Understand Java 6 vs. Java 8. Eclipse should work on OS X with no further configuration. However, we recommend reading the OS X section of the FAQ, as there are several Java-related issues on OS X.
|
![]() Avoid permissions issues. We recommend installing to $HOME/eclipse .
Do not use a package manager. For several reasons, we do not recommend installing Eclipse from a package manager. You may not get a new enough version of Eclipse (we recommend 4.3+), you will not get the Java Developers version that includes the M2E plugins, and you will likely have trouble installing additional plugins due to the permissions issues with the system-wide installation.
|
Clone the source code
- Using your Git client of choice, clone the source code which interests you.
Import the source code
- Choose File › Import from the Eclipse menu
- Select "Existing Maven Projects" and click Next
- Browse to the folder where you cloned the project source code
- Click Finish
Eclipse will import and automatically build the project(s). There should not be any build errors, but it is normal to see a large number (often hundreds) of warnings. These mostly come from Java-1.4-style code or unnecessary imports, variables or methods in the sources of authors who do not use an IDE and thus have no automatic assistance at cleaning up. All these warnings can be ignored, having no effect on the functionality of the code.
The Run-Debug cycle
Keyboard shortcuts
On OS X, replace ^ Ctrl with ⌘ Cmd
Navigation | |
^ Ctrl+⇧ Shift+T | open a Java class |
^ Ctrl+1 | quick fix |
F3 | jump to class (to edit the code, see snapshot coupling) |
^ Ctrl+O | show outline |
^ Ctrl+Space | auto-complete |
^ Ctrl+T | show implementations of interface or class |
Editing | |
⎇ Alt+↑, ⎇ Alt+↓ | move current line up or down |
^ Ctrl+D | delete the current line |
^ Ctrl+/ | comment/uncomment the selected line(s) |
Code cleanup | |
^ Ctrl+⇧ Shift+O | organize imports |
^ Ctrl+⇧ Shift+F | format code (BUT make sure you set the coding style) |
⎇ Alt+⇧ Shift+S, U | clean up (does format and much more) |
⎇ Alt+⇧ Shift+R | refactor rename |
Now that you have the project successfully nestled within Eclipse, you can run it, change the code, and run it again, iterating as needed to develop features and fix bugs. This process is known as the run-debug cycle—although some people call it compile-debug or edit-compile-debug or edit-compile-run or debug-edit-compile or edit-build-test-debug or edit-compile-link-debug or...
Launch ImageJ
If you cloned the imagej project, you can launch the program as follows:
- In the Package Explorer, expand the
imagej
project - Navigate into
src/main/java
- Navigate into
net.imagej
- Right-click on
Main.java
- Choose "Run As" and then "Java Application"
Other projects will have different main classes, but the general procedure is the same.
Running and debugging
One major problem when debugging ImageJ 1.x plugins 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 Fiji project provides a convenience class fiji.Debug in the fiji-lib component which 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 Debug.run("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:
<dependency> <groupId>sc.fiji</groupId> <artifactId>fiji-lib</artifactId> </dependency>
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()); }
Testing your plugin in an existing installation
When you run your plugin from Eclipse, you're only testing with the classpath of this project—which may or may not reflect the environment of an actual user's installation. To test your plugin in an existing installation you can either simply copy the jar, or use Maven to install your plugin and its dependencies.
Option 1: Copying the jar
All modern Eclipse installations have the m2e plugin, so you can simply tell Maven to build the project. This creates a .jar
in the /target
subdirectory, which you can then copy to an ImageJ.app/jars/
directory.
This is a simple option that makes minimal changes to the existing installation.
Option 2: Install dependencies
All mavenized ImageJ projects have built-in support for installing directly into an existing installation, overwriting previous versions of any components, and pulling in up-to-date versions of any dependencies. This is the most robust way to test your plugin, but note that it may make additional changes to your existing ImageJ installation.
Steps are as follows:
- Right-click your project in Eclipse and select Run As › Run Configurations...
- Scroll down to Maven Build. If you've built this project with Maven via Eclipse before there will already be a configuration for it. Otherwise you can double-click "Maven Build" to create a new run configuration.
- Add a parameter:
imagej.app.directory
with value:<path/to/ImageJ.app>
(e.g./home/hinerm/Fiji.app
) - Add a parameter:
delete.other.versions
with value:true
- Click
Apply
You can now run the project from this dialog. You only need to perform this configuration once though—future uses of the Maven Build option will automatically copy your plugin and its dependencies to the specified ImageJ app.
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.
See also
ImageJ2 | ImageJ 1.x |
---|---|
|