♻️ Use input_resolutions instead of resolution

- Use `input_resolutions` instead of resolution to make engines outputs compatible with ioconfig.
- Uses input resolution as a list of dictionaries on units and resolution.

Author: shaneahmed

tests/engines/test_engine_abc.py

@@ -530,7 +530,7 @@ def test_io_config_delegation(tmp_path: Path, caplog: pytest.LogCaptureFixture)
             patch_mode=True,
             save_dir=tmp_path / "dump",
             patch_input_shape=kwargs["patch_input_shape"],
-            resolution=kwargs["resolution"],
+            input_resolutions=kwargs["resolution"],
             units=kwargs["units"],
         )
         assert "provide a valid ModelIOConfigABC" in caplog.text
@@ -570,7 +570,7 @@ def test_io_config_delegation(tmp_path: Path, caplog: pytest.LogCaptureFixture)
         images=np.zeros((10, 224, 224, 3), dtype=np.uint8),
         patch_input_shape=(300, 300),
         stride_shape=(300, 300),
-        resolution=1.99,
+        input_resolutions=1.99,
         units="baseline",
         patch_mode=True,
         save_dir=f"{tmp_path}/dump",
@@ -585,7 +585,7 @@ def test_io_config_delegation(tmp_path: Path, caplog: pytest.LogCaptureFixture)
         images=np.zeros((10, 224, 224, 3), dtype=np.uint8),
         patch_input_shape=(300, 300),
         stride_shape=(300, 300),
-        resolution=None,
+        input_resolutions=None,
         units=None,
         patch_mode=True,
         save_dir=f"{tmp_path}/dump",
@@ -599,7 +599,7 @@ def test_io_config_delegation(tmp_path: Path, caplog: pytest.LogCaptureFixture)
         ioconfig=None,
         patch_input_shape=(300, 300),
         stride_shape=(300, 300),
-        resolution=1.99,
+        input_resolutions=1.99,
         units="baseline",
     )
 
@@ -620,6 +620,6 @@ def test_io_config_delegation(tmp_path: Path, caplog: pytest.LogCaptureFixture)
                 ioconfig=None,
                 patch_input_shape=_kwargs["patch_input_shape"],
                 stride_shape=(1, 1),
-                resolution=_kwargs["resolution"],
+                input_resolutions=_kwargs["resolution"],
                 units=_kwargs["units"],
             )

tests/engines/test_patch_predictor.py

@@ -1,4 +1,4 @@
-"""Test for Patch Predictor."""
+"""Test PatchPredictor."""
 
 from __future__ import annotations
 
@@ -134,7 +134,7 @@ def test_io_config_delegation(remote_sample: Callable, tmp_path: Path) -> None:
 
     predictor.run(
         images=[mini_wsi_svs],
-        resolution=1.99,
+        input_resolutions=1.99,
         patch_mode=False,
         save_dir=f"{tmp_path}/dump",
     )
@@ -153,7 +153,7 @@ def test_io_config_delegation(remote_sample: Callable, tmp_path: Path) -> None:
     predictor.run(
         images=[mini_wsi_svs],
         units="level",
-        resolution=0,
+        input_resolutions=0,
         patch_mode=False,
         save_dir=f"{tmp_path}/dump",
     )
@@ -164,7 +164,7 @@ def test_io_config_delegation(remote_sample: Callable, tmp_path: Path) -> None:
     predictor.run(
         images=[mini_wsi_svs],
         units="power",
-        resolution=20,
+        input_resolutions=20,
         patch_mode=False,
         save_dir=f"{tmp_path}/dump",
     )

tiatoolbox/models/engine/engine_abc.py

@@ -35,7 +35,7 @@
 
     from tiatoolbox.annotation import AnnotationStore
     from tiatoolbox.models.models_abc import ModelABC
-    from tiatoolbox.typing import IntPair, Resolution, Units
+    from tiatoolbox.type_hints import IntPair, Resolution, Units
     from tiatoolbox.wsicore.wsireader import WSIReader
 
 
