ImageJ 1.* was never meant as anything else than a desktop application with one user in front of one screen attached to one computer.

However, it acquired macro capabilities, a batch mode for such macros, and even scripting support through Fiji.

Naturally, users want to execute such macros or scripts in environments such as clusters where there is no graphical user interface available.

The problem

Java does support a headless mode via the java.awt.headless property; setting this property to true enables it.

Unfortunately, with X11-based Java (such as on Linux, which is the most prevalent platform for running clusters), headless mode does not allow to instantiate any GUI components that would want to display text. The reason is that the font-metrics on X11 are provided by the X11 server (and are indeed different between servers) and therefore the dimensions of such elements simply cannot be calculated without a graphical desktop.

Since ImageJ 1.* was devised as a desktop application, everything -- including macros -- works through the GUI. For example, a simple run("Open..."); will look for the action in the menu.

On MacOSX, there is no problem: Aqua provides GUI-independent text rendering (mapping to the actual display using anti-aliasing). There, running in headless mode allows instantiating GUI elements such as the menu bar.

Possible solutions

Fiji's --headless mode

Originally a branch in ImageJA, the headless support basically rewrites a couple of classes to allow for starting ImageJ 1.* in batch mode without instantiating GUI components.

Historically, we put the three classes into a file called headless.jar which was put into the class path before ij.jar so they would override ImageJ's versions.

Nowadays, we use Javassist for run-time patching, but if you still require a headless.jar file (e.g. because your Java environment does not allow run-time modification of Java classes), you can check out fiji.git and run ./Build.sh misc/headless.jar.

Shortcoming: There are plugins which are even more bound to a GUI than ImageJ 1.*. Naturally, these plugins will still try to instantiate GUI elements when being called in headless mode, failing.

Xvfb

Another method is to have a virtual desktop, e.g. Xvfb. This will allow Fiji to start with a virtualised graphical desktop.

Advantage: No run-time patching is required.

Shortcomings: It is slower than it needs to be because of the overhead of starting the GUI, it is harder to configure, and plugins might get stuck because they wait for user input which never comes.

Example: Here is an example shell script that wraps a macro for use with Xvfb (thanks to Nestor Milyaev!):

export DISPLAY=:1
Xvfb $DISPLAY -auth /dev/null &
(
# the '(' starts a new sub shell. In this sub shell we start the worker processes:

script=$scriptDir"lsmrotate2nrrd.ijm \"dir="$1"&angle-x=$2&angle-y=
$3&angle-z=$4&reverse=$5\" -batch"
$fijiBin -macro $script # running the actual ijm script

wait # waits until all 'program' processes are finished
# this wait sees only the 'program' processes, not the Xvfb process
)

Rewriting as scripts or plugins

The most robust method is to rewrite macros as scripts that do not require interaction with the GUI to begin with. Unfortunately, this is the most involved solution, too, since it usually takes some time to convert macros.