How to create an ImageJ Plugin using JCuda



This page contains a description of how to create a Plugin for ImageJ which uses JCuda for efficient manipulation of image data on the GPU.


NOTE: Some parts of this tutorial may be out-dated, but will be updated as soon as possible.


Overview



The files required for a quick start, including the necessary JAR files and a template for a simple JCuda ImageJ plugin are contained in this archive: Simple_JCuda_Plugin_Package.zip. Note that the files in this package are unversioned, and thus only serve as a quick start template. Please see the Project setup section for more information about how to use this file.


Introduction



This website shows the basic setup of a simple ImageJ plugin that uses JCuda. If you have suggestions for improvements of the setup and project structure, please contact me.

ImageJ is the leading public domain Java based image processing program. It is possible to extend ImageJ with own plugins due to its open and well-documented architecture. For general information about ImageJ, please consult the following resources: This tutorial assumes that you have installed ImageJ as described on the ImageJ home page.


General setup


First of all, download the JCuda archive for your operating system from the downloads section. Additionally, you will need the JCuda utilities library from the utilities section.

The JAR files of JCuda and the Utilities JAR file must be copied into the \plugins\jars directory of the main ImageJ directory, so that they can be found by the Plugin JAR file at runtime.

Additionally, ImageJ must be able to locate the native JCuda libraries when the Plugin should be executed. The JCuda archive contains the .DLL files for Windows, the .SO files for Linux, or the .JNILIB files for MacOS, respectively. The most simple solution is to unpack these native libraries into the main ImageJ directory. Alternatively, they may be put into a directory that is visible via an environment variable.


Project setup



Quick start


The Simple_JCuda_Plugin_Package.zip contains all files that are required to quickly create an Eclipse project on 32bit Windows for the first, simple JCuda ImageJ plugin. For other IDEs, operating systems and architectures, please follow the manual setup steps.

Importing the project from the quick start package into Eclipse:

Compiling the JCuda ImageJ plugin:

Using the JCuda ImageJ plugin:


Manual setup


Required software:

The following files are required for a minimal JCuda ImageJ Plugin. All these files are contained in the Simple_JCuda_Plugin_Package.zip.

Required JAR files: Minimal set of source files: Additional files:

Compiling the Java source file

The main Java source file may be compiled as usual in your IDE. Note that the required JAR files have to be added to the build path. You may also compile the file from the command line:
    javac -cp ".;jcuda.jar;jcudaUtils.jar;ij.jar" Simple_JCuda_Plugin.java
This will create the Simple_JCuda_Plugin.class file.


Compiling the CUDA source file

The CUDA source file has to be compiled, to create a CUBIN (CUDA binary). This file will contain the CUDA kernel. It will be loaded and executed by the Plugin at runtime. To compile the CUDA source file and to create the CUBIN file, execute the following command line:
    nvcc -cubin simpleJCudaPluginKernel.cu -o simpleJCudaPluginKernel.cubin
This will create the simpleJCudaPluginKernel.cubin file.

Depending on the architecture of the target system (32/64 bit) and the compute capability of the CUDA card that will be used, it may be necessary to specify the target version for the CUBINS. For example, to compile for a 64 bit system with compute capability 1.1, the command is     nvcc -m64 -arch sm_11 -cubin simpleJCudaPluginKernel.cu -o simpleJCudaPluginKernel.cubin
Further information about compiling CUBIN files may be found in the NVCC documentation that comes with the NVIDIA CUDA Toolkit.


Creating the Plugin configuration file

The final archive for the Plugin must contain a file called plugins.config. This file will contain the information about the menu entries that sohould be added for the Plugin in ImageJ. For the first test, you may use the plugins.config which is contained in the Simple_JCuda_Plugin_Package.zip. For more information about the contents of this file, see the ImageJ JAR Plugin demo.


Putting it all together

You now should have all required files for the Plugin: It is recommended to copy these files into a single directory. The final Plugin JAR file may then be created with the following command line:
    jar cvfM Simple_JCuda_Plugin.jar *
This will create the Simple_JCuda_Plugin.jar file. Copy this file into the plugins directory of ImageJ.


Using the JCuda ImageJ plugin: