How to create an ImageJ Plugin using JCuda





The JCuda/ImageJ example has been moved to https://github.com/jcuda/jcuda-imagej-example

The information presented here refers to earlier JCuda- and ImageJ versions and may not work with the latest versions of JCuda and ImageJ.













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.


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 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 (or into the \jars directory if you are using Fiji), 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 .DYLIB files for MacOS, respectively. The most simple solution is to unpack these native libraries into the main ImageJ- or Fiji 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 for the first, simple JCuda ImageJ plugin. For other IDEs 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 example plugin from the Simple_JCuda_Plugin_Package.zip uses the KernelLauncher class from the utilities package to compile the CUDA source code into a PTX file at runtime. Alternatively, you may also compile the CUDA files into a PTX- or CUBIN file. Basic information about the creation of PTX- and CUBIN files may be found in the general JCuda Tutorial. Further information about compiling CUDA 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: