GridPatch to Extract Tiles/Patches

docs/source/transforms.rst

@@ -737,6 +737,18 @@ Spatial
     :members:
     :special-members: __call__
 
+`GridPatch`
+"""""""""""
+.. autoclass:: GridPatch
+    :members:
+    :special-members: __call__
+
+`RandGridPatch`
+"""""""""""""""
+.. autoclass:: RandGridPatch
+    :members:
+    :special-members: __call__
+
 `GridSplit`
 """""""""""
 .. autoclass:: GridSplit
@@ -1513,6 +1525,18 @@ Spatial (Dict)
     :members:
     :special-members: __call__
 
+`GridPatchd`
+""""""""""""
+.. autoclass:: GridPatchd
+    :members:
+    :special-members: __call__
+
+`RandGridPatchd`
+""""""""""""""""
+.. autoclass:: RandGridPatchd
+    :members:
+    :special-members: __call__
+
 `GridSplitd`
 """"""""""""
 .. autoclass:: GridSplitd

monai/apps/pathology/transforms/spatial/array.py

@@ -17,12 +17,13 @@
 
 from monai.config.type_definitions import NdarrayOrTensor
 from monai.transforms.transform import Randomizable, Transform
-from monai.utils import convert_data_type, convert_to_dst_type
+from monai.utils import convert_data_type, convert_to_dst_type, deprecated
 from monai.utils.enums import TransformBackends
 
 __all__ = ["SplitOnGrid", "TileOnGrid"]
 
 
+@deprecated(since="0.8", msg_suffix="use `monai.transforms.GridSplit` instead.")
 class SplitOnGrid(Transform):
     """
     Split the image into patches based on the provided grid shape.
@@ -107,6 +108,7 @@ def get_params(self, image_size):
         return patch_size, steps
 
 
+@deprecated(since="0.8", msg_suffix="use `monai.transforms.GridPatch` or `monai.transforms.RandGridPatch` instead.")
 class TileOnGrid(Randomizable, Transform):
     """
     Tile the 2D image into patches on a grid and maintain a subset of it.

monai/apps/pathology/transforms/spatial/dictionary.py

@@ -15,12 +15,14 @@
 from monai.config import KeysCollection
 from monai.config.type_definitions import NdarrayOrTensor
 from monai.transforms.transform import MapTransform, Randomizable
+from monai.utils import deprecated
 
 from .array import SplitOnGrid, TileOnGrid
 
 __all__ = ["SplitOnGridd", "SplitOnGridD", "SplitOnGridDict", "TileOnGridd", "TileOnGridD", "TileOnGridDict"]
 
 
+@deprecated(since="0.8", msg_suffix="use `monai.transforms.GridSplitd` instead.")
 class SplitOnGridd(MapTransform):
     """
     Split the image into patches based on the provided grid shape.
@@ -55,6 +57,7 @@ def __call__(self, data: Mapping[Hashable, NdarrayOrTensor]) -> Dict[Hashable, N
         return d
 
 
+@deprecated(since="0.8", msg_suffix="use `monai.transforms.GridPatchd` or `monai.transforms.RandGridPatchd` instead.")
 class TileOnGridd(Randomizable, MapTransform):
     """
     Tile the 2D image into patches on a grid and maintain a subset of it.

monai/data/wsi_datasets.py

