cuCIM

RAPIDS cuCIM is an open-source, accelerated computer vision and image processing software library for multidimensional images used in biomedical, geospatial, material and life science, and remote sensing use cases.

cuCIM offers:

• Enhanced Image Processing Capabilities for large and n-dimensional tag image file format (TIFF) files
• Accelerated performance through Graphics Processing Unit (GPU)-based image processing and computer vision primitives
• A Straightforward Pythonic Interface with Matching Application Programming Interface (API) for Openslide

cuCIM supports the following formats:

• Aperio ScanScope Virtual Slide (SVS)
• Philips TIFF
• Generic Tiled, Multi-resolution RGB TIFF files with the following compression schemes:
  • No Compression
  • JPEG
  • JPEG2000
  • Lempel-Ziv-Welch (LZW)
  • Deflate

NOTE: For the latest stable README.md ensure you are on the main branch.

• GTC 2022 Accelerating Storage IO to GPUs with Magnum IO [S41347]
  • cuCIM's GDS API examples: https://github.com/NVIDIA/MagnumIO/tree/main/gds/readers/cucim-gds
• SciPy 2021 cuCIM - A GPU image I/O and processing library
  • video
• GTC 2021 cuCIM: A GPU Image I/O and Processing Toolkit [S32194]
  • video

Developer Page

Blogs

• Enhanced Image Analysis with Multidimensional Image Processing
• Accelerating Scikit-Image API with cuCIM: n-Dimensional Image Processing and IO on GPUs
• Accelerating Digital Pathology Pipelines with NVIDIA Clara™ Deploy

Webinars

• cuCIM: a GPU Image IO and Processing Library

Documentation

Release notes are available on our wiki page.

Install cuCIM

Conda

Conda (stable)

conda create -n cucim -c rapidsai -c conda-forge cucim cudatoolkit=<CUDA version>

<CUDA version> should be 11.0+ (e.g., 11.0, 11.2, etc.)

Conda (nightlies)

conda create -n cucim -c rapidsai-nightly -c conda-forge cucim cudatoolkit=<CUDA version>

<CUDA version> should be 11.0+ (e.g., 11.0, 11.2, etc)

PyPI

pip install cucim

# Install dependencies for `cucim.skimage` (assuming that CUDA 11.0 is used for CuPy)
pip install scipy scikit-image cupy-cuda110

Notebooks

Please check out our Welcome notebook (NBViewer)

Downloading sample images

To download images used in the notebooks, please execute the following commands from the repository root folder to copy sample input images into notebooks/input folder:

(You will need Docker installed in your system)

./run download_testdata

or

mkdir -p notebooks/input
tmp_id=$(docker create gigony/svs-testdata:little-big)
docker cp $tmp_id:/input notebooks
docker rm -v ${tmp_id}

Build/Install from Source

See build instructions.

Contributing Guide

Contributions to cuCIM are more than welcome! Please review the CONTRIBUTING.md file for information on how to contribute code and issues to the project.

Acknowledgments

Without awesome third-party open source software, this project wouldn't exist.

Please find LICENSE-3rdparty.md to see which third-party open source software is used in this project.

License

Apache-2.0 License (see LICENSE file).

Copyright (c) 2020-2022, NVIDIA CORPORATION.

cuCIM 23.04.01 (14 Apr 2023)

🛠️ Improvements

