Skip to main content

cuCIM - 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.

Project description

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.

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==9.0.0b3

Jupyter Notebooks

Please check out our Welcome notebook.

Open Image

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))

Using Cache

Please look at this notebook.

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`

# 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-2021, NVIDIA CORPORATION.

Changelog

21.08.02

  • [New] Add transforms for Digital Pathology (#100)
    • Implement transforms for color jitter, image scale intensity, image flip and rotate for batched RGB images.

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.

0.19.0 (2021-04-19)

  • The first release of cuClaraImage + cupyimg as a single project cuCIM.
    • cucim.skimage package is added from cupyimg.
    • CuPy (>=9.0.0b3), scipy, scikit-image is required to use cuCIM's scikit-image-compatible API.

0.18.3 (2021-04-16)

  • Fix memory leaks that occur when reading completely out-of-boundary regions.

0.18.2 (2021-03-29)

  • Use the white background only for Philips TIFF file.
    • Generic TIFF file would have the black background by default.
  • Fix upside-downed image for TIFF file if the image is not RGB & tiled image with JPEG/Deflate-compressed tiles.
    • Use slow path if the image is not RGB & tiled image with JPEG/Deflate-compressed tiles.
      • Show an error message if the out-of-boundary cases are requested with the slow path.
      • ValueError: Cannot handle the out-of-boundary cases for a non-RGB image or a non-Jpeg/Deflate-compressed image.

0.18.1 (2021-03-17)

  • Disable using cuFile
    • Remove warning messages when libcufile.so is not available.
      • [warning] CuFileDriver cannot be open. Falling back to use POSIX file IO APIs.

0.18.0 (2021-03-16)

  • First release on PyPI with only cuClaraImage features.
  • The namespace of the project is changed from cuimage to cucim and project name is now cuCIM
  • Support Deflate(zlib) compression in Generic TIFF Format.
    • libdeflate library is used to decode the deflate-compressed data.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cucim, version 21.8.2
Filename, size File type Python version Upload date Hashes
Filename, size cucim-21.8.2-py3-none-manylinux2014_x86_64.whl (4.9 MB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page