Skip to content

maweigert/gputools

Repository files navigation

gputools - OpenCL accelerated volume processing in Python

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)
  • affine transforms

via OpenCL and the excellent 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 2.7 / 3.5+
  • a working OpenCL environment (check with clinfo).

Installation

pip install gputools

Or the developmental version:

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

Check if basic stuff is working:

python -m gputools

Troubleshooting

If you experience installation issues in Windows, this might be due to pyopencl not
being properly installed.

  1. Download the correct pyopencl wheel for your platform
  2. Install it via pip install pyopencl‑2020.2.2+cl21‑cp38‑cp38‑win_amd64.whl

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
import gputools

d = np.zeros((128,128), np.float32)
d[64,64] = 1.
h = np.ones((17,17))
res = gputools.convolve(d,h)
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

...
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

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

Transforms

scaling, translate, rotate, affine...

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

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

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

Troubleshooting

pyopencl: _cffi.so ImportError

If you see a

ImportError: _cffi.so: undefined symbol: clSVMFree

after importing gputools, this is most likely a problem of pyopencl being installed with an incorrent OpenCL version. Check the OpenCL version for your GPU with clinfo (e.g. 1.2):

clinfo | grep Version

and install pyopencl manually while enforcing your opencl version:

# uninstall pyopencl
pip uninstall pyopencl cffi
  
# get pyopencl source
git clone https://github.com/pyopencl/pyopencl.git
cd pyopencl
python configure.py
	
# add in siteconf.py the line
# CL_PRETEND_VERSION = "1.2"
echo 'CL_PRETEND_VERSION = "1.2"' >> siteconf.py

pip install .

where e.g. "1.2" is your version of OpenCL.