Metadata-Version: 2.4
Name: gputools
Version: 0.3.0
Summary: OpenCL accelerated volume processing
Author-email: Martin Weigert <martin.weigert@epfl.ch>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/maweigert/gputools
Keywords: science,image-processing,opencl,gpu
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: scipy
Requires-Dist: numpy
Requires-Dist: pyopencl>=2016.1
Requires-Dist: reikna>=0.8.0
Dynamic: license-file

# 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)

This package aims to provide GPU accelerated implementations of common volume processing algorithms to the python ecosystem, such as  

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

via OpenCL and 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)[3]
----|----| ----| ---- | ----
Mean filter 7x7x7| (128, 1024, 1024) uint8 | 2627 ms | 99 ms | 24 ms
Median filter 3x3x3| (128, 1024, 1024) uint8 | 59750 ms | 346 ms | 252 ms
Gaussian filter 5x5x5| (128, 1024, 1024) float32 | 9594 ms | 416 ms | 101 ms
Zoom/Scale 2x2x2| (128, 1024, 1024) uint8 | 61829 ms | 466 ms | -
NLM denoising| (64, 256, 256) float32 | 52736 ms | 742 ms | -
FFT (pow2) | (128, 1024, 1024) complex64 | 13831 ms | 615 ms | 69 ms

	[1] Xeon(R) CPU E5-2630 v4 using numpy/scipy functions
	[2] NVidia Titan X using gputools
	[3] as [2] but without CPU->GPU->CPU transfer
	
### 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).




