Image IO Proposal

The I/O Working group and developers are interested in having MONAI support a wide range of image file formats. We considered only supporting one file format (e.g., NIFTI), but we determine that such a constraint would be a barrier to adoption for some groups. However, we do not want MONAI to invest significant time in developing and/or supporting file I/O. Therefore, we developed the following proposal to take advantage of ITK for MONAI I/O needs.

We welcome feedback on this proposal from other developers and the entire MONAI community via the MONAI issue tracker: #856

Proposal Goal

Support reading and writing common research image and data file formats: NRRD, Nifti, DICOM (objects), JPG, PNG, TIFF, MetaIO, ... without re-implementation or significant support burden. Additionally, enable a user to override default I/O methods on an experiment-by-experiment basis, e.g., to ensure a specific version of a specific reader is used so the desired, reproducible behavior is achieved for that experiment.

Proposal Summary

MONAI should offer an extensible framework for research image I/O and rely on ITK for the default handling of the file formats that it supports.

Proposal Details

1) Use-case

Code in MONAI should be agnostic to the file format. So, reading an image and accessing its meta data should be handled without the developer needing to know what format the image is stored in. For example, instead of calls such as

train_ds = NiftiDataset(images, segs, transform=train_imtrans, seg_transform=train_segtrans)

The calls would instead be data-format agnostic, such as

train_ds = ImageDataset(images, segs, transform=train_imtrans, seg_transform=train_segtrans)

It is important that this simple/straightforward approach remain unchanged. It should not be necessary to specify additional arguments or configuration files. So, if the user wants to do something simple, it should be simple for them to do that.

2) Extensibility and reproducibility

We propose that a user should be able to override MONAI's default reader for a particular file type, on an experiment-by-experiment basis. For example, a user may know that they want to use PyDICOM instead of ITK's GDCM to read files with a ".dcm" suffix for the experiment that they are about to run. So, via arguments passed to the ImageDataset call, or via settings in an experiment's configuration file (or via some other flexible method), it should be possible for the behavior of the ImageDataset function to be changed to use a user-specified function when an image file has a specified suffix. A user should also be able to specify a wildcard suffix, so that regardless of the file's suffix, the alternative reader that they provide is called.

3) Implementation ideas

In monai/transforms/io/array.py, define

LoadImage(Transform)

that uses ITK to read in image in any format supported by ITK. Internally, this function perhaps uses an object factory mechanism to call other readers, based on the image's suffix. Then, this object factory could perhaps be extended or modified by arguments to the dataset function that calls it or by an experiment definition file or by some other to-be-determined method.

Similarly, in monai/data, two new functions are added: image_reader.py and image_writer.py. These function call LoadImage to read in the images passed to a corresponding ImageDataset() function call.

It has been suggested that MONAI should have a global property file that (among other things) defines the default Loaders and Writers for files. Each Loader definition specifies the file suffix, dependencies, version of dependencies, and function to be called.

MONAI.IO
{
    FOO LoadFOO
    PNG  ITK/5.1/LoadITK
    TIFF,TIF  ITK/5.1/LoadITK
    * ITK/5.1/LoadITK
}

Then, experiment files can optionally include a property file that defines alternative loaders to be used, e.g.:

Experiment.IO
{
    PNG  ITK/5.2/LoadITK
    TIF  LoadTIF
}

4) Clinical Relevance

The framework should preserve an image’s clinical relevance by maintaining its real-world properties, e.g., orientation, spacing, and origin. If an image format does not provide such values (e.g., a GIF), then reasonable defaults are given (0 origin, and 1 spacing). ITK handles this for most formats.

5) Compliance

Every image loader should use the meta-data dictionary terms commonly used by ITK (based on DICOM images read by GDCM). This way, when LoadDatad() is called, which internally calls LoadImage(), the resulting data dictionary is the same, regardless of the image format read.

6) Extensibility Considerations

Other libraries that an experiment may want to include for doing file I/O include:

• BIDS (brain imaging data structure)
• NDWB (neurodata without boarders)

7) Other examples to learn from

When designing / implementing a solution to this proposal, we should carefully consider the work done in

• MedIO
  • See discussion on issue #827

8) Extras Benefits

Note that this object factory mechanism could also be used to specify alternative implementations of other aspects of an experiments, e.g., alternative transforms, etc.