adds tests and docs

Signed-off-by: Wenqi Li <[email protected]>

Author: wyli

docs/source/data.rst

@@ -74,7 +74,7 @@ Generic Interfaces
 .. autoclass:: ImageDataset
   :members:
   :special-members: __getitem__
-  
+
 `NPZDictItemDataset`
 ~~~~~~~~~~~~~~~~~~~~
 .. autoclass:: NPZDictItemDataset
@@ -108,6 +108,11 @@ Patch-based dataset
 Image reader
 ------------
 
+ImageReader
+~~~~~~~~~~~
+.. autoclass:: ImageReader
+  :members:
+
 ITKReader
 ~~~~~~~~~
 .. autoclass:: ITKReader

monai/data/image_reader.py

@@ -45,16 +45,30 @@
 
 
 class ImageReader(ABC):
-    """Abstract class to define interface APIs to load image files.
-    users need to call `read` to load image and then use `get_data`
-    to get the image data and properties from meta data.
+    """
+    An abstract class defines APIs to load image files.
+
+    Typical usage of an implementation of this class is:
+
+    .. code-block:: python
+
+        image_reader = MyImageReader()
+        img_obj = image_reader.read(path_to_image)
+        img_data, meta_data = image_reader.get_data(img_obj)
+
+    - The `read` call converts image filenames into image objects,
+    - The `get_data` call fetches the image data, as well as meta data.
+    - A reader should implement `verify_suffix` with the logic of checking the input filename
+      by the filename extensions.
 
     """
 
     @abstractmethod
     def verify_suffix(self, filename: Union[Sequence[str], str]) -> bool:
         """
-        Verify whether the specified file or files format is supported by current reader.
+        Verify whether the specified `filename` is supported by the current reader.
+        This method should return True if the reader is able to read the format suggested by the
+        `filename`.
 
         Args:
             filename: file name or a list of file names to read.
@@ -67,7 +81,7 @@ def verify_suffix(self, filename: Union[Sequence[str], str]) -> bool:
     def read(self, data: Union[Sequence[str], str], **kwargs) -> Union[Sequence[Any], Any]:
         """
         Read image data from specified file or files.
-        Note that it returns the raw data, so different readers return different image data type.
+        Note that it returns a data object or a sequence of data objects.
 
         Args:
             data: file name or a list of file names to read.
@@ -80,7 +94,8 @@ def read(self, data: Union[Sequence[str], str], **kwargs) -> Union[Sequence[Any]
     def get_data(self, img) -> Tuple[np.ndarray, Dict]:
         """
         Extract data array and meta data from loaded image and return them.
-        This function must return 2 objects, first is numpy array of image data, second is dict of meta data.
+        This function must return two objects, the first is a numpy array of image data,
+        the second is a dictionary of meta data.
 
         Args:
             img: an image object loaded from an image file or a list of image objects.
