cuCIM

RAPIDS cuCIM is an extensible toolkit designed to provide GPU accelerated I/O, computer vision & image processing primitives for N-Dimensional images with a focus on biomedical imaging.

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

Quick Start

Install cuCIM

pip install cucim

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

Jupyter Notebooks

Please check out our Welcome notebook.

Open Image

cuCIM's dataloader(cucim.CuImage class) is currently supporting Digital-pathology specific image formats (tiled multi-resolution raw/deflate/lzw/JPEG/JPEG2000-compressed TIFF-like RGB images such as Generic TIFF, Philips TIFF, Aperio SVS format).

from cucim import CuImage
img = CuImage('image.tif')

See Metadata

import json
print(img.is_loaded)        # True if image data is loaded & available.
print(img.device)           # A device type.
print(img.ndim)             # The number of dimensions.
print(img.dims)             # A string containing a list of dimensions being requested.
print(img.shape)            # A tuple of dimension sizes (in the order of `dims`).
print(img.size('XYC'))      # Returns size as a tuple for the given dimension order.
print(img.dtype)            # The data type of the image.
print(img.channel_names)    # A channel name list.
print(img.spacing())        # Returns physical size in tuple.
print(img.spacing_units())  # Units for each spacing element (size is same with `ndim`).
print(img.origin)           # Physical location of (0, 0, 0) (size is always 3).
print(img.direction)        # Direction cosines (size is always 3x3).
print(img.coord_sys)        # Coordinate frame in which the direction cosines are
                            # measured. Available Coordinate frame is not finalized yet.

# Returns a set of associated image names.
print(img.associated_images)
# Returns a dict that includes resolution information.
print(json.dumps(img.resolutions, indent=2))
# A metadata object as `dict`
print(json.dumps(img.metadata, indent=2))
# A raw metadata string.
print(img.raw_metadata)

Read Region

# Install matplotlib (`pip install matplotlib`) if not installed before.
from matplotlib import pyplot as plt
def visualize(image):
    dpi = 80.0
    height, width, _ = image.shape
    plt.figure(figsize=(width / dpi, height / dpi))
    plt.axis('off')
    plt.imshow(image)

import numpy as np

# Read whole slide at the highest resolution
resolutions = img.resolutions
level_count = resolutions['level_count']  # level: 0 ~ (level_count - 1)

# Note: ‘level’ is at 3rd parameter (OpenSlide has it at 2nd parameter)
#   `location` is level-0 based coordinates (using the level-0 reference frame)
#   If `size` is not specified, size would be (width, height) of the image at the specified `level`.
region = img.read_region(location=(5000, 5000), size=(512, 512), level=0)

visualize(region)
#from PIL import Image
#Image.fromarray(np.asarray(region))

Aperio SVS (.svs) image format is supported since cuCIM v21.10.01.

Please check this notebook to see how to use the feature.

Using Cache

Please look at this notebook.

Accessing File with GDS

Please look at this notebook.

NVTX Support for Performance Analysis

Please look at this release note.

Supporting Multithreading and Batch Processing

Please look at this release note.

Using scikit-image API

Import cucim.skimage instead of skimage.

# The following code is modified from https://scikit-image.org/docs/dev/auto_examples/color_exposure/plot_ihc_color_separation.html#sphx-glr-auto-examples-color-exposure-plot-ihc-color-separation-py
#
import cupy as cp  # modified from: `import numpy as np`
import matplotlib.pyplot as plt

# from skimage import data
from cucim.skimage.color import rgb2hed, hed2rgb  # modified from: `from skimage.color import rgb2hed, hed2rgb`

# Load image (You can download sample images from https://openslide.cs.cmu.edu/download/openslide-testdata/Aperio/)
from cucim import CuImage
img = CuImage("CMU-1.svs")
region = img.read_region((30000, 10000), (256, 256))

# Example IHC image
ihc_rgb = cp.asarray(region)  # modified from: `ihc_rgb = data.immunohistochemistry()`

# Separate the stains from the IHC image
ihc_hed = rgb2hed(ihc_rgb)

# Create an RGB image for each of the stains
null = cp.zeros_like(ihc_hed[:, :, 0])  # np -> cp
ihc_h = hed2rgb(cp.stack((ihc_hed[:, :, 0], null, null), axis=-1))  # np -> cp
ihc_e = hed2rgb(cp.stack((null, ihc_hed[:, :, 1], null), axis=-1))  # np -> cp
ihc_d = hed2rgb(cp.stack((null, null, ihc_hed[:, :, 2]), axis=-1))  # np -> cp

# Display
fig, axes = plt.subplots(2, 2, figsize=(7, 6), sharex=True, sharey=True)
ax = axes.ravel()

ax[0].imshow(ihc_rgb.get())  # appended `.get()`
ax[0].set_title("Original image")

ax[1].imshow(ihc_h.get())  # appended `.get()`
ax[1].set_title("Hematoxylin")

ax[2].imshow(ihc_e.get())  # appended `.get()`
ax[2].set_title("Eosin")

ax[3].imshow(ihc_d.get())  # appended `.get()`
ax[3].set_title("DAB")

for a in ax.ravel():
    a.axis('off')

fig.tight_layout()

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.

Changelog (See Release Notes)

22.02.06

