Skip to content

Commit 7cde994

Browse files
author
haesleinhuepf
committed
updated general pages
1 parent fd12c57 commit 7cde994

8 files changed

+425
-12
lines changed

‎_config.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
title: CLIJ2 (BETA test release)
1+
title: CLIJ2
22
logo: /images/clij2_logo.png
3-
description: CLIJ2 (BETA test release)
3+
description: CLIJ2
44
show_downloads: false
55
google_analytics:
66
theme: jekyll-theme-minimal

‎clij2_transition_notes.md

+29-4
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,31 @@ This document is under construction. Stay tuned.
33

44
CLIJ and CLIJ2 are fully compatible. You can run CLIJ and CLIJ2 command side by side.
55
Thus, there is no immediate need to make the transtion and to change code.
6-
However, support for CLIJ will run out in June 2021.
7-
Until then, code should be adapted to use CLIJ2 instead of CLIJ.
6+
However, CLIJ may no longer be offically supported in June 2021.
7+
It is recommended to update your scripts and programs to use CLIJ2 instead of CLIJ.
8+
9+
When updating ImageJ macro code from CLIJ to CLIJ2, please put a 2 behind CLIJ in this initializing line:
10+
```
11+
run("CLIJ2 Macro Extensions", "cl_device=");
12+
```
13+
14+
Java developers should replace the CLIJ gateway with CLIJ2:
15+
```
16+
CLIJ2 clij2 = CLIJ2.getInstance();
17+
```
18+
19+
Furthermore, all operations are now available directly in the gateway:
20+
```
21+
clij2.gaussianBlur(input, output, sigma, sigma);
22+
```
823

924
## API changes
1025
The application programming interface (API) of CLIJ and CLIJ2 are different in some minor aspects. If you use one of the
1126
following listed methods, you find guidance to transition from CLIJ to CLIJ2 here:
1227

28+
## applyVectorfield
29+
The method applyVectorfield was renamed to applyVectorField.
30+
1331
## maximumSphere, minimumSphere, maximumSliceBySliceSphere, minimumSliceBySliceSphere, meanSphere, meanSliceBySliceSphere, medianBox, medianSphere, MedianSliceBySliceBox and MedianSliceBySliceSphere
1432
For ImageJ macro users, nothing changes.
1533
Users who used the Java/Groovy/Jython API of these methods may have noticed that the API differs from the ImageJ Macro API:
@@ -25,10 +43,13 @@ This API inconsistency has been fixed in CLIJ2. All methods take radus as parame
2543
The method meanIJ was removed in CLIJ2 compared to CLIJ. Use meanSphere2D or meanSphere3D instead.
2644

