home | contents | previous | next

Plugins Menu

Introduction

Plugins and macros are loadable code modules that extend the capabilities of ImageJ. Plugins are written in the Java programming language and compiled to .class files. Macros, written in ImageJ's Java-like macro language, are stored in .txt files. Plugins run faster and are more flexible but macros are easier to write and debug. Plugins and macros in the plugins folder, with an underscore in their name, are listed at the bottom of this menu. Plugins and macros in subfolders of the plugins folder are listed in submenus. Use Shortcuts>Create Shortcut to assign a keyboard shortcut to a plugin or a macro.

Use the Recorder (Macros>Record) to record a series of commands and to convert them to a macro. Use the Edit>Convert to Plugin command in the editor to convert the macro to a plugin. Note that the Convert to Plugin command is only available in editor windows created by clicking on "Create" in the Recorder and it does not correctly convert some macro code. Use the commands in the New submenu to create new macros, scripts or plugins. Press "o" (File>Open) to open an existing macro, script or plugin. More than 500 plugins are available through the ImageJ Web site as well as more than 300 macros. A tutorial for plugin writers is available at www.imagingbook.com. There are also tutorials on how to use the Eclipse (tutorial1, tutorial2), NetBeans and Xcode IDEs to develop ImageJ plugins. Information about macros is available on the ImageJ Web site.

Internal Plugins

Most commands in ImageJ are implemented as plugins but these internal plugins are located in the ij.jar file, not in the plugins folder. ij.jar also contains the properties file (IJ_Props.txt) that ImageJ uses to install internal plugins in menus. A JAR file (Java ARchive) is formatted the same as a ZIP file, so you can use a ZIP utility to look at the contents of ij.jar.

You can convert an internal plugin to a user plugin by copying the source to the plugins folder, adding an underscore to the file name and class name, and changing the package statement to an import statement. For example, to change the RoiManager (Analyze/Tools/ROI Manager) to a user plugin:

  1. Download the latest ImageJ source code.
  2. Copy ij/plugin/frame/RoiManager.java to the plugins folder.
  3. Change the file name to Roi_Manager.java.
  4. Open Roi_Manager.java using File>Open and change all instances (4) of "RoiManager" to "Roi_Manager".
  5. Change the first line from "package ij.plugin.frame;" to "import ij.plugin.frame.*;".
  6. Run the new plugin using the editor's File>Compile and Run command.
There will be a new Roi Manager command in the Plugins menu the next time you restart ImageJ.

Changing Location of Plugins Directory

The "plugins.dir" property specifies the location of the parent of the plugins directory. This property can be set from either the command line or from within a Java program that starts ImageJ. For example, if you run ImageJ with the command
java -Dplugins.dir=/Users/wayne -cp ij.jar ij.ImageJ
it will look for the plugins folder in the /Users/wayne/ directory. This property can also be set in a program that launches ImageJ:
System.getProperties().setProperty("plugins.dir", "/users/wayne");
new ImageJ(null);

Macros Submenu

This submenu contains commands for installing, running and recording macros, as well as any macro commands added by Plugins>Macros>Install. Macros contained in a file named "StartupMacros.txt", in the macros folder, are automatically added to this submenu when ImageJ starts up.

Install...

Adds one or more macros contained in a file to the bottom of this submenu. To install a set of macros, and at the same time view their source code, open the macro file with File>Open and use the editor's Macros>Install Macros command. Macros in the file ImageJ/macros/StartupMacros.txt are automatically installed when ImageJ starts up.

Run...

Loads and runs a macro without opening it in the ImageJ editor. To run a macro, and at the same time view its source code, open it with File>Open and use the editor's Macros>Run Macro command.

Record...

Opens the ImageJ command recorder. To create a macro, open the recorder, use one or more ImageJ commands, then click "Create". When the recorder is open, each menu command you use generates a macro run() function call. The run() function has one or two string arguments. The first is the command name. The optional second argument contains dialog box parameters.

Create a rectangular, oval or line selection and the recorder will generate a makeRectangle(), makeOval() or makeLine() function call. Click on "Auto" or "Set" in the Image>Adjust>Threshold window to generate a setThresold() call, and on "Reset" to generate a resetThresold() call. Select an image from the Window menu to generate a selectWindow() call. Click in the Image>Color>Color Picker window to generate setForegroundColor() and setBackgroundColor() calls.

Shortcuts Submenu

This submenu contains commands for creating keyboard shortcuts and for installing and removing plugins.

Create Shortcut...

Assigns a keyboard shortcut to an ImageJ menu command and lists the shortcut in the Shortcuts submenu.

[hotkey]

Select the command from the popup menu and enter the shortcut in the text field. A shortcut can be a lower or uppercase letter or "F1" through "F12". Use Plugins>Utilities>List Shortcuts to get a list of shortcuts that are already being used.

Install Plugin...

Installs a plugin in a user-specified submenu. Plugins with a showAbout() method are also automatically added to the Help>About Plugins submenu.

[install]

Use the first popup menu to select the plugin and the second to select the submenu it is to installed in. The command must be different from any existing ImageJ command. Shortcut (optional) must be a single letter or "F1" through "F12". Argument (optional) is the string that will passed to the plugin's run method.

Remove...

Removes commands added to the Shortcuts submenu by Create Shortcuts. Also removes commands added by Install Plugin and removes plugins installed in the Plugins menu. The menus are not updated until ImageJ is restarted.

[remove]

Utilities Submenu

This submenu contians several useful utility functions.

Control Panel...

This command opens a window containing ImageJ commands in a hierarchical tree structure. Click on a leaf node to launch the corresponding ImageJ command (or plugin). Double-click on a tree branch node (folder) to expand or collapse it. Click and drag on a tree branch node (folder) to display its descendants in a separate (child) window. In a child window, click on "Show Parent"to re-open the parent window. The Control Panel was contributed to the ImageJ project by Cezar M. Tigaret.

