py-clesperanto is a prototype for clesperanto - a multi-platform multi-language framework for GPU-accelerated image processing. We mostly use it in the life sciences for analysing 3- and 4-dimensional microsopy data, e.g. as we face it developmental biology when segmenting cells and studying their individual properties as well as properties of compounds of cells forming tissues.
Image data source: Daniela Vorkel, Myers lab, MPI-CBG, rendered using napari
clesperanto uses OpenCL kernels from CLIJ.
For users convenience, there are code generators available for napari and Fiji. Also check out the napari workflow optimizer for semi-automatic parameter tuning of clesperanto-functions.
The preliminary API reference is available here. Furthermore, parts of the reference are also available within the CLIJ2 documentation.
conda create --name cle_39 python=3.9
conda activate cle_39
mamba install -c conda-forge pyclesperanto-prototype
OR using pip:
pip install pyclesperanto-prototype
In case error messages contain "ImportError: DLL load failed while importing cl: The specified procedure could not be found" see also or "clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR", please install recent drivers for your graphics card and/or OpenCL device. Select the right driver source depending on your hardware from this list:
Sometimes, mac-users need to install this:
mamba install -c conda-forge ocl_icd_wrapper_apple
Sometimes, linux users need to install this:
mamba install -c conda-forge ocl-icd-system
Linux user may have to install packages such as intel-opencl-icd
or rocm-opencl-runtime
depending on their GPU.
If no OpenCL-compatible GPU is available, pyclesperanto-prototype can make use of CPUs instead. Just install oclgrind or pocl, e.g. using mamba / conda. Oclgrind is recommended for Windows systems, PoCL for Linux. MacOS typically comes with OpenCL support for CPUs.
mamba install oclgrind -c conda-forge
OR
mamba install pocl -c conda-forge
Owners of compatible Intel Xeon CPUs can also install a driver to use them for computing:
A basic image processing workflow loads blobs.gif and counts the number of objects:
import pyclesperanto_prototype as cle
from skimage.io import imread, imsave
# initialize / select GPU with "TX" in their name
device = cle.select_device("TX")
print("Used GPU: ", device)
# load data
image = imread('https://imagej.nih.gov/ij/images/blobs.gif')
# 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 maximium intensity in a label image corresponds to the number of objects
num_labels = labeled.max()
print(f"Number of objects in the image: {num_labels}")
# save image to disc
imsave("result.tif", labeled)
![]() | [Select GPU](https://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/select_GPU.py) |
![]() | [Image processing in Jupyter Notebooks](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/interoperability/jupyter.ipynb) |
![]() | [Counting blobs](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/count_blobs.ipynb) |
![]() | [Voronoi-Otsu labeling](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/segmentation/voronoi_otsu_labeling.ipynb) |
![]() | [3D Image segmentation ](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/segmentation/Segmentation_3D.ipynb) |
![]() | [Cell segmentation based on membranes](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/segmentation/segmentation_2d_membranes.ipynb) |
![]() | [Counting nuclei according to expression in multiple channels](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/measurement/counting_nuclei_multichannel.ipynb) |
![]() | [Differentiating nuclei according to signal intensity](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/measurement/differentiate_nuclei_intensity.ipynb) |
![]() | [Detecting beads and measuring their size](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/segmentation/bead_segmentation.ipynb) |
![]() | [Label statistics](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/label_statistics.ipynb) |
![]() | [Parametric maps](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/tissues/parametric_maps.ipynb) |
![]() | [Measure intensity along lines](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/measurement/intensities_along_lines.ipynb) |
![]() | [Crop and paste images](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/crop_and_paste_images.ipynb) |
![]() | [Inspecting 3D image data](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/inspecting_3d_images.ipynb) |
![]() | [Rotation, scaling, translation, affine transforms](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/transforms/affine_transforms.ipynb) |
![]() | [Deskewing](https://github.com/clEsperanto/pyclesperanto_prototype/blob/master/demo/transforms/deskew.ipynb) |
![]() | [Multiply vectors and matrices](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/multiply_vectors_and_matrices.ipynb) |
![]() | [Matrix multiplication](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/multiply_matrices.ipynb) |
![]() | * [Working with spots, pointlist and matrices](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/spots_pointlists_matrices_tables.ipynb) * [Lists of nonzero pixel coordinates](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/nonzero.ipynb) |
![]() | [Mesh between centroids](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/mesh_between_centroids.ipynb) |
![]() | [Mesh between touching neighbors](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/mesh_between_touching_neighbors.ipynb) |
![]() | [Mesh with distances](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/mesh_with_distances.ipynb) |
![]() | [Mesh nearest_neighbors](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/mesh_nearest_neighbors.ipynb) |
![]() | [Export to igraph and networkx](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/ipgraph_networkx.ipynb) |
![]() | [Neighborhood definitions](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/neighborhood_definitions.ipynb) |
![]() | [Tissue neighborhood quantification](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/tissues/tissue_neighborhood_quantification.ipynb) |
![]() | [Neighbors of neighbors](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/neighbors_of_neighbors.ipynb) |
![]() | [Voronoi diagrams](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/voronoi_diagrams.ipynb) |
![]() | [Shape descriptors based on neighborhood graphs](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/shape_descriptors_based_on_neighborhood_graphs.ipynb) |
![]() | [Measuring distances between labels in two label images](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/neighbors/distance_to_other_labels.ipynb) |
![]() | [Tribolium morphometry + Napari](https://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/tribolium_morphometry/tribolium.py) |
![]() | [Tribolium morphometry](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/tribolium_morphometry/tribolium_morphometry2.ipynb) [(archived version)](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/tribolium_morphometry/tribolium_morphometry.ipynb) |
![]() | [napari+dask timelapse processing](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/napari_gui/napari_dask.ipynb) |
![]() | [Browsing operations](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/browse_operations.ipynb) |
![]() | [Interactive widgets](https://colab.research.google.com/github/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/browse_operations.ipynb) |
![]() | [Automatic workflow optimization](https://colab.research.google.com/github/clEsperanto/pyclesperanto_prototype/tree/master/demo/optimization/optimize_blobs_segmentation.ipynb) |
![]() | [Tracing memory consumtion on NVidia GPUs](https://github.com/clEsperanto/pyclesperanto_prototype/blob/master/demo/optimization/memory_management.ipynb) |
![]() | [Exploring and switching between GPUs](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/switching_gpus.ipynb) |
![]() | [Interoperability with cupy](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/interoperability_cupy.ipynb) [Using the cupy backend](http://github.com/clEsperanto/pyclesperanto_prototype/tree/master/demo/basics/select_backend.ipynb) |
![]() | [Big data handling with Dask GPU clusters](./demo/interoperability/dask.ipynb) |
![]() | [napari-pyclesperanto-assistant](https://github.com/clesperanto/napari_pyclesperanto_assistant): A graphical user interface for general purpose GPU-accelerated image processing and analysis in napari. |
![]() | [napari-accelerated-pixel-and-object-classification](https://github.com/haesleinhuepf/napari-accelerated-pixel-and-object-classification): GPU-accelerated Random Forest Classifiers for pixel and labeled object classification |
![]() | [napari-clusters-plotter](https://github.com/BiAPoL/napari-clusters-plotter): Clustering of objects according to their quantitative properties |
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!
There are other libraries for code acceleration and GPU-acceleration for image processing.
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