gputools 0.3.1
OpenCL accelerated volume processing
Requires Python: >=3.9
Keywords: science, image-processing, opencl, gpu

# gputools - OpenCL accelerated volume processing in Python

[![CI](https://github.com/maweigert/gputools/actions/workflows/ci.yml/badge.svg)](https://github.com/maweigert/gputools/actions/workflows/ci.yml)

GPU accelerated 2D/3D image processing, e.g. for microscopy, via OpenCL (i.e. works on both NVIDIA and non-NVIDIA devices).

* convolutions
* denoising
* synthetic noise
* ffts (simple wrapper around [reikna](https://github.com/fjarri/reikna))
* affine transforms

Built on the excellent [pyopencl](https://documen.tician.de/pyopencl/) bindings.

Some examples of processing tasks and their respective runtime (`tests/benchmark/benchmark.py`):

Task | Image Size/type | CPU[1] | GPU[2] | GPU (w/o transfer)
----|----| ----| ---- | ----
Mean filter 7x7x7| (128, 1024, 1024) uint8 | 1708 ms | 22 ms | 5 ms
Median filter 3x3x3| (128, 1024, 1024) uint8 | 37591 ms | 49 ms | 31 ms
Gaussian filter 5x5x5| (128, 1024, 1024) float32 | 4536 ms | 86 ms | 19 ms
Zoom/Scale 2x2x2| (128, 1024, 1024) uint8 | 18433 ms | 133 ms | -
NLM denoising| (64, 256, 256) float32 | 21109 ms | 105 ms | -
FFT (pow2)| (128, 1024, 1024) complex64 | 3418 ms | 156 ms | 21 ms

	[1] AMD Ryzen Threadripper PRO 9965WX 
	[2] NVIDIA GeForce RTX 5090 
	
### Requirements

- Python 3.9+
- a working OpenCL environment (check with `clinfo`).

### Installation

```
pip install gputools
```
Or the development version:

```
pip install git+https://github.com/maweigert/gputools
```

Check if basic stuff is working:

```
python -m gputools
```

#### Troubleshooting

If you experience installation issues, this might be due to `pyopencl` not
being properly installed. The easiest way to get a working pyopencl is via conda:
```
conda install -c conda-forge pyopencl
```

### Usage

Docs are still to be done ;)

Most of the methods work on both numpy arrays or GPU memory objects (gputools.OCLArrays/OCLImage). The latter saving the memory transfer (which e.g. for simple convolutions accounts for the main run time)

#### Convolutions

* 2D-3D convolutions
* separable convolutions
* fft based convolution
* spatially varying convolutions

```python

import gputools

d = np.zeros((128,128), np.float32)
d[64,64] = 1.
h = np.ones((17,17))
res = gputools.convolve(d,h)

```

```python
d = np.zeros((128,128,128), np.float32)
d[64,64,64] = 1.
hx,hy,hz = np.ones(7),np.ones(9),np.ones(11)
res = gputools.convolve_sep3(d,hx,hy,hz)

```

#### Denoising

bilateral filter, non local means

```python
...
d = np.zeros((128,128,128), np.float32)
d[50:78,50:78,50:78:2] = 4.
d = d+np.random.normal(0,1,d.shape)
res_nlm = gputools.denoise.nlm3(d,2.,2,3)
res_bilat = gputools.denoise.bilateral3(d,3,4.)

```

#### Perlin noise

fast 2d and 3d perlin noise calculations

```python
gputools.perlin3(size = (256,256,256), scale = (10.,10.,10.))
```


#### Transforms
scaling, translate, rotate, affine...


```python
gputools.transforms.scale(d,.2)
gputools.transforms.rotate(d,axis = (64,64,64),angle = .3)
gputools.transforms.shift(d,(10,20,30))
...
```

#### fft
wraps around reikna

```python
gputools.fft(d)
gputools.fft(d, inverse = True)
```

### Configuration

Some configuration data (e.g. the default OpenCL platform and devic) can be changed in the config file "~/.gputools" (create it if necessary)  
```
#~/.gputools

id_platform = 0
id_device = 1
```
See 
```python
gputools.config.defaults
```
for available keys and their defaults.

Alternatively, the used OpenCL Device can be set via the environment variables `gputools_id_device`,  `gputools_id_platform`, and `gputools_use_gpu` (variables present in the config file will take precendence, however).