How to install and use Ruby to write an ImageJ plugin

by Edoardo "Dado" Marcora (last updated on 2006-12-12)

Table of Contents

1. Introduction
2. Step 1: Install ImageJ
3. Step 2: Install JRuby
4. Step 3: Make ImageJ aware of JRuby
5. Step 4: Write an ImageJ plugin using the Ruby language

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 Ruby 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 JRuby, the Java implementation of Ruby. This means that you will be able to write ImageJ plugins using Ruby, 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).
• 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 JRuby in order to use Ruby as the programming language for developing ImageJ plugins can be easily replicated using other languages (e.g., Python) that have Java-based and embeddable versions of their interpreters (e.g., 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 JRuby

• Download and install JRuby on your computer following the installation instructions specific to your platform (Windows, Mac OS, Linux, etc.).
• This HOWTO assumes that you install JRuby in C:\JRuby and that you set the system variable JRUBY_HOME appropriately as indicated in the installation instructions.

Step 3: Make ImageJ aware of JRuby

• In brief, the goal here is to add C:\JRuby\lib\jruby.jar to the classpath of the Java interpreter that runs ImageJ.
• To make ImageJ (v1.31 or older) aware of JRuby, 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:\JRuby\lib\jruby.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 JRuby (jruby.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:\JRuby\lib\jruby.jar to the -cp switch in the C:\ImageJ\ImageJ.cfg file.

Step 4: Write an ImageJ plugin using the Ruby language

• To make it really easy to write and use ImageJ plugins written using the Ruby language I modified an ImageJ plugin written by Albert Cardona for Jython.
  
• Just download it here and unzip it into your ImageJ plugins folder C:\ImageJ\plugins. The unzipping process should create a folder named "Ruby" containing the plugin java source file C:\ImageJ\plugins\Ruby\Refresh_Ruby_List.java and a Ruby plugin example C:\ImageJ\plugins\Ruby\Add_Noise.rb.
• Run ImageJ and execute the command "Plugins>Compile and Run..." on C:\ImageJ\plugins\Ruby\Refresh_Ruby_List.java.
• Restart ImageJ. You should now have a new command available at "Plugins>Ruby>Refresh Ruby List" that populates the "Plugins>Ruby" menu with submenus corresponding to every *.rb file in the C:\ImageJ\plugins\Ruby folder. To make this happen every time you start ImageJ add: macro "AutoRun" { run("Refresh Ruby List"); } to your C:\ImageJ\macros\Startup_Macros.txt file.
• Looking at the C:\ImageJ\plugins\Ruby\Add_Noise.rb file should get you started on how to write an ImageJ plugin using the Ruby language! Most importantly, have fun scripting ImageJ with Ruby!!! :)

Belorussian translation