Control Panel

ImageJ Properties...

This command displays various ImageJ properties (Java version, OS name and version, path separator, location of directories, screen size, etc.) in a text window.

List Shortcuts...

This command generates a table with the ImageJ keyboard shortcuts in one column and the commands they call in another. Note that you do not have to hold down the control key to use a keyboard shortcut. To open an image, for example, press the "o" key.

Threads...

This command lists, in a text window, the currently running threads and their priorities.

Benchmark

Runs 62 image processing operations on the current image and displays the elapsed time in the ImageJ status bar. The fastest sysems (as of early 2007) run this test on a 512x512 RGB image (e.g., File>Open Samples>Mandrill) in about one second. Additional benchmarks, test results, and souce code are available in the Benchmarks package of plugins.

Reset...

Use this command to unlock a locked Image, or to reclaim memory used by the clipboard and undo buffers.

Monitor Memory...

Displays a continuously updated graph of ImageJ's memory utilization, which can be useful for detecting memory leaks. Ideally you should be able to open a several images, process them, close them, and the amount of memory used will be the same as when you started. Clicking on ImageJ's status bar, which forces the Java garbage collector run, may help reclaim unused memory. Start the memory monitor with the alt key down to have it use a 640x480 window that simulates how a frame grabber plugin would work.

[Search dialog]

Search...

Searches recursively for a particular string (case sensitive or not) contained in the file names or file contents in a chosen folder. The results are displayed in the Log window. If the "Search Contents" option is checked, the line number where the string was found is displayed. In the Log window, double click on a file path to open that file in an editor window.

[Search dialog]

There is an option to search the macros folder and also an option to search the ImageJ source code if it has been downloaded (from rsb.info.nih.gov/ij/download/src/) and extracted into the ImageJ folder.

Capture Screen

Copies the the screen to an RGB image and displays that image a new window. Pressing control-shift-g will capture the screen while a modal dialog box is active if the dialog is based on ImageJ's GenericDialog class.

Find Command

The Command Finder, created by Mark Longair, provides an easy way to find commands you might know the name of without having to go through all the menus. If you type part of a command name, the list will only show commands that match that substring. If only a single command matches then that command can be run by pressing Enter. If multiple commands match, click with the mouse to select a command to run. Alternatively pressing the up or down keys will move keyboard focus to the list and the selected command can be run by pressing Enter. Pressing Backspace switches focus back to the prompt. Double-clicking on a command will run that command. Pressing Esc closes the window.

New Submenu

This submenu contains commands that open editor windows that can be used to edit and run macros and plugins. It also has a command that opens a text window of a specified size and a command that opens a table that macros can write to. The editor windows opened by PlugIn, PlugInFilter and PlugInFrame contain prototype Java code for the three types of plugins supported by ImageJ.

Macro

Opens a blank editor window with the title "Macro.txt". The window has a Macros menu that lets you run, install and abort ImageJ macros. As a shortcut, press shift-n (File>New>Text Window) to open a macro editor window.

JavaScript (requires ImageJ 1.41 or later)

Opens a blank editor window with the title "Script.js". Use the editor window's Macros>Run Macro command to evaluate JavaScript code. The required JavaScript interpreter (Mozilla Rhino) is built into Java 1.6 for Linux and Windows. Mac users, and users of earlier versions of Java, must have a copy of JavaScript.jar in the plugins folder. This file is included with the Mac version of ImageJ 1.41, in the ImageJ/plugins/tools folder.

Example JavaScript programs are available at rsb.info.nih.gov/ij/macros/js/. To run one of the examples, download it, drag and drop it on the "ImageJ" window, then press ctrl-r (Macros>Run Macro). Or copy it the clipboard, paste it into a window created by this command, and press ctrl-r. Albert Cardona's Javascript Scripting tutorial also has examples.

PlugIn

Opens an editor window containing a prototype plugin that implements the PlugIn interface. Plugins of this type open, capture or generate images. The prototype displays "Hello world!" in the ImageJ window. Press ctrl-r (File>Run Macro) to compile and run it. Note that the name you choose for the plugin should include at least one underscore. Another example is the Step Maker plugin at ../../plugins/steps.html.

PlugInFilter

Opens an editor window containing a prototype plugin that implements the PlugInFilter interface. Plugins of this type process the active image. The prototype inverts the active image twice. Another example is the Image Inverter plugin at ../../plugins/inverter.html.

PlugInFrame

Opens an editor window containing a prototype plugin that extends the PlugInFrame class. Plugins of this type displays a window containing controls such as buttons and sliders. The prototype opens a window containing a text area. Another example is the IP Demo plugin at ../../plugins/ip-demo.html.

Text Window

Opens a text window of a specified size that macros can write to. PrintToTextWindow, Clock and ProgressBar are examples of macros that write to a text window.

Table

Opens a blank table, similar to the Results table, that macros can write to. SineCosineTable is an example of such a macro.

The editor windows created by these command have an Edit>Zap Gremlins command that finds and deletes the extraneous non-visible characters that sometimes appear when cutting and pasting from other sources, such as email messages.

Compile and Run...

Compiles and runs a plugin. Runs a plugin if the name of the selected file ends in ".class". Requires that ImageJ be running on a Java Virtual Machine that includes the javac compiler, which is contained in the tools.jar archive. Tools.jar is included with the Windows and Linux versions of ImageJ bundled with Java, and it is pre-installed on Mac OSX. Troubleshooting information can be found under "Compiling Plugins" in the Linux and Windows release notes.

The Edit>Options>Compiler command displays a dialog box that can be used to configure the javac compiler used by Compile and Run.

top | home | contents | previous | next