How to install and use Jython to write an ImageJ plugin

by Edoardo "Dado" Marcora (last updated on 2005-10-31)

Introduction
Step 1: Install ImageJ
Step 2: Install Jython
Step 3: Make ImageJ aware of Jython
Step 4: Write an ImageJ plugin using Jython
Related resources

Introduction

If you would like to extend the capabilities of the free and wonderful ImageJ image processing and analysis program, but you are scared of writing your own ImageJ plugins because it requires writing complicated Java code... well, there is no need to be scared anymore! You can use Python instead as an alternative midway between the not so powerful ImageJ macro language and Java.
This HOWTO will guide you through the steps of setting up ImageJ to be aware of Jython, the Java implementation of Python 2.1. This means that you will be able to write ImageJ plugins using Python, a powerful yet simple and user-friendly programming language.
This HOWTO assumes that you use Windows on your computer. However, it should get you started in the right direction regardless of the platform that you are using (I got it to work on my Debian Linux-based computer and the same should apply to Mac OS X, it is mostly a matter of changing the directory/folder locations).
The old version of this HOWTO (which uses a different and more cumbersome approach to the integration of ImageJ and Jython) is still available here.
For a tutorial on how to write ImageJ plugins goto here.
You may also want to check out the extensive ImageJ plugins library, to get a feeling of what it is possible to do when you harness the power of ImageJ using plugins.
This approach of making ImageJ aware of Jython in order to use Python as the programming language for developing ImageJ plugins can be easily replicated using other languages (e.g., Ruby) that have Java-based and embeddable versions of their interpreters (e.g., JRuby, Sleep, BeanShell, Groovy, and others).
Please do not hesitate to contact me if you have any question, comment, or suggestion.

Step 1: Install ImageJ

Download and install ImageJ on your computer following the installation instructions specific to your platform (Windows, Mac OS, Linux, etc.).
This HOWTO assumes that you install ImageJ in C:\ImageJ.

Step 2: Install Jython

Download jython-21.class in a directory/folder on your computer.
Start the Jython installer using the Java interpreter that runs ImageJ:

Open a command window.
Change the working directory/folder to where you downloaded the jython-21.class file.
Type C:\ImageJ\jre\bin\java -cp . jython-21.

Follow the Jython installer instructions and install Jython in C:\Jython21\.

Step 3: Make ImageJ aware of Jython

In brief, the goal here is to add C:\Jython21\jython.jar to the classpath of the Java interpreter that runs ImageJ.
To make ImageJ (v1.31 or older) aware of Jython, open the C:\ImageJ directory/folder, right-click on the ImageJ shortcut (a microscope with an arrow), and change the "Target:" field of the "Shortcut" properties to:
C:\ImageJ\jre\bin\javaw.exe -mx256m -cp ij.jar;C:\Jython21\jython.jar ij.ImageJ
The -mx256m switch specifies that ImageJ will have available a maximum of 256MB of RAM. The -cp switch specifies the classpath mentioned above, which should include the location of Jython (jython.jar) in addition to that of ImageJ (ij.jar). Also, make sure that the "Start in:" field of the "Shortcut" properties to is set to C:\ImageJ.
If you are using a recent version of ImageJ (v1.32 or newer), then all you have to do is to add C:\Jython21\jython.jar to the -cp switch in the C:\ImageJ\ImageJ.cfg file.

Step 4: Write an ImageJ plugin using Jython

Enough with this installation cr@#&p! Let's write an ImageJ plugin using the delightful Python syntax!!!
First, create a text file named Hello_World.py in the ImageJ plugins directory C:\ImageJ\plugins.
Open Hello_World.py with your favorite text editor, insert the following Python code, and save the file.

# import and use ImageJ (Java) classes as if they were Python classes

from ij import IJ

IJ.showMessage("Hello World!")

Second, create a text file named Hello_World.java in the same directory.
Open Hello_World.java with your favorite text editor, insert the following Java code, and save the file.

import ij.plugin.PlugIn;

import org.python.util.PythonInterpreter;

public class Hello_World implements PlugIn {

public void run(String arg) {

// create a Python interpreter

PythonInterpreter py = new PythonInterpreter();

// execute the Python file containing the source code for this ImageJ plugin

py.execfile("C:\\ImageJ\\plugins\\Hello_World.py");

}

Launch a Jython-aware ImageJ instance and compile Hello_World.java using the menu command "Plugins>Compile and Run...". A message box saying "Hello World!" should pop up!
Restart ImageJ and a new command named "Hello World" should be present under the "Plugins" menu. To test it, run the "Plugins>Hello World" menu command and the aforementioned message box should pop up again.
As you can see, Hello_World.java is mostly boiler-plate code (only the parts marked in red need to be customized) and it exists only to support Hello_World.py. Write it once, compile it and forget about it. All the "real" programming is done in Hello_World.py.
Congratulations... you've written your first ImageJ plugin using Jython! Now you can go back and edit Hello_World.py and see the changes take effect immediately without the need to recompile anything or even restart ImageJ... isn't that great!!! :)
Of course, this is only a simple example but don't forget that, via Jython, you have full access to the raw power of ImageJ (plus its plugins and macros) and to the elegance and ease of use of Python and its extensive library.

A similar approach is used to write an ImageJ plugin filter...

First, create a text file named Invert_Filter.py in the ImageJ plugins directory C:\ImageJ\plugins.
Open Invert_Filter.py with your favorite text editor, insert the following Python code, and save the file.

# "ip" is the image processor of the current image that is passed in from ImageJ

ip.invert()

Second, create a text file named Invert_Filter.java in the same directory.
Open Invert_Filter.java with your favorite text editor, insert the following Java code, and save the file.

import ij.plugin.filter.PlugInFilter;

import ij.ImagePlus;

import ij.process.ImageProcessor;

import org.python.util.PythonInterpreter;

public class Invert_Filter implements PlugInFilter {

public int setup(String arg, ImagePlus imp) {

// inform ImageJ that this plugin filter only handles 8 bit grayscale images

return DOES_8G;

}

public void run(ImageProcessor ip) {

// create a Python interpreter

PythonInterpreter py = new PythonInterpreter();

// pass the image processor of the current image to the Python interpreter

py.set("ip", ip);

// execute the Python file containing the source code for this ImageJ plugin filter

py.execfile("C:\\ImageJ\\plugins\\Invert_Filter.py");

}

Launch a Jython-aware ImageJ instance and compile Invert_Filter.java using the menu command "Plugins>Compile and Run...". A message box saying "There are no images open" should pop up! Remember that an ImageJ plugin filter requires an image to act upon; therefore, don't worry and read on!
Restart ImageJ and a new command named "Invert Filter" should be present under the "Plugins" menu. To test it, open an image (it must be a gray scale image for this particular filter) and run the "Plugins>Invert Filter" menu command, which should invert the current image.
As you can see, Invert_Filter.java is mostly boiler-plate code (only the parts marked in red need to be customized) and it exists only to support Invert_Filter.py. Write it once, compile it and forget about it. All the "real" programming is done in Invert_Filter.py.
Hope this helps to get you started. Most importantly, have fun scripting ImageJ with Python!!! :)

Related resources

Albert Cardona wrote an ImageJ plugin that makes it really easy, even easier than what I described above, to integrate Jython plugins with ImageJ. He also wrote a Jython interpreter that integrates with ImageJ. You can find them here.
This site here has a Jython editor/interpreter that integrates with ImageJ.