GPU-accelerated image processing in ImageJ using CLIJ

View the Project on GitHub clij/clij-docs

CLIJ - GPU-accelerated image processing with ImageJ and Java

CLIJ is a Java library and a ImageJ/Fiji plugin allowing you to run OpenCL GPU accelerated code from Java.

High level API

The high level API of CLIJ becomes accessible from your Java project by linking its maven dependency. Furthermore, it can be used from ImageJs scripting languages such as Groovy and Jython from Fijis script editor. Therefore, the CLIJ update site needs to be activated.

To get started, you need a clij variable containing the CLIJ instance to access the GPU. The following example shows how to do this from ImageJ Jython:

from net.haesleinhuepf.clij import CLIJ;

clij = CLIJ.getInstance();

Afterwards, you can convert ImagePlus objects to ClearCL objects which makes them accessible on the OpenCL device:

imageInput = clij.push(imp);

Furthermore, you can create images, for example with the same size as a given one:

imageOutput = clij.create(imageOutput);

Alternatively, create an image with a given size and a given type:

imageOutput = clij.create([imageInput.getWidth(), imageInput.getHeight()], imageInput.getNativeType());

Inplace operations are not well supported by OpenCL 1.2. Thus, after creating two images, you can call a kernel taking the first image and filling the pixels of second image with data:

clij.op().maximumZProjection(clij, imageInput, imageOutput);

Then, use the show() method of CLIJ to get the image out of the GPU back to view in ImageJ:, "output");

You can also get the result image as ImagePlus:

result = clij.pull(imageOutput);

A list of all clij.op().... methods with example code is available for ImageJ Jython, ImageJ/Java and ImageJ Groovy.

Low level API

In order to call your own files, use the clij.execute() method. Example code (Jython):

# initialize the GPU 
clij = CLIJ.getInstance();

# convert ImageJ image to CL images (ready for the GPU)
inputCLBuffer = clij.push(imp);
outputCLBuffer = clij.create(inputCLBuffer); # allocate memory for result image

# downsample the image stack using ClearCL / OpenCL
clij.execute(DownsampleXYbyHalfTask, "kernels/", "downsample_xy_by_half_nearest", {"src":inputCLBuffer, "dst":outputCLBuffer});

# convert the result back to imglib2 and show it
result = clij.pull(outputCLBuffer);;

# free memory on the GPU - needs to be done explicitly

More examples can be found in the src/main/jython and src/main/java directories.

OpenCL Kernel calls with CLIJ.execute()

The execute function asks for three or four parameters

clij.execute(<Class>, "", "kernelfunction", {"src":image, "dst":image, "more":5, "evenmore":image})

clij.execute("absolute/or/relative/path/", "kernelfunction", {"src":image, "dst":image, "more":5, "evenmore":image})

Type agnostic OpenCL

As jython is a type-agnostic programming language, CLIJ targets bringing the same convenience to OpenCL as well. However, in order to make the executed OpenCL programs image pixel type agnostic, some conventions must be introduced. The conventions are all optional. OpenCL programmers who know how to pass images of a defined type to OpenCL programs using the correct access functions can skip this section.

Back to CLIJ documentation