@@ -206,13 +206,13 @@ def __init__(
                     elif isinstance(offset_limits[0], tuple):
                         self.offset_limits = offset_limits
                     else:
-                        ValueError(
+                        raise ValueError(
                             "The offset limits should be either a tuple of integers or tuple of tuple of integers."
                         )
                 else:
-                    ValueError("The offset limits should be a tuple.")
+                    raise ValueError("The offset limits should be a tuple.")
             else:
-                ValueError(
+                raise ValueError(
                     f'Invalid string for offset "{offset}". It should be either "random" as a string,'
                     "an integer, or a tuple of integers defining the offset."
                 )
@@ -238,15 +238,15 @@ def _evaluate_patch_coordinates(self, sample):
         """Define the location for each patch based on sliding-window approach"""
         patch_size = self._get_size(sample)
         level = self._get_level(sample)
-        start_pos = self._get_offset(sample)
+        offset = self._get_offset(sample)
 
         wsi_obj = self._get_wsi_object(sample)
         wsi_size = self.wsi_reader.get_size(wsi_obj, 0)
         downsample = self.wsi_reader.get_downsample_ratio(wsi_obj, level)
         patch_size_ = tuple(p * downsample for p in patch_size)  # patch size at level 0
         locations = list(
             iter_patch_position(
-                image_size=wsi_size, patch_size=patch_size_, start_pos=start_pos, overlap=self.overlap, padded=False
+                image_size=wsi_size, patch_size=patch_size_, start_pos=offset, overlap=self.overlap, padded=False
             )
         )
         sample["size"] = patch_size

monai/data/wsi_reader.py

@@ -278,7 +278,7 @@ def __init__(self, backend="cucim", level: int = 0, **kwargs):
         elif self.backend == "openslide":
             self.reader = OpenSlideWSIReader(level=level, **kwargs)
         else:
-            raise ValueError("The supported backends are: cucim")
+            raise ValueError(f"The supported backends are cucim and openslide, '{self.backend}' was given.")
         self.supported_suffixes = self.reader.supported_suffixes
 
     def get_level_count(self, wsi) -> int:

monai/transforms/__init__.py

@@ -311,6 +311,7 @@
     AffineGrid,
     Flip,
     GridDistortion,
+    GridPatch,
     GridSplit,
     Orientation,
     Rand2DElastic,
@@ -321,6 +322,7 @@
     RandDeformGrid,
     RandFlip,
     RandGridDistortion,
+    RandGridPatch,
     RandRotate,
     RandRotate90,
     RandZoom,
@@ -343,6 +345,9 @@
     GridDistortiond,
     GridDistortionD,
     GridDistortionDict,
+    GridPatchd,
+    GridPatchD,
+    GridPatchDict,
     GridSplitd,
     GridSplitD,
     GridSplitDict,
@@ -367,6 +372,9 @@
     RandGridDistortiond,
     RandGridDistortionD,
     RandGridDistortionDict,
+    RandGridPatchd,
+    RandGridPatchD,
+    RandGridPatchDict,
     RandRotate90d,
     RandRotate90D,
     RandRotate90Dict,

monai/transforms/spatial/array.py

@@ -22,13 +22,21 @@
 
 from monai.config import USE_COMPILED, DtypeLike
 from monai.config.type_definitions import NdarrayOrTensor
-from monai.data.utils import AFFINE_TOL, compute_shape_offset, reorient_spatial_axes, to_affine_nd, zoom_affine
+from monai.data.utils import (
+    AFFINE_TOL,
+    compute_shape_offset,
+    iter_patch,
+    reorient_spatial_axes,
+    to_affine_nd,
+    zoom_affine,
+)
 from monai.networks.layers import AffineTransform, GaussianFilter, grid_pull
 from monai.networks.utils import meshgrid_ij, normalize_transform
 from monai.transforms.croppad.array import CenterSpatialCrop, Pad
 from monai.transforms.intensity.array import GaussianSmooth
 from monai.transforms.transform import Randomizable, RandomizableTransform, ThreadUnsafe, Transform
 from monai.transforms.utils import (
+    convert_pad_mode,
     create_control_grid,
     create_grid,
     create_rotate,
@@ -44,6 +52,7 @@
     InterpolateMode,
     NumpyPadMode,
     PytorchPadMode,
+    convert_to_dst_type,
     ensure_tuple,
     ensure_tuple_rep,
     ensure_tuple_size,
@@ -53,10 +62,10 @@
     pytorch_after,
 )
 from monai.utils.deprecate_utils import deprecated_arg
-from monai.utils.enums import TransformBackends
+from monai.utils.enums import GridPatchSort, TransformBackends
 from monai.utils.misc import ImageMetaKey as Key
 from monai.utils.module import look_up_option
-from monai.utils.type_conversion import convert_data_type, convert_to_dst_type
+from monai.utils.type_conversion import convert_data_type
 
 nib, has_nib = optional_import("nibabel")
 
@@ -68,6 +77,8 @@
     "Flip",
     "GridDistortion",
     "GridSplit",
+    "GridPatch",
+    "RandGridPatch",
     "Resize",
     "Rotate",
     "Zoom",
@@ -2577,7 +2588,6 @@ def __call__(
                 image,
                 shape=(*self.grid, n_channels, split_size[0], split_size[1]),
                 strides=(x_stride * x_step, y_stride * y_step, c_stride, x_stride, y_stride),
-                writeable=False,
             )
             # Flatten the first two dimensions
             strided_image = strided_image.reshape(-1, *strided_image.shape[2:])
@@ -2609,3 +2619,161 @@ def _get_params(
         )
 
         return size, steps
+
+
+class GridPatch(Transform):
+    """
+    Extract all the patches sweeping the entire image in a row-major sliding-window manner with possible overlaps.
+    It can sort the patches and return all or a subset of them.
+
+    Args:
+        patch_size: size of patches to generate slices for, 0 or None selects whole dimension
+        offset: offset of starting position in the array, default is 0 for each dimension.
+        num_patches: number of patches to return. Defaults to None, which returns all the available patches.
+        overlap: the amount of overlap of neighboring patches in each dimension (a value between 0.0 and 1.0).
+            If only one float number is given, it will be applied to all dimensions. Defaults to 0.0.
+        sort_fn: a callable or string that defines the order of the patches to be returned. If it is a callable, it
+            will be passed directly to the `key` argument of `sorted` function. The string can be "min" or "max",
+            which are, respectively, the minimum and maximum of the sum of intensities of a patch across all dimensions
+            and channels. Also "random" creates a random order of patches.
+            By default no sorting is being done and patches are returned in a row-major order.
+        pad_mode: refer to  NumpyPadMode and PytorchPadMode. Defaults to ``"constant"``.
+        pad_kwargs: other arguments for the `np.pad` or `torch.pad` function.
+
+    """
+
+    backend = [TransformBackends.TORCH, TransformBackends.NUMPY]
+
+    def __init__(
+        self,
+        patch_size: Sequence[int],
+        offset: Sequence[int] = (),
+        num_patches: Optional[int] = None,
+        overlap: Union[Sequence[float], float] = 0.0,
+        sort_fn: Optional[Union[Callable, str]] = None,
+        pad_mode: Union[NumpyPadMode, PytorchPadMode, str] = NumpyPadMode.CONSTANT,
+        **pad_kwargs,
+    ):
+        self.patch_size = ensure_tuple(patch_size)
+        self.offset = ensure_tuple(offset)
+        self.pad_mode: NumpyPadMode = convert_pad_mode(dst=np.zeros(1), mode=pad_mode)
+        self.pad_kwargs = pad_kwargs
+        self.overlap = overlap
+        self.num_patches = num_patches
+        self.sort_fn: Optional[Callable]
+        if isinstance(sort_fn, str):
+            if sort_fn == GridPatchSort.RANDOM.value:
+                self.sort_fn = np.random.random
+            elif sort_fn == GridPatchSort.MIN.value:
+                self.sort_fn = self.get_patch_sum
+            elif sort_fn == GridPatchSort.MAX.value:
+                self.sort_fn = self.get_negative_patch_sum
+            else:
+                raise ValueError(
+                    f'sort_fn should be one of the following values, "{sort_fn}" was given:',
+                    [enum.value for enum in GridPatchSort],
+                )
+        else:
+            self.sort_fn = sort_fn
+
+    @staticmethod
+    def get_patch_sum(x):
+        return x[0].sum()
+
+    @staticmethod
+    def get_negative_patch_sum(x):
+        return -x[0].sum()
+
+    def __call__(self, array: NdarrayOrTensor):
+        # create the patch iterator which sweeps the image row-by-row
+        array_np, *_ = convert_data_type(array, np.ndarray)
+        patch_iterator = iter_patch(
+            array_np,
+            patch_size=(None,) + self.patch_size,  # expand to have the channel dim
+            start_pos=(0,) + self.offset,  # expand to have the channel dim
+            overlap=self.overlap,
+            copy_back=False,
+            mode=self.pad_mode,
+            **self.pad_kwargs,
+        )
+        if self.sort_fn is not None:
+            output = sorted(patch_iterator, key=self.sort_fn)
+        else:
+            output = list(patch_iterator)
+        if self.num_patches:
+            output = output[: self.num_patches]
+            if len(output) < self.num_patches:
+                patch = np.full((array.shape[0], *self.patch_size), self.pad_kwargs.get("constant_values", 0))
+                slices = np.zeros((3, len(self.patch_size)))
+                output += [(patch, slices)] * (self.num_patches - len(output))
+
+        output = [convert_to_dst_type(src=patch, dst=array)[0] for patch in output]
+
+        return output
+
+
+class RandGridPatch(GridPatch, RandomizableTransform):
+    """
+    Extract all the patches sweeping the entire image in a row-major sliding-window manner with possible overlaps,
+    and with random offset for the minimal corner of the image, (0,0) for 2D and (0,0,0) for 3D.
+    It can sort the patches and return all or a subset of them.
+
+    Args:
+        patch_size: size of patches to generate slices for, 0 or None selects whole dimension
+        min_offset: the minimum range of offset to be selected randomly. Defaults to 0.
+        max_offset: the maximum range of offset to be selected randomly.
+            Defaults to image size modulo patch size.
+        num_patches: number of patches to return. Defaults to None, which returns all the available patches.
+        overlap: the amount of overlap of neighboring patches in each dimension (a value between 0.0 and 1.0).
+            If only one float number is given, it will be applied to all dimensions. Defaults to 0.0.
+        sort_fn: a callable or string that defines the order of the patches to be returned. If it is a callable, it
+            will be passed directly to the `key` argument of `sorted` function. The string can be "min" or "max",
+            which are, respectively, the minimum and maximum of the sum of intensities of a patch across all dimensions
+            and channels. Also "random" creates a random order of patches.
+            By default no sorting is being done and patches are returned in a row-major order.
+        pad_mode: refer to  NumpyPadMode and PytorchPadMode. Defaults to ``"constant"``.
+        pad_kwargs: other arguments for the `np.pad` or `torch.pad` function.
+
+    """
+
+    backend = [TransformBackends.TORCH, TransformBackends.NUMPY]
+
+    def __init__(
+        self,
+        patch_size: Sequence[int],
+        min_offset: Optional[Union[Sequence[int], int]] = None,
+        max_offset: Optional[Union[Sequence[int], int]] = None,
+        num_patches: Optional[int] = None,
+        overlap: Union[Sequence[float], float] = 0.0,
+        sort_fn: Optional[Union[Callable, str]] = None,
+        pad_mode: Union[NumpyPadMode, PytorchPadMode, str] = NumpyPadMode.CONSTANT,
+        **pad_kwargs,
+    ):
+        super().__init__(
+            patch_size=patch_size,
+            offset=(),
+            num_patches=num_patches,
+            overlap=overlap,
+            sort_fn=sort_fn,
+            pad_mode=pad_mode,
+            **pad_kwargs,
+        )
+        self.min_offset = min_offset
+        self.max_offset = max_offset
+
+    def randomize(self, array):
+        if self.min_offset is None:
+            min_offset = (0,) * len(self.patch_size)
+        else:
+            min_offset = ensure_tuple_rep(self.min_offset, len(self.patch_size))
+        if self.max_offset is None:
+            max_offset = tuple(s % p for s, p in zip(array.shape[1:], self.patch_size))
+        else:
+            max_offset = ensure_tuple_rep(self.max_offset, len(self.patch_size))
+
+        self.offset = tuple(self.R.randint(low=low, high=high + 1) for low, high in zip(min_offset, max_offset))
+
+    def __call__(self, array: NdarrayOrTensor, randomize: bool = True):
+        if randomize:
+            self.randomize(array)
+        return super().__call__(array)