image data reader and LoadImage transform refactoring

[wyli]

This is a follow-up of #856 to track the progress of a preliminary IO refactoring.

Goal

The main goal of this ticket is to create a file format agnostic wrapper for the image inputs (LoadImage and LoadImaged).
A typical use case (enhancing the current NiftiDataset) is:

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

where images and segs are filenames, ImageDataset internally invokes LoadImage.

Or using a generic monai Dataset API, specify the first component of train_imtrans as a LoadImage transform that extracts data array and meta data from the file.

More specifically:

Reader （file format-specific component)

1. [format]reader are themselves monai data components (users can use the readers without going through the LoadImage logic), they call external package APIs
2. [format]reader share the same superclass ImageReader interface (for handling physical/voxel resolution, orientation...)

class ImageReader:
    def get_data(self, ...):
        # return the data in the designated resolution, orientation, 
        # image channel selector, the relevant coordinates, datatype
    
    def read(self, ...):
        # create an IO object instance or a set of instances

3. users can make customized MyReader by implementing the ImageReader interface
4. the customized MyReader could be registered with the LoadImage factory

@register_reader(requires='my_external_library')
class MyReader(ImageReader):
    ...

LoadImage（file format agnostic component)

1. LoadImage is a monai transform
2. LoadImaged should return the same underlying data representation dictionary regardless of the image format.
3. LoadImage may choose a suitable [format]reader dynamically at runtime based on the following rules (ordered from high to low priority):

• user's selection of a specific reader, such as LoadImage(reader='ITkReader')
• try any user-registered readers
• try resources map based on a global property file and filename extensions:

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

• fails early and preserves detailed error messages

additional requirements

• should be able to specify versions of external reader to ensure reproducibility
• need to have consistent coordinate systems, resolution conventions

tasks

• implement interface ImageReader, factory (transforms) LoadImage LoadImaged
• implement ITKReader, NibabelReader, NumpyReader, PILReader?
• LoadImage selecting readers according to the preference list
• new interfaces tutorial 17 Add load medical image notebook tutorials#19
• deprecate NiftiDataset, add ImageDataset
• deprecate LoadNifti, LoadPNG, LoadNumpy, LoadDatad
• revise/check all examples demos

[wyli]

thanks for the discussion @Nic-Ma let's use this ticket to raise any detailed technical issues

[Nic-Ma]

Mark: completed 2 tasks in the list, will work on NumpyReader, PILReader in the next PR.
Thanks.

[wyli]

before deprecating the previous loaders, would be very helpful to have a new tutorial to demonstrate the new interfaces, what do you think @Nic-Ma?

[Nic-Ma]

Hi @wyli ,

Sounds good a plan.
Please submit a ticket and assign it to me.

Thanks.

[wyli]

this ticket is currently blocked at InsightSoftwareConsortium/ITK#2003 because the default is

MONAI/monai/transforms/io/array.py

Lines 62 to 63 in 99f7a43

	self.default_reader: ITKReader = ITKReader()
	self.readers: List[ImageReader] = list()

[Nic-Ma]

Here is the plan for this ticket in v0.4 development:

1. Change the default reader of LoadImage to Nibabel.
2. Add string support for the reader parameter.
3. Update all the examples and tutorials to use LoadImage transform.

Thanks.

[Nic-Ma]

Will deprecate NiftiDataset, add ImageDataset in another separate PR later.
Thanks.