nicost / clij-opencl-kernels

clij-opencl-kernels

This repository contains a collection of OpenCL kernels for generic image processing. The CLIJ is build on top of it allowing ImageJ / Fiji users in doing GPU-accelerated image processing without the need for learning OpenCL.

If you use it, please cite it:

Robert Haase, Loic Alain Royer, Peter Steinbach, Deborah Schmidt, Alexandr Dibrov, Uwe Schmidt, Martin Weigert, Nicola Maghelli, Pavel Tomancak, Florian Jug, Eugene W Myers. CLIJ: GPU-accelerated image processing for everyone. BioRxiv preprint. https://doi.org/10.1101/660704

Why a custom OpenCL-dialect?

OpenCL offers several pixel types, such as uint8, unit16 and float. Theoretically, one has to write OpenCL-kernels specifically for given input- and output-images, such as a kernel for adding images of type float resulting in a float image and a kernel for adding image of type uint8 resulting in an image of type float. Furthermore, OpenCL defines images and buffers. However, as both are arrays of pixel intensities in memory, we wanted to access them in a unified way. As this would result in a ridiculous large number of individual kernel implementations, we used a dialect where placeholders such as DTYPE_OUT represent the pixel type of the output image.

List of placeholders

The following list of placeholders are used at the moment:

Place holder	Replacement during runtime
CONVERT_DTYPE_IN	clij_convert_char_sat clij_convert_uchar_sat clij_convert_short_sat clij_convert_ushort_sat clij_convert_int_sat clij_convert_uint_sat clij_convert_float_sat	Convert any number to a given type.
CONVERT_DTYPE_OUT
DTYPE_IMAGE_IN_2D	__read_only image2d_t __global char* __global uchar* __global short* __global ushort* __global float*	Two dimensional input image type definition
DTYPE_IMAGE_IN_3D	__read_only image3d_t __global char* __global uchar* __global short* __global ushort* __global float*	Three dimensional input image type definition
DTYPE_IMAGE_OUT_2D	__write_only image2d_t __global char* __global uchar* __global short* __global ushort* __global float*	Two dimensional output image type definition
DTYPE_IMAGE_OUT_3D	__write_only image3d_t __global char* __global uchar* __global short* __global ushort* __global float*	Three dimensional output image type definition
DTYPE_IN	char uchar short ushort float	Pixel type definition
DTYPE_OUT
GET_IMAGE_DEPTH	constant number	Image size in Z
GET_IMAGE_HEIGHT	constant number	Image size in Y
GET_IMAGE_WIDTH	constant number	Image size in X
READ_IMAGE_2D	read_imageui read_imagef read_buffer2dc read_buffer2duc read_buffer2di read_buffer2dui read_buffer2df	Read pixel intensity from a given position
READ_IMAGE_3D	read_imageui read_imagef read_buffer3dc read_buffer3duc read_buffer3di read_buffer3dui read_buffer3df	Read pixel intensity from a given position
WRITE_IMAGE_2D	write_imageui write_imagef write_buffer2dc write_buffer2duc write_buffer2di write_buffer2dui write_buffer2df	Write pixel intensity to a given position
WRITE_IMAGE_3D	write_imageui write_imagef write_buffer3dc write_buffer3duc write_buffer3di write_buffer3dui write_buffer3df	Write pixel intensity to a given position

Known issues

• The described OpenCL dialect has a drawback: Input images all need to be of the same type and output images have to be of the same type. As this assumption might be violated in practice, we are working on an new version of the dialect to be release in summer 2020.
• Some of the placeholders represent image size in x/y/z. This results in performance drop in case many images of different size are processed as individual kernels need to be implemented. We have this in mind for the summer 2020 update of the OpenCL-dialect.
• Image dimensionality is limited to three dimensions.

Deprecation note

The opencl-kernels presented here will be replaced by Summer 2020. Background is an upcoming update of the used OpenCL dialect. If you plan to build your software directly on our OpenCL kernels, you should consider waiting for this update. You can follow development live on the development branch.