pyclesperanto-prototype 0.10.4

GPU-accelerated image processing in python using OpenCL

py-clEsperanto

py-clEsperanto is a prototype for clEsperanto - a multi-platform multi-language framework for GPU-accelerated image processing. It uses OpenCL kernels from CLIJ.

For users convenience, there are code generators available for napari and Fiji.

Reference

The full reference is available as part of the CLIJ2 documentation.

Installation

• Get a python environment, e.g. via mini-conda. If you never used python/conda environments before, please follow the instructions here first.
• Install pyopencl.

If installation of pyopencl for Windows fails, consider downloading a precompiled wheel (e.g. from here ) and installing it manually. Note that "cl12" and "cp38" in the filename matter: They allow you using OpenCL 1.2 compatible GPU devices from Python 3.8.

pip install pyopencl-2019.1.1+cl12-cp37-cp37m-win_amd64.whl

Alternatively, installing via conda also works:

conda install -c conda-forge pyopencl=2020.3.1

Afterwards, install pyclesperanto:

pip install pyclesperanto-prototype

Troubleshooting installation

If you receive an error like

DLL load failed: The specified procedure could not be found.

Try downloading and installing a pyopencl with a lower cl version, e.g. cl12 : pyopencl-2020.1+cl12-cp37-cp37m-win_amd64

Example code

A basic image procressing workflow loads blobs.gif and counts the number of gold particles:

import pyclesperanto_prototype as cle

from skimage.io import imread, imsave

# initialize GPU
cle.select_device("GTX")
print("Used GPU: " + cle.get_device().name)

# load data
image = imread('https://imagej.nih.gov/ij/images/blobs.gif')
print("Loaded image size: " + str(image.shape))

# push image to GPU memory
input = cle.push(image)
print("Image size in GPU: " + str(input.shape))

# process the image
inverted = cle.subtract_image_from_scalar(image, scalar=255)
blurred = cle.gaussian_blur(inverted, sigma_x=1, sigma_y=1)
binary = cle.threshold_otsu(blurred)
labeled = cle.connected_components_labeling_box(binary)

# The maxmium intensity in a label image corresponds to the number of objects
num_labels = cle.maximum_of_all_pixels(labeled)

# print out result
print("Num objects in the image: " + str(num_labels))

# for debugging: print out image
print(labeled)

# for debugging: save image to disc
imsave("result.tif", cle.pull(labeled))

Example gallery

	Select GPU
	Counting blobs
	Voronoi-Otsu labeling
	3D Image segmentation
	Cell segmentation based on membranes
	Detecting beads and measuring their size
	Label statistics
	Parametric maps
	Crop and paste images
	Inspecting 3D image data
	Rotation, scaling, translation, affine transforms
	Multiply vectors and matrices
	Matrix multiplication
	Working with spots, pointlist and matrices
	Mesh between centroids
	Mesh between touching neighbors
	Mesh with distances
	Mesh nearest_neighbors
	Neighborhood definitions
	Tissue neighborhood quantification
	Neighbors of neighbors
	Voronoi diagrams
	Shape descriptors based on neighborhood graphs
	Tribolium morphometry + Napari
	Tribolium morphometry
	napari+dask timelapse processing

Technical insights

	Browsing operations
	Interactive widgets
	Automatic workflow optimization
	Exploring and switching between GPUs
	Interoperability with cupy

Related projects

	napari-pyclesperanto-assistant: A graphical user interface for general purpose GPU-accelerated image processing and analysis in napari.
	napari-oclrfc: GPU-accelerated Random Forest Classifiers for pixel and labeled object classification

Benchmarking

We implemented some basic benchmarking notebooks allowing to see performance differences between pyclesperanto and some other image processing libraries, typically using the CPU. Such benchmarking results vary heavily depending on image size, kernel size, used operations, parameters and used hardware. Feel free to use those notebooks, adapt them to your use-case scenario and benchmark on your target hardware. If you have different scenarios or use-cases, you are very welcome to submit your notebook as pull-request!

• Affine transforms
• Gaussian blur
• Convolution
• Otsu's thresholding
• Connected component labeling
• Extend labels
• Statistics of labeled pixels / regionprops
• Histograms
• Matrix multiplication
• Pixel-wise comparison
• Intensity projections
• Axis transposition

See also

There are other libraries for code acceleration and GPU-acceleration for image processing.

• numba
• cupy
• cucim
• clij

Feedback welcome!

clEsperanto is developed in the open because we believe in the open source community. See our community guidelines. Feel free to drop feedback as github issue or via image.sc