• [Update/Breaking] Promote small integer types to single rather than double precision (#278) @grlee77
• [Bug] Populate correct channel names for RGBA image (#294) @gigony
• [Bug] Merge branch-22.04 into branch-22.06 (#258) @jakirkham
• [New] add missing cucim.skimage.segmentation.clear_border function (#267) @grlee77
• [Update] Update to use DLPack v0.6 (#295) @gigony
• [Update] Remove plugin-related messages temporarily (#291) @gigony
• [Update] Simplify recipes (#286) @Ethyling
• [Update] Use cupy.fuse to improve efficiency hessian_matrix_eigvals (#280) @grlee77
• [Update] improve efficiency of histogram-based thresholding functions (#276) @grlee77
• [Update] Remove unused dependencies in GPU tests job (#268) @Ethyling
• [Update] Use conda compilers (#232) @Ethyling
• [Update] Build packages using mambabuild (#216) @Ethyling
• [Doc] update outdated links to example data (#289) @grlee77
• [Doc] Add missing API docs (#275) @grlee77

22.02.04

• [Bug] Fix ImportError from vendored code (#252) @grlee77
• [Bug] Fix wrong dimension in metadata (#248) @gigony

22.02.01

• [Bug] Check nullptr of handler in CuFileDriver::close() (#229) @gigony
• [Bug] Handle file descriptor ownership and update documents for GDS (#234) @gigony
• [Bug] Apply fixes to skimage.transform scheduled for scikit-image 0.19.2 (#208) @grlee7
• [New] Randomization of transforms per image per batch (#231) @shekhardw
• [New] Expose data type of CuImage object for interoperability with NumPy (#246) @gigony
• [Update] Remove verbose plugin messages temporarily. Address #109 ([BUG] - Info messages appearing as warnings in Jupyter notebooks)
• [Doc] Fix docs builds (#218) @ajschmidt8
• [Doc] Update GTC 2021 Spring video links (#227) @gigony
• [Doc] Update documents for v22.02.00 (#226) @gigony

22.02.00

• [New/Breaking] Update cucim.skimage API to match scikit-image 0.19 (#190) @glee77
• [Bug] 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).
• [Bug] Fix segfault for preferred_memory_capacity in Python 3.9+ (#214) @gigony
• [Doc] PyPI v21.12.00 release (#182) @gigony
• [New] Allow CuPy 10 (#195) @jakikham
• [New] Support multi-threads and batch, and support nvJPEG for JPEG-compressed images (#191) @gigony
• [New] Update cucim.skimage API to match scikit-image 0.19 (#190) @glee77
• [Update] Add missing imports tests (#183) @Ethyling
• [Update] Allow installation with CuPy 10 (#197) @glee77
• [Update] Upgrade Numpy to 1.18 for Python 3.9 support (#196) @Ethyling
• [Update] Upgrade Numpy to 1.19 for Python 3.9 support (#203) @Ethyling

21.12.01

• [New] Supporting Multithreading and Batch Processing (#149) @gigony

21.12.00

• [New] Support Aperio SVS with CPU LZW and jpeg2k decoder (#141) @gigony
• [New] Add NVTX support for performance analysis (#144) @gigony
• [New] Normalize operation (#150) @shekhardw
• [Bug] Load libcufile.so with RTLD_NODELETE flag (#177) @gigony
• [Bug] Remove rmm/nvcc dependencies to fix cudaErrorUnsupportedPtxVersion error (#175) @gigony
• [Bug] Do not compile code with nvcc if no CUDA kernel exists (#171) @gigony
• [Bug] Fix a segmentation fault due to unloaded libcufile (#158) @gigony
• [Bug] Fix thread contention in Cache (#145) @gigony
• [Bug] Build with NumPy 1.17 (#148) @jakirkham
• [Doc] Add Jupyter notebook for SVS Support (#147) @gigony
• [Doc] Update change log for v21.10.01 (#142) @gigony
• [Doc] update docs theme to pydata-sphinx-theme (#138) @quasiben
• [Doc] Update Github links in README.md through script (#132) @gigony
• [Doc] Fix GDS link in Jupyter notebook (#131) @gigony
• [Doc] Update notebook for the interoperability with DALI (#127) @gigony
• [Update] Update conda recipes for Enhanced Compatibility effort by (#164) @ajschmidt8
• [Update] Fix Changelog Merge Conflicts for branch-21.12 (#156) @ajschmidt8
• [Update] Add cucim.kit.cumed plugin with skeleton (#129) @gigony
• [Update] Update initial cpp unittests (#128) @gigony
• [Update] Optimize zoom out implementation with separate padding kernel (#125) @chirayuG-nvidia
• [Update] Do not force install linux-64 version of openslide-python (#124) @Ethyling

21.10.01

• [New] Support Aperio SVS with CPU LZW and jpeg2k decoder (#141)

21.10.00

• [New] Add transforms for Digital Pathology (#100) @shekhardw @chirayuG-nvidia
• [New] Enable GDS and Support Runtime Context (enter, exit) for CuFileDriver and CuImage (#106) @gigony
• [New] Add a mechanism for user to know the availability of cucim.CuImage (#107) @gigony
• [New] Support raw RGB tiled TIFF (#108) @gigony
• [Bug] fix failing regionprops test cases (#110) @grlee77
• [Doc] Forward-merge branch-21.08 to branch-21.10 (#88) @jakirkham
• [Doc] Update PyPI cuCIM v21.08.01 README.md and CHANGELOG.md (#87) @gigony
• [Update] ENH Replace gpuci_conda_retry with gpuci_mamba_retry (#69) @dillon-cullinan

21.08.02

• [New] Add transforms for Digital Pathology (#100) @shekhardw @chirayuG-nvidia

21.08.01

• [New] Add skimage.morphology.thin (#27)
• [Bug] Fix missing __array_interface__ for associated_image(): (#48, #65)
• [Testing] Added unit and performance tests for TIFF loaders (#62)
• [Bug] Fix Windows int-type Bug: (#72)
• [Update] Use more descriptive ElementwiseKernel names in cucim.skimage: (#75)

21.06.00

• Implement cache mechanism
• Add __cuda_array_interface.
• Fix a memory leak in Deflate decoder.