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.
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.
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.
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:
- In the Eclipse File menu, select Import...
- In the dialog that appears, choose General -> Existing Projects into Workspace from the trees
- In the next dialog, choose Select archive file, and Browse... to select
the Simple_JCuda_Plugin_Package.zip file
- After clicking Finish, a new project will appear in your workspace
Compiling the JCuda ImageJ plugin:
- In the Eclipse project tree, right-click the createJarLocal.jardesc file, and
choose Create JAR from the menu
- This will create the Simple_JCuda_Plugin.jar file in
the project directory.
- Copy the Simple_JCuda_Plugin.jar file into the
plugins
directory of ImageJ
Using the JCuda ImageJ plugin:
-
Copy the native libraries for JCuda into the main ImageJ directory.
The files that are required are the
JCudaRuntime-os-arch.ext
and the JCudaDriver-os-arch.ext
. For example,
on 32bit Windows, you need the JCudaRuntime-windows-x86.dll
and JCudaDriver-windows-x86.dll
- Start ImageJ and open an image
-
In the Plugins menu, select
Simple JCuda Plugin -> Run Simple JCuda Plugin...
-
This should invert the image. Or create an error message.
Most likely, an 'UnsatisfiedLinkError'. In this case,
review the project setup, and compare it to the one
described in the general setup section.
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:
- ij.jar: The main ImageJ JAR file, contained in the ImageJ main directory
- jcuda-X.X.X.jar: The main JCuda JAR file. The most recent version
is contained in the archive from the
downloads section
- jcudaUtils-X.X.X.jar: The main JCuda Utilities JAR file. The most
recent version is available in the
utilities section
Minimal set of source files:
- Simple_JCuda_Plugin.java: The main Java source file for the Plugin
- simpleJCudaPluginKernel.cu: The main CUDA source file, containing the
CUDA kernel for the Plugin
Additional files:
- plugins.config: The Plugin configuration file for ImageJ
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:
- Simple_JCuda_Plugin.class: The Java class file, created by compiling the Java source
- simpleJCudaPluginKernel.cu: The CUDA file containing the CUDA source
- plugins.config: The Plugin configuration file
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:
- Start ImageJ and open an image
- In the Plugins menu, select
Simple JCuda Plugin -> Run Simple JCuda Plugin...
- This should invert the image. Or create an error message.
Most likely, an 'UnsatisfiedLinkError'. In this case,
review the project setup, and compare it to the one
described in the general setup section.