pyclesperanto

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

[!WARNING]

• 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] pyclesperanto package is also available on PyPI and can be install with the command:

• pip install pyclesperanto

Troubleshooting: Graphics cards drivers

In case you encounter one of the following error messages indicate a wrong OpenCL setup on your system:

• "clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR"
• "No backend 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:

• AMD drivers
• NVidia drivers
• Intel GPU drivers
• Microsoft Windows OpenCL support

And make sure that your OpenCL library are accessible in you PATH.

[!TIP] Linux users may 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?raw=true")

# 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

	Select and Manage devices Host-Device memory management Process an image
	Crop, Flip, Paste arrays Math operations Matrix operations Vector and Matrix operations How to inspecting 3D image
	Segment and analyse blobs Voronoi-Otsu labeling Cell segmentation based on membrane Cell segmentation in 3D
	Edge detection Ridge and Tube detection Parametric maps Rotation, scaling, translation, and affine transform
	Multi-device tile processing Ask Bia-Bob example

More usage and example can be found as notebooks in the demos folder. As well as in the documentation.

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 and by the Institut Pasteur, Paris. 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, and by support from the French National Research Agency via the France BioImaging research infrastructure (ANR-24-INBS-0005 FBI BIOGEN).