@@ -132,7 +132,7 @@ class EngineABCRunParams(TypedDict, total=False):
             Shape of patches input to the model as tuple of height and width (HW).
             Patches are requested at read resolution, not with respect to level 0,
             and must be positive.
-        resolution (Resolution):
+        input_resolutions (Resolution):
             Resolution used for reading the image. Please see
             :class:`WSIReader` for details.
         scale_factor (tuple[float, float]):
@@ -164,7 +164,7 @@ class EngineABCRunParams(TypedDict, total=False):
     num_post_proc_workers: int
     output_file: str
     patch_input_shape: IntPair
-    resolution: Resolution
+    input_resolutions: Resolution
     return_labels: bool
     scale_factor: tuple[float, float]
     stride_shape: IntPair
@@ -242,7 +242,7 @@ class EngineABC(ABC):  # noqa: B024
             Runtime ioconfig.
         return_labels (bool):
             Whether to return the labels with the predictions.
-        resolution (Resolution):
+        input_resolutions (Resolution):
             Resolution used for reading the image. Please see
             :obj:`WSIReader` for details.
         units (Units):
@@ -283,7 +283,7 @@ class EngineABC(ABC):  # noqa: B024
             Number of workers to postprocess the results of the model.
         return_labels (bool):
             Whether to return the output labels. Default value is False.
-        resolution (Resolution):
+        input_resolutions (Resolution):
             Resolution used for reading the image. Please see
             :class:`WSIReader` for details.
             When `patch_mode` is True, the input image patches are expected to be at