• Pin libwebp-base (#541) @ajschmidt8

cuCIM 23.04.00 (13 Apr 2023)

🚨 Breaking Changes

• Fix inefficiency in handling clipping of image range in resize and other transforms (#516) @grlee77

🐛 Bug Fixes

• Fix bug in median filter with non-uniform footprint (#521) @grlee77
• use cp.around instead of cp.round for CuPy 10.x compatiblity (#508) @grlee77
• Fix error in LZ4-compressed Zarr writing demo (#506) @grlee77
• Normalize whitespace.(#474) @bdice

🛠️ Improvements

• allow scikit-image 0.20 as well (#536) @grlee77
• Pass AWS_SESSION_TOKEN and SCCACHE_S3_USE_SSL vars to conda build (#525) @ajschmidt8
• Update aarch64 to GCC 11 (#524) @bdice
• Update to GCC 11 (#522) @bdice
• Upgrade dockcross and pybind11 (#519) @gigony
• Binary morphology: omit weights array when possible (#517) @grlee77
• Fix inefficiency in handling clipping of image range in resize and other transforms (#516) @grlee77
• Fix GHA build workflow (#515) @AjayThorve
• Reduce error handling verbosity in CI tests scripts (#511) @AjayThorve
• Update shared workflow branches (#510) @ajschmidt8
• Remove gpuCI scripts. (#505) @bdice
• Move date to build string in conda recipe (#497) @ajschmidt8

cuCIM 23.02.00 (9 Feb 2023)

🚨 Breaking Changes

• Add disambiguation option to phase_cross_correlation (skimage 0.20 feature) (#486) @grlee77

🐛 Bug Fixes

• apply bug fix to vendored ndimage code (#494) @grlee77
• Closes #490 -- fixes bug in hue jitter (#491) @benlansdell
• Fix random seed used in test_3d_similarity_estimation (#472) @grlee77

📖 Documentation

• Fix documentation author (#475) @bdice

🚀 New Features

• Add colocalization measures (#488) @grlee77
• Add disambiguation option to phase_cross_correlation (skimage 0.20 feature) (#486) @grlee77

🛠️ Improvements

• Update shared workflow branches (#501) @ajschmidt8
• Update isort version to 5.12.0 (#492) @ajschmidt8
• Improve rank filtering performance by removing use of footprint kernel when possible (#485) @grlee77
• use vendored version of cupy.pad with added performance optimizations (#482) @grlee77
• add docs builds to Github Actions (#481) @AjayThorve
• Update numpy version specifier (#480) @ajschmidt8
• Build CUDA 11.8 and Python 3.10 Packages (#476) @ajschmidt8
• Add GitHub Actions Workflows. (#471) @bdice
• Fix conflicts in "Forward-merge branch-22.12 to branch-23.02" (#468) @jakirkham
• Enable copy_prs. (#465) @bdice

cuCIM 22.12.00 (8 Dec 2022)

🚨 Breaking Changes

• Implement additional deprecations carried out for scikit-image 0.20 (#451) @grlee77
• improved implementation of ridge filters (bug fixes and reduced memory footprint) (#423) @grlee77

🐛 Bug Fixes

• pin to cmake !3.25.0 on CI to avoid bug with CUDA+conda during build (#444) @grlee77
• update incorrect argument and deprecated function for tifffile.TiffWriter (#433) @JoohyungLee0106
• Fix rotate behavior for ndim > 2 (#432) @grlee77

📖 Documentation

• add whole-slide tiled read/write demos for measuring GPUDirect Storage (GDS) I/O performance (#452) @grlee77
• Add demo for distance_transform_edt (#394) @grlee77

🚀 New Features

• Support no-compression method in converter (#443) @gigony
• add three segmentation metrics (#425) @grlee77
• add isotropic binary morphology functions (#421) @grlee77
• Add blob feature detectors (blob_dog, blob_log, blob_doh) (#413) @monzelr

🛠️ Improvements

• additional minor updates (skimage 0.20) (#455) @grlee77
• Implement additional deprecations carried out for scikit-image 0.20 (#451) @grlee77
• Faster hessian_matrix_* and structure_tensor_eigvals via analytical eigenvalues for the 3D case (#434) @grlee77
• use fused kernels to reduce overhead in corner detector implementations (#426) @grlee77
• Misc updates for consistency with scikit-image 0.20 (#424) @grlee77
• improved implementation of ridge filters (bug fixes and reduced memory footprint) (#423) @grlee77
• analytical moments computations, support pixel spacings in moments and regionprops (#422) @grlee77
• Forward merge branch-22.10 to branch-22.12 (#420) @grlee77
• Support sampling kwarg for distance_transform_edt (take pixel/voxel sizes into account) (#407) @grlee77
• Improve performance of Euclidean distance transform (#406) @grlee77

cuCIM 22.10.00 (12 Oct 2022)

🐛 Bug Fixes

• Correctly use dtype when computing shared memory requirements of separable convolution (#409) @grlee77
• Forward-merge branch-22.08 to branch-22.10 (#403) @jakirkham
• Add missing imports of euler_number and perimeter_crofton (#386) @grlee77

📖 Documentation

• update pypi CHANGELOG.md for releases 22.08.00 and 22.08.01 (#404) @grlee77
• Update README.md (#396) @HesAnEasyCoder

🚀 New Features

• Allow cupy 11 (#399) @galipremsagar
• Add cucim.skimage.feature.match_descriptors (#338) @grlee77

🛠️ Improvements

• Merge docs and add links (#415) @jakirkham
• Add benchmarks for scikit-image functions introduced in 22.08 (#378) @grlee77

cuCIM 22.08.00 (17 Aug 2022)

🚨 Breaking Changes

• Stain extraction: use a less strict condition across channels when thresholding (#316) @grlee77

🐛 Bug Fixes

• create SimilarityTransform using CuPy 9.x-compatible indexing (#365) @grlee77
• Add __init__.py in cucim.core (#359) @jakirkham
• Stain extraction: use a less strict condition across channels when thresholding (#316) @grlee77
• Incorporate bug fixes from skimage 0.19.3 (#312) @grlee77
• fix RawKernel bug for canny filter when quantiles are used (#310) @grlee77

📖 Documentation

• Defer loading of custom.js (#383) @galipremsagar
• add cucim.core.morphology to API docs + other docstring fixes (#367) @grlee77
• Update README.md (#361) @HesAnEasyCoder
• remove unimplemented functions from See Also and fix version numbers in deprecation warnings (#356) @grlee77
• Forward-merge branch-22.06 to branch-22.08 (#344) @grlee77
• Update README.md (#315) @HesAnEasyCoder
• Update index.rst (#314) @HesAnEasyCoder
• Update PyPI package documentation for v22.06.00 (#311) @gigony

🚀 New Features

• Add segmentation with the Chan-Vese active contours method (#343) @grlee77
• Add cucim.skimage.morphology.medial_axis (#342) @grlee77
• Add cucim.skimage.segmentation.expand_labels (#341) @grlee77
• Add Euclidean distance transform for images/volumes (#318) @grlee77

🛠️ Improvements

• Revert "Allow CuPy 11" (#362) @galipremsagar
• Fix issues with day & night modes in python docs (#360) @galipremsagar
• Allow CuPy 11 (#357) @jakirkham
• more efficient separable convolution (#355) @grlee77
• Support resolution and spacing metadata (#349) @gigony
• Performance optimizations to morphological segmentation functions (#340) @grlee77
• benchmarks: avoid use of deprecated pandas API (#339) @grlee77
• Reduce memory overhead and improve performance of normalize_colors_pca (#328) @grlee77
• Protect against obscure divide by zero error in edge case of normalize_colors_pca (#327) @grlee77
• complete parametrization of cucim.skimage benchmarks (#324) @grlee77
• parameterization of filters and features benchmarks (v2) (#322) @grlee77
• Add a fast histogram-based median filter (#317) @grlee77
• Remove custom compiler environment variables (#307) @ajschmidt8

cuCIM 22.06.00 (7 Jun 2022)

🚨 Breaking Changes

• Promote small integer types to single rather than double precision (#278) @grlee77

🐛 Bug Fixes

• Populate correct channel names for RGBA image (#294) @gigony
• Merge branch-22.04 into branch-22.06 (#258) @jakirkham

📖 Documentation

• update outdated links to example data (#289) @grlee77
• Add missing API docs (#275) @grlee77

🚀 New Features

• add missing cucim.skimage.segmentation.clear_border function (#267) @grlee77
• add cucim.core.operations.color.stain_extraction_pca and cucim.core.operations.color.normalize_colors_pca for digital pathology H&E stain extraction and normalization (#273) @grlee77, @drbeh

🛠️ Improvements

• Update to use DLPack v0.6 (#295) @gigony
• Remove plugin-related messages temporarily (#291) @gigony
• Simplify recipes (#286) @Ethyling
• Use cupy.fuse to improve efficiency hessian_matrix_eigvals (#280) @grlee77
• Promote small integer types to single rather than double precision (#278) @grlee77
• improve efficiency of histogram-based thresholding functions (#276) @grlee77
• Remove unused dependencies in GPU tests job (#268) @Ethyling
• Enable footprint decomposition for morphology (#274) @grlee77
• Use conda compilers (#232) @Ethyling
• Build packages using mambabuild (#216) @Ethyling

cuCIM 22.04.00 (6 Apr 2022)

🚨 Breaking Changes

• Apply fixes to skimage.transform scheduled for scikit-image 0.19.2 (#208) @grlee77

🐛 Bug Fixes

• Fix ImportError from vendored code (#252) @grlee77
• Fix wrong dimension in metadata (#248) @gigony
• Handle file descriptor ownership and update documents for GDS (#234) @gigony
• Check nullptr of handler in CuFileDriver::close() (#229) @gigony
• Fix docs builds (#218) @ajschmidt8
• Apply fixes to skimage.transform scheduled for scikit-image 0.19.2 (#208) @grlee77

📖 Documentation

• Update PyPI cuCIM v22.02.01 CHANGELOG.md (#249) @gigony
• Update GTC 2021 Spring video links (#227) @gigony
• Update documents for v22.02.00 (#226) @gigony
• Merge branch-22.02 into branch-22.04 (#220) @jakirkham

🛠️ Improvements

• Expose data type of CuImage object for interoperability with NumPy (#246) @gigony
• Temporarily disable new ops-bot functionality (#239) @ajschmidt8
• Add .github/ops-bot.yaml config file (#236) @ajschmidt8
• randomization per image per batch (#231) @shekhardw

cuCIM 22.02.00 (2 Feb 2022)

🚨 Breaking Changes

• Update cucim.skimage API to match scikit-image 0.19 (#190) @glee77

🐛 Bug Fixes

• Fix a bug in v21.12.01 (#191) @gigony
  • Fix GPU memory leak when using nvJPEG API (when device='cuda' parameter is used in read_region method).
• Fix segfault for preferred_memory_capacity in Python 3.9+ (#214) @gigony

📖 Documentation

• PyPI v21.12.00 release (#182) @gigony

🚀 New Features

• Update cucim.skimage API to match scikit-image 0.19 (#190) @glee77
• Support multi-threads and batch, and support nvJPEG for JPEG-compressed images (#191) @gigony
• Allow CuPy 10 (#195) @jakikham

🛠️ Improvements

• Add missing imports tests (#183) @Ethyling
• Allow installation with CuPy 10 (#197) @glee77
• Upgrade Numpy to 1.18 for Python 3.9 support (#196) @Ethyling
• Upgrade Numpy to 1.19 for Python 3.9 support (#203) @Ethyling

cuCIM 21.12.00 (9 Dec 2021)

🚀 New Features

• Support Aperio SVS with CPU LZW and jpeg2k decoder (#141) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Add NVTX support for performance analysis (#144) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Normalize operation (#150) [@shekhardw](https://github.com/shekhardw](https://github.com/shekhardw))

🐛 Bug Fixes

• Load libcufile.so with RTLD_NODELETE flag (#177) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Remove rmm/nvcc dependencies to fix cudaErrorUnsupportedPtxVersion error (#175) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Do not compile code with nvcc if no CUDA kernel exists (#171) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Fix a segmentation fault due to unloaded libcufile (#158) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Fix thread contention in Cache (#145) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Build with NumPy 1.17 (#148) [@jakirkham](https://github.com/jakirkham](https://github.com/jakirkham))

📖 Documentation

• Add Jupyter notebook for SVS Support (#147) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Update change log for v21.10.01 (#142) [@gigony](https://github.com/gigony](https://github.com/gigony))
• update docs theme to pydata-sphinx-theme (#138) [@quasiben](https://github.com/quasiben](https://github.com/quasiben))
• Update Github links in README.md through script (#132) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Fix GDS link in Jupyter notebook (#131) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Update notebook for the interoperability with DALI (#127) [@gigony](https://github.com/gigony](https://github.com/gigony))

🛠️ Improvements

• Update conda recipes for Enhanced Compatibility effort by (#164) [@ajschmidt8](https://github.com/ajschmidt8](https://github.com/ajschmidt8))
• Fix Changelog Merge Conflicts for branch-21.12 (#156) [@ajschmidt8](https://github.com/ajschmidt8](https://github.com/ajschmidt8))
• Add cucim.kit.cumed plugin with skeleton (#129) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Update initial cpp unittests (#128) [@gigony](https://github.com/gigony](https://github.com/gigony))
• Optimize zoom out implementation with separate padding kernel (#125) [@chirayuG-nvidia](https://github.com/chirayuG-nvidia](https://github.com/chirayuG-nvidia))
• Do not force install linux-64 version of openslide-python (#124) [@Ethyling](https://github.com/Ethyling](https://github.com/Ethyling))

cuCIM 21.10.00 (7 Oct 2021)

🐛 Bug Fixes

• fix failing regionprops test cases (#110) @grlee77

📖 Documentation

• Forward-merge branch-21.08 to branch-21.10 (#88) @jakirkham
• Update PyPI cuCIM v21.08.01 README.md and CHANGELOG.md (#87) @gigony

🚀 New Features

• Support raw RGB tiled TIFF (#108) @gigony
• Add a mechanism for user to know the availability of cucim.CuImage (#107) @gigony
• Enable GDS and Support Runtime Context (enter, exit) for CuFileDriver and CuImage (#106) @gigony
• Add transforms for Digital Pathology (#100) @shekhardw

🛠️ Improvements

• ENH Replace gpuci_conda_retry with gpuci_mamba_retry (#69) @dillon-cullinan

cuCIM 21.08.00 (4 Aug 2021)

🐛 Bug Fixes

• Remove int-type bug on Windows in skimage.measure.label (#72) @grlee77
• Fix missing array interface for associated_image() (#65) @gigony
• Handle zero-padding version string (#59) @gigony
• Remove invalid conda environment activation (#58) @ajschmidt8

📖 Documentation

• Fix a typo in cache document (#66) @gigony

🚀 New Features

• Pin isort hook to 5.6.4 (#73) @charlesbluca
• Add skimage.morphology.thin (#27) @grlee77

🛠️ Improvements

• Add SciPy 2021 to README (#79) @jakirkham
• Use more descriptive ElementwiseKernel names in cucim.skimage (#75) @grlee77
• Add initial Python unit/performance tests for TIFF loader module (#62) @gigony
• Fix 21.08 forward-merge conflicts (#57) @ajschmidt8

cuCIM 21.06.00 (9 Jun 2021)

🐛 Bug Fixes

• Update update-version.sh (#42) @ajschmidt8

🛠️ Improvements

• Update environment variable used to determine cuda_version (#43) @ajschmidt8
• Update version script to remove bump2version dependency (#41) @gigony
• Update changelog (#40) @ajschmidt8
• Update docs build script (#39) @ajschmidt8

cuCIM 0.19.0 (15 Apr 2021)

• Initial release of cuCIM including cuClaraImage and cupyimg.