Package: pyclesperanto-prototype
py-clesperantopy-clesperanto is a prototype forclesperanto- 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 usingnapariclesperanto usesOpenCL kernelsfromCLIJ.For users convenience, there are code generators available fornapariandFiji.
Also check out thenapari workflow optimizerfor semi-automatic parameter tuning of clesperanto-functions.ReferenceThe preliminary API reference is availablehere.
Furthermore, parts of thereferenceare also available within the CLIJ2 documentation.InstallationGet a conda/python environment, e.g. viamamba-forge.If you never used python/conda environments before, please followthese instructionsfirst.conda create --name cle_39 python=3.9
conda activate cle_39Install pyclesperanto-prototype usingmamba / conda:mamba install -c conda-forge pyclesperanto-prototypeOR using pip:pip install pyclesperanto-prototypeTroubleshooting: Graphics cards driversIn case error messages contain "ImportError: DLL load failed while importing cl: The specified procedure could not be found"see alsoor "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:AMD driversNVidia driversIntel GPU driversMicrosoft Windows OpenCL supportSometimes, mac-users need to install this:mamba install -c conda-forge ocl_icd_wrapper_appleSometimes, linux users need to install this:mamba install -c conda-forge ocl-icd-systemLinux user may have to install packages such asintel-opencl-icdorrocm-opencl-runtimedepending on their GPU.Computing on Central Processing units (CPUs)If no OpenCL-compatible GPU is available, pyclesperanto-prototype can make use of CPUs instead.
Just installoclgrindorpocl, 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-forgeORmamba install  pocl -c conda-forgeOwners of compatible Intel Xeon CPUs can also install a driver to use them for computing:Intel CPU OpenCL driversExample codeA basic image processing workflow loads blobs.gif and counts the number of objects:importpyclesperanto_prototypeasclefromskimage.ioimportimread,imsave# initialize / select GPU with "TX" in their namedevice=cle.select_device("TX")print("Used GPU: ",device)# load dataimage=imread('https://imagej.nih.gov/ij/images/blobs.gif')# process the imageinverted=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 objectsnum_labels=labeled.max()print(f"Number of objects in the image:{num_labels}")# save image to discimsave("result.tif",labeled)Example gallerySelect GPUImage processing in Jupyter NotebooksCounting blobsVoronoi-Otsu labeling3D Image segmentationCell segmentation based on membranesCounting nuclei according to expression in multiple channelsDifferentiating nuclei according to signal intensityDetecting beads and measuring their sizeLabel statisticsParametric mapsMeasure intensity along linesCrop and paste imagesInspecting 3D image dataRotation, scaling, translation, affine transformsDeskewingMultiply vectors and matricesMatrix multiplicationWorking with spots, pointlist and matricesLists of nonzero pixel coordinatesMesh between centroidsMesh between touching neighborsMesh with distancesMesh nearest_neighborsExport to igraph and networkxNeighborhood definitionsTissue neighborhood quantificationNeighbors of neighborsVoronoi diagramsShape descriptors based on neighborhood graphsMeasuring distances between labels in two label imagesTribolium morphometry + NapariTribolium morphometry(archived version)napari+dask timelapse processingTechnical insightsBrowsing operationsInteractive widgetsAutomatic workflow optimizationTracing memory consumtion on NVidia GPUsExploring and switching between GPUsInteroperability with cupyUsing the cupy backendBig data handling with Dask GPU clustersRelated projectsnapari-pyclesperanto-assistant:
A graphical user interface for general purpose GPU-accelerated image processing and analysis in napari.napari-accelerated-pixel-and-object-classification:
GPU-accelerated Random Forest Classifiers for pixel and labeled object classificationnapari-clusters-plotter:
Clustering of objects according to their quantitative propertiesBenchmarkingWe 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 transformsBackground subtractionGaussian blurConvolutionOtsu's thresholdingConnected component labelingExtend labelsStatistics of labeled pixels / regionpropsHistogramsMatrix multiplicationPixel-wise comparisonIntensity projectionsAxis transpositionNonzeroSee alsoThere are other libraries for code acceleration and GPU-acceleration for image processing.numbacupycucimclijFeedback welcome!clesperanto is developed in the open because we believe in the open source community. See ourcommunity guidelines. Feel free to drop feedback asgithub issueor viaimage.sc