@@ -371,7 +371,7 @@ def __init__(
         self.num_loader_workers = num_loader_workers
         self.num_post_proc_workers = num_post_proc_workers
         self.patch_input_shape: IntPair | None = None
-        self.resolution: Resolution | None = None
+        self.input_resolutions: Resolution | None = None
         self.return_labels: bool = False
         self.stride_shape: IntPair | None = None
         self.units: Units | None = None
@@ -791,7 +791,7 @@ def _update_ioconfig(
         ioconfig: ModelIOConfigABC,
         patch_input_shape: IntPair,
         stride_shape: IntPair,
-        resolution: Resolution,
+        input_resolutions: Resolution,
         units: Units,
     ) -> ModelIOConfigABC:
         """Update IOConfig.
@@ -808,7 +808,7 @@ def _update_ioconfig(
                 at requested read resolution, not with respect to
                 level 0, and must be positive. If not provided,
                 `stride_shape=patch_input_shape`.
-            resolution (Resolution):
+            input_resolutions (Resolution):
                 Resolution used for reading the image. Please see
                 :obj:`WSIReader` for details.
             units (Units):
@@ -820,7 +820,7 @@ def _update_ioconfig(
         """
         config_flag = (
             patch_input_shape is None,
-            resolution is None,
+            input_resolutions is None,
             units is None,
         )
         if isinstance(ioconfig, ModelIOConfigABC):
@@ -845,15 +845,15 @@ def _update_ioconfig(
                 ioconfig.patch_input_shape = patch_input_shape
             if stride_shape is not None:
                 ioconfig.stride_shape = stride_shape
-            if resolution is not None:
-                ioconfig.input_resolutions[0]["resolution"] = resolution
+            if input_resolutions is not None:
+                ioconfig.input_resolutions[0]["resolution"] = input_resolutions
             if units is not None:
                 ioconfig.input_resolutions[0]["units"] = units
 
             return ioconfig
 
         return ModelIOConfigABC(
-            input_resolutions=[{"resolution": resolution, "units": units}],
+            input_resolutions=[{"resolution": input_resolutions, "units": units}],
             patch_input_shape=patch_input_shape,
             stride_shape=stride_shape,
             output_resolutions=[],
@@ -955,7 +955,7 @@ def _update_run_params(
             ioconfig,
             self.patch_input_shape,
             self.stride_shape,
-            self.resolution,
+            self.input_resolutions,
             self.units,
         )
 

tiatoolbox/models/engine/io_config.py

@@ -8,7 +8,7 @@
 import numpy as np
 
 if TYPE_CHECKING:  # pragma: no cover
-    from tiatoolbox.typing import Units
+    from tiatoolbox.type_hints import Units
 
 
 @dataclass
@@ -69,6 +69,7 @@ def __post_init__(self: ModelIOConfigABC) -> None:
             self.stride_shape = self.patch_input_shape
 
         self.resolution_unit = self.input_resolutions[0]["units"]
+        self.highest_input_resolution = self.input_resolutions[0]["resolution"]
 
         if self.resolution_unit == "mpp":
             self.highest_input_resolution = min(

tiatoolbox/models/engine/patch_predictor.py

@@ -58,7 +58,7 @@ class PredictorRunParams(EngineABCRunParams):
             Shape of patches input to the model as tuple of height and width (HW).
             Patches are requested at read resolution, not with respect to level 0,
             and must be positive.
-        resolution (Resolution):
+        input_resolutions (Resolution):
             Resolution used for reading the image. Please see
             :class:`WSIReader` for details.
         return_probabilities (bool):
@@ -239,7 +239,7 @@ class PatchPredictor(EngineABC):
             Runtime ioconfig.
         return_labels (bool):
             Whether to return the labels with the predictions.
-        resolution (Resolution):
+        input_resolutions (Resolution):
             Resolution used for reading the image. Please see
             :obj:`WSIReader` for details.
         units (Units):
@@ -280,7 +280,7 @@ class PatchPredictor(EngineABC):
             Number of workers to postprocess the results of the model.
         return_labels (bool):
             Whether to return the output labels. Default value is False.
-        resolution (Resolution):
+        input_resolutions (Resolution):
             Resolution used for reading the image. Please see
             :class:`WSIReader` for details.
             When `patch_mode` is True, the input image patches are expected to be at
@@ -301,27 +301,27 @@ class PatchPredictor(EngineABC):
         >>> # list of 2 image patches as input
         >>> data = ['path/img.svs', 'path/img.svs']
         >>> predictor = PatchPredictor(model="resnet18-kather100k")
-        >>> output = predictor.run(data, mode='patch')
+        >>> output = predictor.run(data, patch_mode=False)
 
         >>> # array of list of 2 image patches as input
         >>> data = np.array([img1, img2])
         >>> predictor = PatchPredictor(model="resnet18-kather100k")
-        >>> output = predictor.run(data, mode='patch')
+        >>> output = predictor.run(data, patch_mode=True)
 
         >>> # list of 2 image patch files as input
         >>> data = ['path/img.png', 'path/img.png']
         >>> predictor = PatchPredictor(model="resnet18-kather100k")
-        >>> output = predictor.run(data, mode='patch')
+        >>> output = predictor.run(data, patch_mode=True)
 
         >>> # list of 2 image tile files as input
         >>> tile_file = ['path/tile1.png', 'path/tile2.png']
         >>> predictor = PatchPredictor(model="resnet18-kather100k")
-        >>> output = predictor.run(tile_file, mode='tile')
+        >>> output = predictor.run(tile_file, patch_mode=False)
 
         >>> # list of 2 wsi files as input
         >>> wsi_file = ['path/wsi1.svs', 'path/wsi2.svs']
         >>> predictor = PatchPredictor(model="resnet18-kather100k")
-        >>> output = predictor.run(wsi_file, mode='wsi')
+        >>> output = predictor.run(wsi_file, patch_mode=False)
 
     References:
         [1] Kather, Jakob Nikolas, et al. "Predicting survival from colorectal cancer
@@ -517,6 +517,7 @@ def run(
 
         Examples:
             >>> wsis = ['wsi1.svs', 'wsi2.svs']
+            >>> image_patches = [np.ndarray, np.ndarray]
             >>> class PatchPredictor(EngineABC):
             >>> # Define all Abstract methods.
             >>>     ...