2745
## maximumXYZProjection
28-
The method maximumXYZProjetion doesn't exist in CLIJ2. Use [maximumXProjection](reference_maximumXProjection.md), [maximumYProjection](reference_maximumYProjection.md) and [maximumZProjection](reference_maximumZProjection.md) instead.
46+
The method maximumXYZProjetion doesn't exist in CLIJ2.
47+
Use [maximumXProjection](https://clij.github.io/clij2-docs/reference_maximumXProjection),
48+
[maximumYProjection](https://clij.github.io/clij2-docs/reference_maximumYProjection) and
49+
[maximumZProjection](https://clij.github.io/clij2-docs/reference_maximumZProjection) instead.
2950

3051
## resliceRadial
31-
[resliceRadial](reference_resliceRadial) has more parameters now. The documentation contains default values.
52+
[resliceRadial](https://clij.github.io/clij2-docs/reference_resliceRadial) has more parameters now. The documentation contains default values.
3253

3354
## resample, scale, translate, affineTransform
3455
In CLIJ, transforms are mixed inverse transforms of the specified transforms.
@@ -70,6 +91,10 @@ Starting at version 2.0.0.0-BETA, these dependencies should be used:
7091
<groupId>net.haesleinhuepf</groupId>
7192
<artifactId>clij-clearcl</artifactId>
7293
</dependency>
94+
<dependency>
95+
<groupId>net.haesleinhuepf</groupId>
96+
<artifactId>clij2_</artifactId>
97+
</dependency>
7398
```
7499

75100

‎dependingViaMaven.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ If you want to access CLIJ from your Java code, it is recommended to depend on C
77
<dependency>
88
<groupId>net.haesleinhuepf</groupId>
99
<artifactId>clij2_</artifactId>
10-
<version>0.27.3</version>
10+
<version>2.0.0.10</version>
1111
</dependency>
1212
```
1313

‎development.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
## Developing using maven
2+
CLIJ2 uses the maven build system. In order to develop CLIJ2, use git to get the recent version and maven to build it:
3+
4+
Clone the clij2 repository
5+
```
6+
git clone https://github.com/clij/clij2
7+
```
8+
9+
Open pom.xml and enter the path of your Fiji installation in the line containing
10+
11+
```
12+
<imagej.app.directory>C:/path/to/Fiji.app
13+
```
14+
15+
Go to the source dir and install it to your Fiji.app
16+
17+
```
18+
cd clij2
19+
mvn install
20+
```
21+
22+
For development it is recommended to use an integrated development environment such as IntelliJ or Eclipse.
23+
24+
[Back to CLIJ documentation](https://clij.github.io/)
25+
26+
[Imprint](https://clij.github.io/imprint)
27+

‎macro_intro.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# CLIJ - GPU-accelerated image processing in ImageJ macro
2+
Image processing in modern GPUs allows for accelerating processing speeds massively.
3+
This page introduces how to do image processing in the graphics processing unit (GPU) using [OpenCL](https://www.khronos.org/opencl/) from ImageJ macro inside [Fiji](http://fiji.sc) using the [CLIJ](https://clij.github.io/) library.
4+
It is not necessary to learn OpenCL itself.
5+
Preprogrammed routines are supposed to do GPU image processing for you with given ImageJ macro programming experience.
6+
The list of preprogrammed routines might be extended depending on the communities needs.
7+
8+
This is how your code might look like if you do GPU based image processing in ImageJ macro:
9+
10+
![Image](images/example.png)
11+
12+
## Installation
13+
Follow the [installation instructions](installationInFiji);
14+
15+
## Activating CLIJs macro extensions
16+
17+
To get started, all ImageJ macros using CLIJ have a line like this at the beginning:
18+
19+
```java
20+
run("CLIJ2 Macro Extensions", "cl_device=");
21+
```
22+
23+
Note: This line may contain the specific name for a GPU.
24+
You can - but you don't have to - specify one.
25+
If none is specified, the system will take the first one found.
26+
If you don't have the named GPU in your computer, another one will be chosen.
27+
You don't have to enter the full name, you can also just specify a part of the name.
28+
In order to run on any `HD` named GPU, change the macro like this:
29+
30+
```java
31+
run("CLIJ2 Macro Extensions", "cl_device=HD");
32+
```
33+
34+
## Transferring images between ImageJ and the GPU
35+
In order to allow images to be processed by the GPU, you need to transfer them into the memory of the GPU.
36+
In order to view images which were processed by the GPU, you need to transfer them back to ImageJ.
37+
The two methods for doing this are called `push(image)` and `pull(image)`.
38+
You can remove a single image from the GPUs memory by using the `release(image)` method.
39+
Finally, you can remove all images from the GPU with the `clear()` method.
40+
In case the destination image doesn't exist, it will be created automatically in the GPU.
41+
Just push an image _A_ to the GPU, process it with destination _B_ and afterwards, you can pull _B_ back from the GPU to ImageJ in order to show it.
42+
43+
Let's have a look at an example which loads an image and blurs it using the push-pull mechanism.
44+
45+
```java
46+
// Get test data
47+
run("T1 Head (2.4M, 16-bits)");
48+
input = getTitle();
49+
getDimensions(width, height, channels, slices, frames);
50+
51+
// Init GPU
52+
run("CLIJ2 Macro Extensions", "cl_device=");
53+
Ext.CLIJ_clear();
54+
55+
// push images to GPU
56+
Ext.CLIJ2_push(input);
57+
58+
// cleanup ImageJ
59+
run("Close All");
60+
61+
// Blur in GPU
62+
Ext.CLIJ2_gaussianBlur3D(input, blurred, 10, 10, 1);
63+
64+
// Get results back from GPU
65+
Ext.CLIJ2_pull(blurred);
66+
67+
// Cleanup by the end
68+
Ext.CLIJ2_clear();
69+
```
70+
71+
To find out, which images are currently stored in the GPU, run the `Ext.CLIJ2_reportMemory();` method.
72+
73+
## Sparing time with GPU based image processing
74+
The overall goal for processing images in the GPU is sparing time.
75+
GPUs can process images faster because they can calculate pixel values of many pixels in parallel.
76+
Furthermore, images in memory of modern GPUs can be accessed faster than in ImageJ.
77+
However, there is a drawback: pushing/pulling the images to/from the GPU takes time.
78+
Thus, overall efficiency can only be achieved if whole pipelines are processed in the GPU.
79+
Furthermore, repeatedly using the same operations on a GPU pays off because operations are cached. Reusing them is faster than using other methods.
80+
81+
Let's compare the `Mean 3D` filter of ImageJ with it's counterpart in CLIJ.
82+
The example macro is [benchmarking.ijm](https://github.com/clij/clij-docs/tree/master/src/main/macro/benchmarking.ijm).
83+
It executes both operations ten times and measures the time each operation takes.
84+
This is just an excerpt of the macro:
85+
86+
```java
87+
// Local mean filter in CPU
88+
for (i = 1; i <= 10; i++) {
89+
time = getTime();
90+
run("Mean 3D...", "x=3 y=3 z=3");
91+
print("CPU mean filter no " + i + " took " + (getTime() - time));
92+
}
93+
```
94+
95+
```java
96+
// push images to GPU
97+
time = getTime();
98+
Ext.CLIJ2_push(input);
99+
Ext.CLIJ2_push(blurred);
100+
print("Pushing two images to the GPU took " + (getTime() - time) + " msec");
101+
102+
// Local mean filter in GPU
103+
for (i = 1; i <= 10; i++) {
104+
time = getTime();
105+
Ext.CLIJ2_mean3DBox(input, blurred, 3, 3, 3);
106+
print("GPU mean filter no " + i + " took " + (getTime() - time));
107+
}
108+
109+
// Get results back from GPU
110+
time = getTime();
111+
Ext.CLIJ2_pull(blurred);
112+
print("Pullning one image from the GPU took " + (getTime() - time) + " msec");
113+
```
114+
115+
When executing the macro on an Intel Core i7-8565U CPU with a built-in Intel UHD Graphics 620 GPU (Windows 10, 64 bit), the output is:
116+
117+
```java
118+
CPU mean filter no 1 took 3907 msec
119+
CPU mean filter no 2 took 3664 msec
120+
CPU mean filter no 3 took 3569 msec
121+
CPU mean filter no 4 took 3414 msec
122+
CPU mean filter no 5 took 2325 msec
123+
CPU mean filter no 6 took 2752 msec
124+
CPU mean filter no 7 took 2395 msec
125+
CPU mean filter no 8 took 2633 msec
126+
CPU mean filter no 9 took 2543 msec
127+
CPU mean filter no 10 took 2610 msec
128+
Pushing one image to the GPU took 11 msec
129+
GPU mean filter no 1 took 489 msec
130+
GPU mean filter no 2 took 27 msec
131+
GPU mean filter no 3 took 27 msec
132+
GPU mean filter no 4 took 28 msec
133+
GPU mean filter no 5 took 29 msec
134+
GPU mean filter no 6 took 39 msec
135+
GPU mean filter no 7 took 34 msec
136+
GPU mean filter no 8 took 29 msec
137+
GPU mean filter no 9 took 30 msec
138+
GPU mean filter no 10 took 31 msec
139+
Pulling one image from the GPU took 47 msec
140+
```
141+
142+
Thus, on the **CPU it takes 30 seconds**, while using the **GPU it just takes 0.8 seconds**. Let's execute it again.
143+
144+
```java
145+
CPU mean filter no 1 took 2254 msec
146+
CPU mean filter no 2 took 2187 msec
147+
CPU mean filter no 3 took 2264 msec
148+
CPU mean filter no 4 took 2491 msec
149+
CPU mean filter no 5 took 2915 msec
150+
CPU mean filter no 6 took 2299 msec
151+
CPU mean filter no 7 took 2401 msec
152+
CPU mean filter no 8 took 2441 msec
153+
CPU mean filter no 9 took 2493 msec
154+
CPU mean filter no 10 took 2588 msec
155+
Pushing one image to the GPU took 9 msec
156+
GPU mean filter no 1 took 30 msec
157+
GPU mean filter no 2 took 28 msec
158+
GPU mean filter no 3 took 30 msec
159+
GPU mean filter no 4 took 39 msec
160+
GPU mean filter no 5 took 34 msec
161+
GPU mean filter no 6 took 34 msec
162+
GPU mean filter no 7 took 34 msec
163+
GPU mean filter no 8 took 32 msec
164+
GPU mean filter no 9 took 40 msec
165+
GPU mean filter no 10 took 32 msec
166+
Pulling one image from the GPU took 43 msec
167+
```
168+
169+
On the **CPU it still takes 24 seconds**, while using the **GPU it goes down to 0.4 seconds**.
170+
The additional speedup comes from the caching mechanism mentioned above.
171+
172+
**Heureka, we can spare 90% of the time by executing the operation on the GPU!**
173+
And this works on a small laptop without dedicated GPU. This example should just motivate you to test your workflow on a GPU and guide you how to evaluate its performance.
174+
175+
Side note: ImageJs mean filter runs _inplace_. That means the result is stored in the same memory as the input image.
176+
With every iteration in the for loop, the image becomes more and more blurry.
177+
The OpenCL operation in the GPU always starts from the _input_ image and puts its result in the _blurred_ image.
178+
Thus, the resulting images will look different.
179+
Be a sceptical scietist when processing images in the GPU.
180+
Check that the workflow is indeed doing the right thing.
181+
This is especially important when working with experimental software.
182+
183+
This is the view on results from the mean filter on CPU and GPU together with the difference image of both:
184+
185+
![Image](images/visual_CPU_GPU_comparison.png)
186+
187+
In presented case, have a look at [mean.ijm](https://github.com/clij/clij-docs/blob/master/src/main/macro/mean.ijm) to see how different the results from CPU and GPU actually are.
188+
In some of the filters, I observed small differences between ImageJ and OpenCL especially at the borders of the images. This is related to the fact that CLIJ contains new implementations of operations in ImageJ. There is a large number of [unit tests in the library](https://github.com/clij/clij/tree/master/src/test/java/net/haesleinhuepf/clij/macro/modules),
189+
ensuring these differences are small and in case they appear, they mostly influence image borders.
190+
191+
[Back to CLIJ documentation](https://clij.github.io/)
192+
193+
[Imprint](https://clij.github.io/imprint)

0 commit comments

Comments
 (0)