A basic example project for a simple ImageJ plugin that uses JCuda.
This project shows how to create an ImageJ1 plugin. As of 04/2018, ImageJ is in the process of being updated and refactored, to be released as ImageJ2. The new version is built on a different infrastructure for handling plugins. However, ImageJ plugins are still supposed to work in ImageJ2. For details about the differences between ImageJ1 and ImageJ2, refer to the ImageJ FAQ.
Currently, the recommended way to obtain an up-to-date ImageJ installation
is via Fiji. Just download the distribution for
your operating system and unpack it. Fiji/ImageJ will then be available
Cloning the repository
Create a local clone of this project by calling
git clone https://github.com/jcuda/jcuda-imagej-example.git
Building the plugin JAR
The cloned project can be opened and edited in any IDE (e.g. Eclipse, NetBeans, IntelliJ...). However, the preferred way to build the final plugin JAR is via Apache Maven.
In order to build the plugin JAR, change into the root directory of the project and execute
mvn clean package
Note that the resulting JAR file has a name that is different from the
default name that Maven would assign to it: In order to properly be recognized
as an ImageJ plugin JAR, it is named
Copy the resulting
/target/JCuda_ImageJ_Example_Plugin.jar file into
Fiji.app/plugins directory of your Fiji/ImageJ installation.
Adding the dependencies
The plugin JAR has dependencies to other JAR files. The following command can be used to collect all the dependencies:
This will copy all required dependencies into the
of the project. Copy these JARs into the
Fiji.app/jars directory of your
Note: These dependencies will only include the platform-specific JAR files.
For example, on Windows, they will include the
In order to support other operating systems, the corresponding JAR files
jcuda-natives-0.9.0d-linux-x86_64.jar) will have to be added
manually for the respective Fiji/ImageJ installation.
Using the plugin
After the JAR files for the plugin have been added, it may be used inside ImageJ: Start ImageJ, load an image, and select
Plugins > JCuda ImageJ Example > Run JCuda ImageJ Example Plugin...
from the menu bar. This will execute the CUDA kernel internally, and show the resulting image, which is simply an inversion of the original image.
Building your own plugin based on the example
Note that the plugin that is shown in this project is very simple and minimalistic. In order to develop more complex plugins, refer to the ImageJ Wiki about Plugins and the general ImageJ Development Documentation.
In order to start first experiments, you may use this project as a template. The project directory structure and the most relevant files are summarized here:
jcuda-imagej-example/ pom.xml src/ main/ java/ JCuda_ImageJ_Example_Plugin.java resources/ JCudaImageJExampleKernel.cu plugins.config
The following is a short summary of the information that is contained in each of these files, and how it may be changed for your own plugin:
pom.xml contains the Maven names for the project. For your own
plugin, you should adjust the
<artifactId> in the
pom.xml file. For example:
pom.xml also defines the name of the resulting plugin JAR file.
For your own plugin, you could change it as shown in this example:
<properties> <imagej.plugin.name>My_ImageJ_Plugin</imagej.plugin.name> ... </properties>
Note: Due to some constraints of ImageJ, the plugin name must contain
'_' underscore character!
This file contains the implementation of the plugin functionality.
Specifically, it contains a class that implements the ImageJ
interface, which consists of two methods:
public int setup(String arg, ImagePlus imagePlus): This method is called once, when the plugin is loaded. It will initialize the JCuda library and load the CUDA kernel function from the
public void run(ImageProcessor imageProcessor): This method performs the actual computation. It receives an image and extracts the pixel data. The pixel data is then copied to the CUDA device. The kernel function is executed and modifies the data. The modified data is then copied back into the image.
For details about these methods and further information about the different types of plugins, refer to the ImageJ Development Documentation.
Note: Due to some constraints of ImageJ, the class name must contain an
'_' underscore character!
This file contains the actual CUDA kernel code. The file is loaded in the
JCuda_ImageJ_Example_Plugin class, where the kernel is compiled and
the actual kernel function is initialized.
This file basically defines where in the Plugins menu of ImageJ the plugin will appear. The relevant entry for the JCuda example plugin is this:
Plugins>JCuda ImageJ Example, "Run JCuda ImageJ Example Plugin...", JCuda_ImageJ_Example_Plugin("run")
The first part defines the menu structure. The last part,
defines the class name of the plugin implementation.