@@ -124,7 +139,7 @@ def _stack_images(image_list: List, meta_dict: Dict):
 class ITKReader(ImageReader):
     """
     Load medical images based on ITK library.
-    All the supported image formats can be found:
+    All the supported image formats can be found at:
     https://github.com/InsightSoftwareConsortium/ITK/tree/master/Modules/IO
     The loaded data array will be in C order, for example, a 3D image NumPy
     array index order will be `CDWH`.

monai/transforms/io/array.py

@@ -128,6 +128,7 @@ def __init__(self, reader=None, image_only: bool = False, dtype: DtypeLike = np.
                 self.register(SUPPORTED_READERS[r](*args, **kwargs))
             except TypeError:  # the reader doesn't have the corresponding args/kwargs
                 warnings.warn(f"{r} is not supported with the given parameters {args} {kwargs}.")
+                self.register(SUPPORTED_READERS[r]())
         if reader is None:
             return  # no user-specified reader, no need to register
 

tests/test_load_image.py

@@ -21,7 +21,24 @@
 from PIL import Image
 
 from monai.data import ITKReader, NibabelReader
-from monai.transforms import LoadImage
+from monai.transforms import SUPPORTED_READERS, LoadImage
+
+
+class _MiniReader:
+    """a test case customised reader"""
+
+    def __init__(self, is_compatible=False):
+        self.is_compatible = is_compatible
+
+    def verify_suffix(self, _name):
+        return self.is_compatible
+
+    def read(self, name):
+        return name
+
+    def get_data(self, _obj):
+        return np.zeros((1, 1, 1)), {"name": "my test"}
+
 
 TEST_CASE_1 = [{"image_only": True}, ["test_image.nii.gz"], (128, 128, 128)]
 
@@ -33,7 +50,7 @@
     (3, 128, 128, 128),
 ]
 
-TEST_CASE_3_1 = [
+TEST_CASE_3_1 = [  # .mgz format
     {"image_only": True, "reader": "nibabelreader"},
     ["test_image.mgz", "test_image2.mgz", "test_image3.mgz"],
     (3, 128, 128, 128),
@@ -45,6 +62,12 @@
     (3, 128, 128, 128),
 ]
 
+TEST_CASE_4_1 = [  # additional parameter
+    {"image_only": False, "mmap": False},
+    ["test_image.nii.gz", "test_image2.nii.gz", "test_image3.nii.gz"],
+    (3, 128, 128, 128),
+]
+
 TEST_CASE_5 = [
     {"reader": NibabelReader(mmap=False), "image_only": False},
     ["test_image.nii.gz"],
@@ -81,7 +104,9 @@
 
 
 class TestLoadImage(unittest.TestCase):
-    @parameterized.expand([TEST_CASE_1, TEST_CASE_2, TEST_CASE_3, TEST_CASE_3_1, TEST_CASE_4, TEST_CASE_5])
+    @parameterized.expand(
+        [TEST_CASE_1, TEST_CASE_2, TEST_CASE_3, TEST_CASE_3_1, TEST_CASE_4, TEST_CASE_4_1, TEST_CASE_5]
+    )
     def test_nibabel_reader(self, input_param, filenames, expected_shape):
         test_image = np.random.rand(128, 128, 128)
         with tempfile.TemporaryDirectory() as tempdir:
@@ -193,6 +218,19 @@ def test_kwargs(self):
             np.testing.assert_allclose(header["spatial_shape"], header_raw["spatial_shape"])
             self.assertTupleEqual(result.shape, result_raw.shape)
 
+    def test_my_reader(self):
+        """test customised readers"""
+        out = LoadImage(reader=_MiniReader, is_compatible=True)("test")
+        self.assertEqual(out[1]["name"], "my test")
+        out = LoadImage(reader=_MiniReader, is_compatible=False)("test")
+        self.assertEqual(out[1]["name"], "my test")
+        SUPPORTED_READERS["minireader"] = _MiniReader
+        for item in ("minireader", _MiniReader, _MiniReader(is_compatible=False)):
+            out = LoadImage(reader=item)("test")
+            self.assertEqual(out[1]["name"], "my test")
+        out = LoadImage()("test", reader=_MiniReader(is_compatible=False))
+        self.assertEqual(out[1]["name"], "my test")
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_nifti_endianness.py

@@ -12,6 +12,7 @@
 import os
 import tempfile
 import unittest
+from pathlib import Path
 from typing import TYPE_CHECKING, List, Tuple
 from unittest.case import skipUnless
 
@@ -85,6 +86,9 @@ def test_switch(self):  # verify data types
         with self.assertRaises(NotImplementedError):
             switch_endianness(np.zeros((2, 1)), "=")
 
+        with self.assertRaises(RuntimeError):
+            switch_endianness(Path("test"), "<")
+
     @skipUnless(has_pil, "Requires PIL")
     def test_pil(self):
         tempdir = tempfile.mkdtemp()