Merge branch 'develop' into ref-highlevel-import-engines

examples/full-pipelines/slide-graph.ipynb

@@ -629,7 +629,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from tiatoolbox.wsicore.wsireader import WSIReader\n",
+    "from tiatoolbox.wsicore.wsireader import WSIReader, Resolution, Units\n",
     "from tiatoolbox.models import NucleusInstanceSegmentor\n",
     "from tiatoolbox.tools.patchextraction import PatchExtractor\n",
     "from shapely.geometry import box as shapely_box\n",
@@ -643,8 +643,8 @@
     "    num_types: int = 6,\n",
     "    patch_input_shape: Tuple[int] = (512, 512),\n",
     "    stride_shape: Tuple[int] = (512, 512),\n",
-    "    resolution: float = 0.25,\n",
-    "    units: str = \"mpp\",\n",
+    "    resolution: Resolution = 0.25,\n",
+    "    units: Units = \"mpp\",\n",
     "):\n",
     "    \"\"\"\n",
     "    Args:\n",

examples/inference-pipelines/slide-graph.ipynb

@@ -604,6 +604,7 @@
    },
    "outputs": [],
    "source": [
+    "from tiatoolbox.wsicore.wsimeta import Resolution, Units\n",
     "from tiatoolbox.wsicore.wsireader import WSIReader\n",
     "from tiatoolbox.models import NucleusInstanceSegmentor\n",
     "from tiatoolbox.tools.patchextraction import PatchExtractor\n",
@@ -618,8 +619,8 @@
     "    num_types: int = 6,\n",
     "    patch_input_shape: Tuple[int] = (512, 512),\n",
     "    stride_shape: Tuple[int] = (512, 512),\n",
-    "    resolution: float = 0.25,\n",
-    "    units: str = \"mpp\",\n",
+    "    resolution: Resolution = 0.25,\n",
+    "    units: Units = \"mpp\",\n",
     "):\n",
     "    \"\"\"\n",
     "    Args:\n",

tiatoolbox/models/engine/patch_predictor.py

@@ -15,6 +15,7 @@
 from tiatoolbox.models.dataset.classification import PatchDataset, WSIPatchDataset
 from tiatoolbox.models.engine.semantic_segmentor import IOSegmentorConfig
 from tiatoolbox.utils import misc, save_as_json
+from tiatoolbox.wsicore.wsimeta import Resolution, Units
 from tiatoolbox.wsicore.wsireader import VirtualWSIReader, WSIReader
 
 
@@ -252,8 +253,8 @@ def __init__(
     def merge_predictions(
         img: Union[str, pathlib.Path, np.ndarray],
         output: dict,
-        resolution: float = None,
-        units: str = None,
+        resolution: Resolution = None,
+        units: Units = None,
         postproc_func: Callable = None,
         return_raw: bool = False,
     ):
@@ -270,9 +271,9 @@ def merge_predictions(
               A HWC image or a path to WSI.
             output (dict):
                 Output generated by the model.
-            resolution (float):
+            resolution (Resolution):
                 Resolution of merged predictions.
-            units (str):
+            units (Units):
                 Units of resolution used when merging predictions. This
                 must be the same `units` used when processing the data.
             postproc_func (callable):
@@ -470,13 +471,11 @@ 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 (float):
+        resolution (Resolution):
             Resolution used for reading the image. Please see
             :obj:`WSIReader` for details.
-        units (str):
-            Units of resolution used for reading the image. Choose
-            from either `level`, `power` or `mpp`. Please see
-            :obj:`WSIReader` for details.
+        units (Units):
+            Units of resolution used for reading the image.
 
         Returns:
             Updated Patch Predictor IO configuration.
@@ -794,10 +793,10 @@ def predict(
                 at requested read resolution, not with respect to
                 level 0, and must be positive. If not provided,
                 `stride_shape=patch_input_shape`.
-            resolution (float):
+            resolution (Resolution):
                 Resolution used for reading the image. Please see
                 :obj:`WSIReader` for details.
-            units (str):
+            units (Units):
                 Units of resolution used for reading the image. Choose
                 from either `level`, `power` or `mpp`. Please see
                 :obj:`WSIReader` for details.

tiatoolbox/models/engine/semantic_segmentor.py

@@ -23,6 +23,7 @@
 from tiatoolbox.models.models_abc import IOConfigABC
 from tiatoolbox.tools.patchextraction import PatchExtractor
 from tiatoolbox.utils import imread, misc
+from tiatoolbox.wsicore.wsimeta import Resolution, Units
 from tiatoolbox.wsicore.wsireader import VirtualWSIReader, WSIMeta, WSIReader
 
 
@@ -195,7 +196,7 @@ def _validate(self):
             raise ValueError(f"Invalid resolution units `{units[0]}`.")
 
     @staticmethod
-    def scale_to_highest(resolutions: List[dict], units: str):
+    def scale_to_highest(resolutions: List[dict], units: Units):
         """Get the scaling factor from input resolutions.
 
         This will convert resolutions to a scaling factor with respect to
@@ -205,7 +206,7 @@ def scale_to_highest(resolutions: List[dict], units: str):
             resolutions (list):
                 A list of resolutions where one is defined as
                 `{'resolution': value, 'unit': value}`
-            units (str):
+            units (Units):
                 Units that the resolutions are at.
 
         Returns:
@@ -601,8 +602,8 @@ def get_coordinates(
     def filter_coordinates(
         mask_reader: VirtualWSIReader,
         bounds: np.ndarray,
-        resolution: Union[float, int] = None,
-        units: str = None,
+        resolution: Resolution = None,
+        units: Units = None,
     ):
         """
         Indicates which coordinate is valid basing on the mask.
@@ -624,7 +625,10 @@ def filter_coordinates(
                 default `func=None`, K should be 4, as we expect the
                 `coordinates` to be bounding boxes in `[start_x,
                 start_y, end_x, end_y]` format.
-
+            resolution (Resolution):
+                Resolution of the requested patch.
+            units (Units):
+                Units of the requested patch.
         Returns:
             :class:`numpy.ndarray`:
                 List of flags to indicate which coordinate is valid.
@@ -1044,11 +1048,10 @@ def _update_ioconfig(
                 are at requested read resolution and must be positive.
                 If not provided, `stride_shape=patch_input_shape` is
                 used.
-            resolution (float):
+            resolution (Resolution):
                 Resolution used for reading the image.
-            units (str):
-                Units of resolution used for reading the image. Choose
-                from either `"level"`, `"power"` or `"mpp"`.
+            units (Units):
+                Units of resolution used for reading the image.
 
         Returns:
             :class:`IOSegmentorConfig`:
@@ -1244,7 +1247,7 @@ def predict(
                 used.
             resolution (float):
                 Resolution used for reading the image.
-            units (str):
+            units (Units):
                 Units of resolution used for reading the image. Choose
                 from either `"level"`, `"power"` or `"mpp"`.
             save_dir (str or pathlib.Path):
@@ -1530,11 +1533,10 @@ def predict(
                 are at requested read resolution and must be positive.
                 If not provided, `stride_shape=patch_input_shape` is
                 used.
-            resolution (float):
+            resolution (Resolution):
                 Resolution used for reading the image.
-            units (str):
-                Units of resolution used for reading the image. Choose
-                from either `"level"`, `"power"` or `"mpp"`.
+            units (Units):
+                Units of resolution used for reading the image.
             save_dir (str):
                 Output directory when processing multiple tiles and
                 whole-slide images. By default, it is folder `output`

tiatoolbox/tools/patchextraction.py

@@ -10,6 +10,7 @@
 from tiatoolbox.utils import misc
 from tiatoolbox.utils.exceptions import MethodNotSupported
 from tiatoolbox.wsicore import wsireader
+from tiatoolbox.wsicore.wsimeta import Resolution, Units
 
 
 class PatchExtractorABC(ABC):
@@ -46,19 +47,16 @@ class PatchExtractor(PatchExtractorABC):
             'morphological', a tissue mask is generated for the
             input_image using tiatoolbox :class:`TissueMasker`
             functionality.
-        resolution (int or float or tuple of float):
+        resolution (Resolution):
             Resolution at which to read the image, default = 0. Either a
             single number or a sequence of two numbers for x and y are
             valid. This value is in terms of the corresponding units.
             For example: resolution=0.5 and units="mpp" will read the
             slide at 0.5 microns per-pixel, and resolution=3,
             units="level" will read at level at pyramid level /
             resolution layer 3.
-        units (str):
-            Units of resolution, default = "level". Supported units are:
-            microns per pixel (mpp), objective power (power), pyramid /
-            resolution level (level), Only pyramid / resolution levels
-            (level) embedded in the whole slide image are supported.
+        units (Units):
+            Units of resolution, default = "level".
         pad_mode (str):
             Method for padding at edges of the WSI. Default to
             'constant'. See :func:`numpy.pad` for more information.
@@ -78,13 +76,13 @@ class PatchExtractor(PatchExtractorABC):
 
 
     Attributes:
-        wsi(WSIReader):
+        wsi (WSIReader):
             Input image for patch extraction of type :obj:`WSIReader`.
-        patch_size(tuple(int)):
+        patch_size (tuple(int)):
             Patch size tuple (width, height).
-        resolution(tuple(int)):
+        resolution (Resolution):
             Resolution at which to read the image.
-        units (str):
+        units (Units):
             Units of resolution.
         n (int):
             Current state of the iterator.
@@ -114,8 +112,8 @@ def __init__(
         input_img: Union[str, Path, np.ndarray],
         patch_size: Union[int, Tuple[int, int]],
         input_mask: Union[str, Path, np.ndarray, wsireader.WSIReader] = None,
-        resolution: Union[int, float, Tuple[float, float]] = 0,
-        units: str = "level",
+        resolution: Resolution = 0,
+        units: Units = "level",
         pad_mode: str = "constant",
         pad_constant_values: Union[int, Tuple[int, int]] = 0,
         within_bound: bool = False,
@@ -468,20 +466,16 @@ class SlidingWindowPatchExtractor(PatchExtractor):
             'morphological', a tissue mask is generated for the
             input_image using tiatoolbox :class:`TissueMasker`
             functionality.
-        resolution (int or float or tuple of float):
+        resolution (Resolution):
             Resolution at which to read the image, default = 0. Either a
             single number or a sequence of two numbers for x and y are
             valid. This value is in terms of the corresponding units.
             For example: resolution=0.5 and units="mpp" will read the
             slide at 0.5 microns per-pixel, and resolution=3,
             units="level" will read at level at pyramid level /
             resolution layer 3.
-        units (str):
-            The units of resolution, default = "level". Supported units
-            are: microns per pixel (mpp), objective power (power),
-            pyramid / resolution level (level), Only pyramid /
-            resolution levels (level) embedded in the whole slide image
-            are supported.
+        units (Units):
+            The units of resolution, default = "level".
         pad_mode (str):
             Method for padding at edges of the WSI. Default to
             'constant'. See :func:`numpy.pad` for more information.
@@ -513,8 +507,8 @@ def __init__(
         input_img: Union[str, Path, np.ndarray],
         patch_size: Union[int, Tuple[int, int]],
         input_mask: Union[str, Path, np.ndarray, wsireader.WSIReader] = None,
-        resolution: Union[int, float, Tuple[float, float]] = 0,
-        units: str = "level",
+        resolution: Resolution = 0,
+        units: Units = "level",
         stride: Union[int, Tuple[int, int]] = None,
         pad_mode: str = "constant",
         pad_constant_values: Union[int, Tuple[int, int]] = 0,
@@ -558,15 +552,15 @@ class PointsPatchExtractor(PatchExtractor):
             resolution).
         patch_size(int or tuple(int)):
             Patch size tuple (width, height).
-        resolution (int or float or tuple of float):
+        resolution (Resolution):
             Resolution at which to read the image, default = 0. Either a
             single number or a sequence of two numbers for x and y are
             valid. This value is in terms of the corresponding units.
             For example: resolution=0.5 and units="mpp" will read the
             slide at 0.5 microns per-pixel, and resolution=3,
             units="level" will read at level at pyramid level /
             resolution layer 3.
-        units (str):
+        units (Units):
             The units of resolution, default = "level". Supported units
             are: microns per pixel (mpp), objective power (power),
             pyramid / resolution level (level), Only pyramid /
@@ -593,8 +587,8 @@ def __init__(
         input_img: Union[str, Path, np.ndarray],
         locations_list: Union[np.ndarray, DataFrame, str, Path],
         patch_size: Union[int, Tuple[int, int]] = (224, 224),
-        resolution: Union[int, float, Tuple[float, float]] = 0,
-        units: str = "level",
+        resolution: Resolution = 0,
+        units: Units = "level",
         pad_mode: str = "constant",
         pad_constant_values: Union[int, Tuple[int, int]] = 0,
         within_bound: bool = False,

tiatoolbox/tools/registration/wsi_registration.py

@@ -1,6 +1,5 @@
 import itertools
-from numbers import Number
-from typing import Dict, Tuple, Union
+from typing import Dict, Tuple
 
 import cv2
 import numpy as np
@@ -16,10 +15,8 @@
 from tiatoolbox.tools.patchextraction import PatchExtractor
 from tiatoolbox.utils.metrics import dice
 from tiatoolbox.utils.transforms import imresize
-from tiatoolbox.wsicore.wsireader import VirtualWSIReader, WSIReader
-
-Resolution = Union[Number, Tuple[Number, Number], np.ndarray]
-IntBounds = Tuple[int, int, int, int]
+from tiatoolbox.wsicore.wsimeta import Resolution, Units
+from tiatoolbox.wsicore.wsireader import IntBounds, VirtualWSIReader, WSIReader
 
 
 def _check_dims(
@@ -1491,7 +1488,7 @@ def read_rect(
         location: Tuple[int, int],
         size: Tuple[int, int],
         resolution: Resolution,
-        units: str,
+        units: Units,
     ) -> np.ndarray:
         """Read a transformed region of the transformed whole slide image.
 
@@ -1504,10 +1501,10 @@ def read_rect(
                 reference frame.
             size (tuple(int)):
                 (width, height) tuple giving the desired output image size.
-            resolution (float or tuple(float)):
-                Pyramid level/resolution layer.
-            units (str):
-                Units of the scale.
+            resolution (Resolution):
+                Resolution used for reading the image.
+            units (Units):
+                Units of resolution used for reading the image.
 
         Returns:
             :class:`numpy.ndarray`:

tiatoolbox/wsicore/wsimeta.py

@@ -8,13 +8,14 @@
 """
 from numbers import Number
 from pathlib import Path
-from typing import List, Mapping, Optional, Sequence, Tuple, Union
+from typing import List, Literal, Mapping, Optional, Sequence, Tuple, Union
 
 import numpy as np
 
 from tiatoolbox import logger
 
 Resolution = Union[Number, Tuple[Number, Number], np.ndarray]
+Units = Literal["mpp", "power", "baseline", "level"]
 
 
 class WSIMeta:
@@ -208,7 +209,7 @@ def level_downsample(
         return np.interp(level, [floor, ceil], [floor_downsample, ceil_downsample])
 
     def relative_level_scales(
-        self, resolution: Resolution, units: str
+        self, resolution: Resolution, units: Units
     ) -> List[np.ndarray]:
         """Calculate scale of each level in the WSI relative to given resolution.
 
@@ -219,9 +220,9 @@ def relative_level_scales(
         target and < 1 indicates that it is smaller.
 
         Args:
-            resolution (float or tuple(float)):
+            resolution (Resolution):
                 Scale to calculate relative to units.
-            units (str):
+            units (Units):
                 Units of the scale. Allowed values are: `"mpp"`,
                 `"power"`, `"level"`, `"baseline"`. Baseline refers to
                 the largest resolution in the WSI (level 0).