py-clesperanto

pyclesperanto is the python package of clEsperanto - a multi-language framework for GPU-accelerated image processing. It relies on a familly of OpenCL kernels originated from CLIJ. This package is developped in python and C++ wrapped using PyBind11, and uses the C++ CLIc library as a processing backend.

Reference and examples

An in-depth API reference and package documentation can be found here, and several demonstration notebook on how to use the library and major functionnality are available in the demos folder

Installation

Get a conda/python environment, e.g. via mamba-forge.
- If you never used python/conda environments before, please follow these instructions first.
Create a new environment and activate it:

mamba create --name cle
mamba activate cle

Install pyclesperanto using mamba / conda:

mamba install -c conda-forge pyclesperanto

MacOS users may need to install the following package: mamba install -c conda-forge ocl_icd_wrapper_apple Linux users may need to install the following package: mamba install -c conda-forge ocl-icd-system

NOTE: It is also possible to install pyclesperanto with pip

Troubleshooting: Graphics cards drivers

In case you encounter one of the following error messages:

"ImportError: DLL load failed while importing cl: The specified procedure could not be found" see also
"clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR"
"No backend available. Please install either OpenCL or CUDA on your system."
"No device available. Please install either OpenCL or CUDA on your system."

please install recent drivers for your graphics card and/or OpenCL device. Select the right driver source depending on your hardware from this list:

Linux user may have to install packages such as intel-opencl-icd or rocm-opencl-runtime depending on their GPU.

Code Example

import pyclesperanto as cle
from skimage.io import imread, imsave

# initialize GPU
device = cle.select_device()
print("Used GPU: ", device)

image = imread("https://samples.fiji.sc/blobs.png")

# push image to device memory
input_image = cle.push(image)

# process the image
inverted = cle.subtract_image_from_scalar(input_image, scalar=255)
blurred = cle.gaussian_blur(inverted, sigma_x=1, sigma_y=1)
binary = cle.threshold_otsu(blurred)
labeled = cle.connected_components_labeling(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))

# read image from device memory
output_image = cle.pull(labeled)
imsave("result.tif", output_image)

Examples & Demos gallery

	[Segment + analyze blobs](https://github.com/clEsperanto/pyclesperanto/tree/main/demos/basics/count_blobs.ipynb)
	[Cell segmentation + Voronoi labeling](https://github.com/clEsperanto/pyclesperanto/tree/main/demos/cell_segmentation.ipynb)
	[3D image filtering](https://github.com/clEsperanto/pyclesperanto/tree/main/demos/image_filtering.ipynb)
	[Find local maxima](https://github.com/clEsperanto/pyclesperanto/tree/main/demos/find_local_maxima.ipynb)
	[3D Tribolium nuclei segmentation](https://github.com/clEsperanto/pyclesperanto/tree/main/demos/process_tribolium.ipynb)
	[Explore application programming interface (API)](https://github.com/clEsperanto/pyclesperanto/tree/main/demos/explore_API.ipynb)

More usage and example can be found as notebooks in the demos folder

Contributing and Feedback

clEsperanto is developed in the open because we believe in the [open source community]. Feel free to drop feedback as github issue or via image.sc forum. Contribution are also very welcome. Please read our community guidelines before you start and get in touch with us so that we can help you get started. If you liked our work, star the repository, share it with your friends, and use it to make cool stuff!

Acknowledgements

We acknowledge support by the Deutsche Forschungsgemeinschaft under Germany’s Excellence Strategy (EXC2068) Cluster of Excellence Physics of Life of TU Dresden. This project has been made possible in part by grant number 2021-237734 (GPU-accelerating Fiji and friends using distributed CLIJ, NEUBIAS-style, EOSS4) from the Chan Zuckerberg Initiative DAF, an advised fund of the Silicon Valley Community Foundation.

clEsperanto / pyclesperanto

readme