Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

image data reader and LoadImage transform refactoring #909

Closed
7 tasks done
wyli opened this issue Aug 18, 2020 · 7 comments · Fixed by #1461
Closed
7 tasks done

image data reader and LoadImage transform refactoring #909

wyli opened this issue Aug 18, 2020 · 7 comments · Fixed by #1461
Assignees

Comments

@wyli
Copy link
Contributor

wyli commented Aug 18, 2020

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
  1. users can make customized MyReader by implementing the ImageReader interface
  2. 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
Copy link
Contributor Author

wyli commented Aug 18, 2020

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

@Nic-Ma
Copy link
Contributor

Nic-Ma commented Aug 20, 2020

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

@wyli
Copy link
Contributor Author

wyli commented Sep 2, 2020

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
Copy link
Contributor

Nic-Ma commented Sep 2, 2020

Hi @wyli ,

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

Thanks.

@wyli
Copy link
Contributor Author

wyli commented Nov 30, 2020

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

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

@Nic-Ma
Copy link
Contributor

Nic-Ma commented Dec 1, 2020

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
Copy link
Contributor

Nic-Ma commented Jan 14, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants