CLIJ is a Java library and a ImageJ/Fiji plugin allowing you to run OpenCL GPU accelerated code from Java.
The high level API of CLIJ becomes accessible from your Java prpject 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 wich 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:
clij.show(imageOutput, "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.
In order to call your own kernel.cl
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
resultStack = clij.execute(DownsampleXYbyHalfTask, "kernels/downsampling.cl", "downsample_xy_by_half_nearest", {"src":inputCLBuffer, "dst":outputCLBuffer});
# convert the result back to imglib2 and show it
result = clij.pull(resultStack);
result.show();
More examples can be found in the src/main/jython and src/main/java directories.
The execute function asks for three or four parameters
clij.execute(<Class>, "filename_open.cl", "kernelfunction", {"src":image, "dst":image, "more":5, "evenmore":image})
clij.execute("absolute/or/relative/path/filename_open.cl", "kernelfunction", {"src":image, "dst":image, "more":5, "evenmore":image})
- An optional class file as an anchor to have a point for where to start searching for the program file (second parameter).
- The open.cl program file will be searched for in the same folder where the class (first parameter) is defined. In the first example above, this class comes with the dependency FastFuse. Alternatively, an absolute path can be proveded if there is no class given as first parameter. In case a relative path is given, it must be relative from the current dir of Fiji.
- The name of the kernel function defined in the program file
- A dictionary with all the parameters of the kernel function, such as "src" and "dst". It is recommended to have at least a "src" and a "dst" parameter, because CLIJ derives image data types and global space from these parameters.
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.
- Instead of using functions like
read_imagef()
,write_imagef()
,write_imageui()
etc., it is recommended to useWRITE_IMAGE_2D()
,WRITE_IMAGE_3D()
,READ_IMAGE_2D()
andREAD_IMAGE_3D()
function calls. These function calls will be replaced during runtime with the function accessing the correct image data type. However, in order to allow CLIJ to detect the right image data type, there must be at least two image type parameters containing "src", "dst", "input", or "output" in their parameter names. CLIJ will then for example detect the type of an image parameter called "src_image" and replace all calls toREAD_IMAGE_2D()
with the respective call toimage_readui()
orimage_readf()
calls. - Variables inside OpenCL programs can be typed with
DTYPE_IN
andDTYPE_OUT
instead offloat
orint4
in order to make the OpenCL code type agnostic.