New to ImageJ, can I use it as a library(API) without GUI?

Hi ,

I am new to ImageJ, and I would like to use it as a library in my Java application that has no GUI, just Linux command line.

I tried to execute a simple example on “run” command :, "Brightness/Contrast..." , "minimum=91.6406 maximum=163.3594");

but I get the error:

      No X11 DISPLAY variable was set, but this program performed an operation which requires it.

I tried setting Java properties to but still getting error:


at java.awt.GraphicsEnvironment.checkHeadless(

So do we need to have available GUI in order for ImageJ to work?



Hello Zazhil-ha -

The answer to the question in the title of you post, "Can I use [ImageJ]
as a library(API) without GUI? " is “Yes, but …”

First the “Yes” part. Here is a simple, free-standing java program that
uses ImageJ classes and methods to do some trivial image analysis:

import ij.IJ;
import ij.ImagePlus;
import ij.process.ImageProcessor;

public class ImageJAsApi {
  public static void main(final String... args) {
    ImagePlus imp = IJ.createImage ("my image", "8-bit ramp", 512, 512, 1);
    System.out.println ("imp.getClass().getName() = " + imp.getClass().getName());
    ImageProcessor ip = imp.getProcessor();
    System.out.println ("ip.getClass().getName() = " + ip.getClass().getName());
    System.out.println ("ip.getWidth() = " + ip.getWidth() + ", ip.getHeight() = " + ip.getHeight());
    double sum = 0.0;
    double cnt = 0.0;
    for (int i = 0; i < ip.getWidth(); i++)
      for (int j = 0; j < ip.getHeight(); j++) {
	sum += ip.getPixel (i, j);
    double mean = sum / cnt;
    System.out.println ("mean = " + mean);
    System.out.println ("cnt = " + cnt);

You must include the ImageJ jars in the classpath you give javac.
I use the Fiji distribution of ImageJ, and I compile as follows:

And I run the compiled java program analogously:

For completeness, the output is:

The “but” part is that many of the facilities offered by ImageJ depend on
running inside of an instance of the ImageJ framework, so the simple
approach illustrated above won’t always work.

(I’m not aware of any documentation that makes clear which bits of
ImageJ depend on having an instance of the ImageJ framework
and/or a gui, so, while you can use ImageJ as a library for many
operations, expect some trial and error to find out which pieces work.)

Alternatively, along the lines you experimented with, ImageJ does
have support for running in a “headless” mode. See:

ImageJ Headless

This talks about how to run headless, and also some of the limitations.
Quoting from this web page:

This would seem to explain the error message you are seeing.

This same web page explains how to pass the “–headless” argument
to ImageJ when you launch it to address the issue you see (as well
as limitations of this approach).

It’s something of a semantic distinction, but when you run headless,
you’re not really using ImageJ as a library, but, rather, running a
nearly full-blown instance of the ImageJ framework that happens
not to have a gui. (This might be what you want.)

(Lastly, you can run a regular ImageJ instance, gui and all, and run
your code inside of it as a script or plugin, and – if you don’t need
user input – simply ignore whatever gets displayed on the screen.)

Thanks, mm

Thank you very much for your help mm, your answer is very useful