RandomizableTransformType, LazyTransformType, and MultiSampleTransformType

monai/transforms/transform.py

@@ -26,7 +26,9 @@
 from monai.utils.enums import TransformBackends
 from monai.utils.misc import MONAIEnvVars
 
-__all__ = ["ThreadUnsafe", "apply_transform", "Randomizable", "RandomizableTransform", "Transform", "MapTransform"]
+__all__ = ["ThreadUnsafe", "apply_transform",
+           "ILazyTransform", "IRandomizableTransform", "IMultiSampleTransform",
+           "Randomizable", "RandomizableTransform", "Transform", "MapTransform"]
 
 ReturnType = TypeVar("ReturnType")
 
@@ -118,6 +120,79 @@ def _log_stats(data, prefix: Optional[str] = "Data"):
         raise RuntimeError(f"applying transform {transform}") from e
 
 
+class ILazyTransform:
+    """
+    An interface to indicate that the transform has the capability to describe
+    its operation as an affine matrix or grid with accompanying metadata. This
+    interface can be extended from by people adapting transforms to the MONAI framework as well as
+    by implementors of MONAI transforms.
+    """
+
+    @property
+    def lazy_evaluation(
+            self,
+    ):
+        """
+        Get whether lazy_evaluation is enabled for this transform instance.
+
+        Returns:
+            True if the transform is operating in a lazy fashion, False if not.
+        """
+        raise NotImplementedError()
+
+    @lazy_evaluation.setter
+    def lazy_evaluation(
+            self,
+            enabled: bool
+    ):
+        """
+        Set whether lazy_evaluation is enabled for this transform instance.
+
+        Args:
+            enabled: True if the transform should operate in a lazy fashion, False if not.
+        """
+        raise NotImplementedError()
+
+
+class IRandomizableTransform:
+    """
+    An interface to indicate that the transform has the capability to perform
+    randomized transforms to the data that it is called upon. This interface
+    can be extended from by people adapting transforms to the MONAI framework as well as by
+    implementors of MONAI transforms.
+    """
+
+    def set_random_state(
+            self,
+            seed: Optional[int] = None,
+            state: Optional[np.random.RandomState] = None
+    ) -> "IRandomizableTransform":
+        """
+        Set either the seed for an inbuilt random generator (assumed to be np.random.RandomState)
+        or set a random generator for this transform to use (again, assumed to be
+        np.random.RandomState). One one of these parameters should be set. If your random transform
+        that implements this interface doesn't support setting or reseeding of its random
+        generator, this method does not need to be implemented.
+
+        Args:
+            seed: set the random state with an integer seed.
+            state: set the random state with a `np.random.RandomState` object.
+
+        Returns:
+            self as a convenience for assignment
+        """
+        raise TypeError(f"{self.__class__.__name__} does not support setting of random state via set_random_state.")
+
+
+class IMultiSampleTransform:
+    """
+    An interface to indicate that the transform has the capability to return multiple samples
+    given an input, such as when performing random crops of a sample. This interface can be
+    extended from by people adapting transforms to the MONAI framework as well as by implementors
+    of MONAI transforms.
+    """
+
+
 class ThreadUnsafe:
     """
     A class to denote that the transform will mutate its member variables,
@@ -251,7 +326,7 @@ def __call__(self, data: Any):
         raise NotImplementedError(f"Subclass {self.__class__.__name__} must implement this method.")
 
 
-class RandomizableTransform(Randomizable, Transform):
+class RandomizableTransform(Randomizable, Transform, IRandomizableTransform):
     """
     An interface for handling random state locally, currently based on a class variable `R`,
     which is an instance of `np.random.RandomState`.

tests/test_irandomizable_transform.py

@@ -0,0 +1,41 @@
+# Copyright (c) MONAI Consortium
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+
+from monai.transforms.transform import IRandomizableTransform, RandomizableTransform
+
+
+class InheritsInterface(IRandomizableTransform):
+    pass
+
+
+class InheritsImplementation(RandomizableTransform):
+
+    def __call__(self, data):
+        return data
+
+
+class TestIRandomizableTransform(unittest.TestCase):
+
+    def test_is_irandomizable(self):
+        inst = InheritsInterface()
+        self.assertIsInstance(inst, IRandomizableTransform)
+
+    def test_set_random_state_default_impl(self):
+        inst = InheritsInterface()
+        with self.assertRaises(TypeError):
+            inst.set_random_state(seed=0)
+
+    def test_set_random_state_randomizable_transform(self):
+        inst = InheritsImplementation()
+        inst.set_random_state(0)