Medreaders — Readers for medical imaging datasets

Source code: https://github.com/ol-sen/medreaders

The package contains the functions for reading a dataset into memory and for auxiliary tasks:

  • resizing images with their ground truth masks;
  • saving images and their ground truth masks slice by slice.

In order to use this package you should download a dataset that you need from Grand Challenges in Biomedical Image Analysis.

Currently the package provides the means for working with ACDC dataset.

ACDC — Reader for ACDC dataset

Source code: ACDC.py

The ACDC module contains the code for reading ACDC dataset into memory and for auxiliary tasks:
  • resize images with their ground truth masks;
  • save images and their ground truth masks slice by slice to PNG.

Before using this code you should download ACDC dataset.

Simple usage example:

import medreaders
from medreaders import ACDC
ACDC.load("ACDC/training", "all", "ED")        
ACDC.resize(216, 256)
ACDC.normalize()
ACDC.save(images = "PatientImages", masks = "PatientMasks", both = "PatientImagesWithMasks")
images = ACDC.get_images()
masks = ACDC.get_masks()

By default this block of code produces no output to command prompt. In order to change logging level you should insert the following lines before the aforementioned block of code:

import logging
logging.basicConfig(level = logging.INFO)

In this case the output would be:

>>> ACDC.load("training/ACDC", "all", "ED")
INFO:root:Loading ACDC dataset...
INFO:root:ACDC dataset has been loaded successfully.
>>> ACDC.resize(216, 256)
INFO:root:Resizing...
INFO:root:The images and masks have been resized successfully to 216x256.
>>> ACDC.save(images = "PatientImages", masks = "PatientMasks", both = "PatientImagesWithMasks")
INFO:root:Saving...
INFO:root:The images have been saved successfully to PatientImages directory.
INFO:root:The masks have been saved successfully to PatientMasks directory.
INFO:root:The images with masks have been saved successfully to PatientImagesWithMasks directory.

One-hot encoding is used for ground truth masks by default. If you don’t want to use it, you can set identity() as encoder and decoder before using load() function:

ACDC.set_encoder(ACDC.identity)
ACDC.set_decoder(ACDC.identity)

Default output image format is such that is used in PyTorch library: [nslices, channels, height, width]. You can change format to Keras style [nslices, height, width, channels]:

ACDC.set_images_format("Keras")

Functions

ACDC.load(data_dir, structure, phase)

Loads ACDC dataset into memory (the dataset can be downloaded from https://www.creatis.insa-lyon.fr/Challenge/acdc/index.html).

Parameters:
  • data_dir (str) – path to “training” directory
  • structure (str) – anatomical structure of interest: right ventricle (“RV”), myocardium (“MYO”), left ventricle (“LV”) or all structures (“all”)
  • phase (str) – end diastole (“ED”), end systole (“ES”) or both phases (“both”)
Raises:
  • ValueError – if mask or phase parameters are incorrrect
  • EnvironmentError – if the directory specified by data_dir parameter does not contain patient images

Example:

ACDC.load("ACDC/training", "all", "ED")
ACDC.resize(new_height, new_width, interpolate=True)

Resizes images according with their ground truth masks to (new_height, new_width). If interpolate parameter is set to True, bilinear interpolation for images and nearest neighbor interpolation for masks is used. Otherwise central cropping and/or zero padding is used for images and masks.

Parameters:
  • new_height (integer) – height (in pixels) of output images and masks
  • new_width (integer) – width (in pixels) of output images and masks
  • interpolate (bool) – whether to use interpolation or cropping/padding

Example 1:

ACDC.resize(216, 256)

Example 2:

ACDC.resize(216, 256, interpolate = False)
ACDC.normalize()

Normalizes images intensity to the range [0, 255].

Example 1:

ACDC.normalize()
ACDC.save(images=None, masks=None, both=None, alpha=0.5)

Saves original images slice by slice in PNG format to images directory. Saves ground truth masks slice by slice in PNG format to masks directory. Saves pairs of images and these images overlayed by ground truth masks slice by slice in PNG format to both directory.

Parameters:
  • images (str) – path to the directory for saving original images
  • masks (str) – path to the directory for saving masks
  • both (str) – path to the directory for saving images with masks
  • alpha (float) – the alpha blending value for mask overlay, between 0 (transparent) and 1 (opaque)

Example 1:

ACDC.save(images = "PatientImages", masks = "PatientMasks")

Example 2:

ACDC.save(both = "PatientImagesWithMasks", alpha = 0.2)
ACDC.get_images()

Get patient images.

Returns:images
Return type:list of numpy.ndarrays

Example:

images = ACDC.get_images()
ACDC.get_masks()

Get ground truth masks of patient images.

Returns:ground truth masks
Return type:list of numpy.ndarrays

Example:

masks = ACDC.get_masks()
ACDC.set_encoder(encode)

Sets the function for encoding of ground truth masks specified by encode parameter.

Parameters:encode (function) – encoding function

Example 1:

ACDC.set_encoder(ACDC.one_hot_encode)
ACDC.set_decoder(ACDC.one_hot_decode)

Example 2:

ACDC.set_encoder(ACDC.identity)
ACDC.set_decoder(ACDC.identity)

Note

Encoder and decoder should be set simultaneously and should correspond to mutually inverse functions.

ACDC.set_decoder(decode)

Sets the function for decoding of encoded ground truth masks specified by decode parameter.

Parameters:decode (function) – decoding function

Example 1:

ACDC.set_encoder(ACDC.one_hot_encode)
ACDC.set_decoder(ACDC.one_hot_decode)

Example 2:

ACDC.set_encoder(ACDC.identity)
ACDC.set_decoder(ACDC.identity)

Note

Encoder and decoder should be set simultaneously and should correspond to mutually inverse functions.

ACDC.set_images_format(fmt)

Sets the images format: PyTorch style [nslices, channels, height, width] or Keras style [nslices, height, width, channels]. PyTorch style is default.

Parameters:fmt (str) – “PyTorch” or “Keras”
Raises:ValueError – if fmt parameter is incorrrect

Example 1:

ACDC.set_images_format("Keras")
ACDC.get_images_format()

Gets the images format: PyTorch style [nslices, channels, height, width] or Keras style [nslices, height, width, channels]. PyTorch style is default.

Example 1:

fmt = ACDC.get_images_format()
ACDC.one_hot_encode(mask)

Performs one-hot encoding of ground truth mask.

Parameters:mask (numpy.ndarray) – input mask, each value of which is a class label, a number in range from 0 to K-1, where K is the total number of classes
Returns:one-hot encoded mask
Return type:numpy.ndarray

Example:

encoded_mask = ACDC.one_hot_encode(input_mask)
ACDC.one_hot_decode(mask)

Performs one-hot decoding of ground truth mask.

Parameters:mask (numpy.ndarray) – input mask, one-hot encoded
Returns:output mask, each value of which is a class label, a number in range from 0 to K-1, where K is the total number of classes
Return type:numpy.ndarray

Example:

decoded_mask = ACDC.one_hot_decode(encoded_mask)
ACDC.identity(mask)

This is identity function that can be used as an argument of functions set_encoder() and set_decoder().

Parameters:mask (numpy.ndarray) – input mask
Returns:the same mask
Return type:numpy.ndarray

Example:

ACDC.set_encoder(ACDC.identity)
ACDC.set_decoder(ACDC.identity)

Indices and tables