Merge branch 'develop' into bug-fix-numpy-upgrade

Author: shaneahmed

.github/workflows/python-package.yml

@@ -30,7 +30,7 @@ jobs:
         sudo apt update
         sudo apt-get install -y libopenjp2-7 libopenjp2-tools
         python -m pip install --upgrade pip
-        python -m pip install ruff==0.12.2 pytest pytest-cov pytest-runner
+        python -m pip install ruff==0.12.7 pytest pytest-cov pytest-runner
         pip install -r requirements/requirements.txt
     - name: Cache tiatoolbox static assets
       uses: actions/cache@v3

.pre-commit-config.yaml

@@ -60,7 +60,7 @@ repos:
       - id: rst-inline-touching-normal # Detect mistake of inline code touching normal text in rst.
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.12.2
+    rev: v0.12.7
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

requirements/requirements_dev.txt

@@ -10,7 +10,7 @@ pytest>=7.2.0
 pytest-cov>=4.0.0
 pytest-runner>=6.0
 pytest-xdist[psutil]
-ruff==0.12.2  # This will be updated by pre-commit bot to latest version
+ruff==0.12.7  # This will be updated by pre-commit bot to latest version
 toml>=0.10.2
 twine>=4.0.1
 wheel>=0.37.1

tiatoolbox/models/dataset/classification.py

@@ -163,7 +163,7 @@ class WSIPatchDataset(dataset_abc.PatchDatasetABC):
 
     """
 
-    def __init__(  # skipcq: PY-R1000  # noqa: PLR0915
+    def __init__(  # skipcq: PY-R1000
         self: WSIPatchDataset,
         img_path: str | Path,
         mode: str = "wsi",
@@ -262,40 +262,17 @@ def __init__(  # skipcq: PY-R1000  # noqa: PLR0915
             raise ValueError(msg)
 
         self.preproc_func = preproc_func
-        img_path = Path(img_path)
-        if mode == "wsi":
-            self.reader = WSIReader.open(img_path)
-        else:
-            logger.warning(
-                "WSIPatchDataset only reads image tile at "
-                '`units="baseline"` and `resolution=1.0`.',
-                stacklevel=2,
-            )
-            img = imread(img_path)
-            axes = "YXS"[: len(img.shape)]
-            # initialise metadata for VirtualWSIReader.
-            # here, we simulate a whole-slide image, but with a single level.
-            # ! should we expose this so that use can provide their metadata ?
-            metadata = WSIMeta(
-                mpp=np.array([1.0, 1.0]),
-                axes=axes,
-                objective_power=10,
-                slide_dimensions=np.array(img.shape[:2][::-1]),
-                level_downsamples=[1.0],
-                level_dimensions=[np.array(img.shape[:2][::-1])],
-            )
-            # infer value such that read if mask provided is through
-            # 'mpp' or 'power' as varying 'baseline' is locked atm
+        self.img_path = Path(img_path)
+        self.mode = mode
+        self.reader = None
+        reader = self._get_reader(self.img_path)
+        if mode != "wsi":
             units = "mpp"
             resolution = 1.0
-            self.reader = VirtualWSIReader(
-                img,
-                info=metadata,
-            )
 
         # may decouple into misc ?
         # the scaling factor will scale base level to requested read resolution/units
-        wsi_shape = self.reader.slide_dimensions(resolution=resolution, units=units)
+        wsi_shape = reader.slide_dimensions(resolution=resolution, units=units)
 
         # use all patches, as long as it overlaps source image
         self.inputs = PatchExtractor.get_coordinates(
@@ -316,13 +293,13 @@ def __init__(  # skipcq: PY-R1000  # noqa: PLR0915
             mask = np.array(mask > 0, dtype=np.uint8)
 
             mask_reader = VirtualWSIReader(mask)
-            mask_reader.info = self.reader.info
+            mask_reader.info = reader.info
         elif auto_get_mask and mode == "wsi" and mask_path is None:
             # if no mask provided and `wsi` mode, generate basic tissue
             # mask on the fly
-            mask_reader = self.reader.tissue_mask(resolution=1.25, units="power")
+            mask_reader = reader.tissue_mask(resolution=1.25, units="power")
             # ? will this mess up  ?
-            mask_reader.info = self.reader.info
+            mask_reader.info = reader.info
 
         if mask_reader is not None:
             selected = PatchExtractor.filter_coordinates(
@@ -344,10 +321,44 @@ def __init__(  # skipcq: PY-R1000  # noqa: PLR0915
         # Perform check on the input
         self._check_input_integrity(mode="wsi")
 
+    def _get_reader(self: WSIPatchDataset, img_path: str | Path) -> WSIReader:
+        """Get a reader for the image."""
+        if self.mode == "wsi":
+            reader = WSIReader.open(img_path)
+        else:
+            logger.warning(
+                "WSIPatchDataset only reads image tile at "
+                '`units="baseline"` and `resolution=1.0`.',
+                stacklevel=2,
+            )
+            img = imread(img_path)
+            axes = "YXS"[: len(img.shape)]
+            # initialise metadata for VirtualWSIReader.
+            # here, we simulate a whole-slide image, but with a single level.
+            # ! should we expose this so that use can provide their metadata ?
+            metadata = WSIMeta(
+                mpp=np.array([1.0, 1.0]),
+                axes=axes,
+                objective_power=10,
+                slide_dimensions=np.array(img.shape[:2][::-1]),
+                level_downsamples=[1.0],
+                level_dimensions=[np.array(img.shape[:2][::-1])],
+            )
+            # infer value such that read if mask provided is through
+            # 'mpp' or 'power' as varying 'baseline' is locked atm
+            reader = VirtualWSIReader(
+                img,
+                info=metadata,
+            )
+        return reader
+
     def __getitem__(self: WSIPatchDataset, idx: int) -> dict:
         """Get an item from the dataset."""
         coords = self.inputs[idx]
         # Read image patch from the whole-slide image
+        if self.reader is None:
+            # only set the reader on first call so that it is initially picklable
+            self.reader = self._get_reader(self.img_path)
         patch = self.reader.read_bounds(
             coords,
             resolution=self.resolution,

tiatoolbox/utils/visualization.py

@@ -56,6 +56,10 @@ def random_colors(num_colors: int, *, bright: bool) -> np.ndarray:
         np.ndarray:
             Array of (r, g, b) colors.
 
+    Examples:
+        >>> from tiatoolbox.utils.visualization import random_colors
+        >>> colors = random_colors(10, bright=True)
+
     """
     brightness = 1.0 if bright else 0.7
     hsv = [(i / num_colors, 1, brightness) for i in range(num_colors)]
@@ -75,6 +79,15 @@ def colourise_image(img: np.ndarray, cmap: str = "viridis") -> np.ndarray:
 
     Returns:
         img(ndarray): An RGB image.
+
+    Examples:
+        >>> from tiatoolbox.utils.visualization import colourise_image
+        >>> import numpy as np
+        >>> # Generate a random example; replace with your own data
+        >>> img = np.random.rand(255, 255)
+        >>> # Example usage of colourise_image
+        >>> coloured_image = colourise_image(img, 'viridis')
+
     """
     if len(img.shape) == 2:  # noqa: PLR2004
         # Single channel, make into rgb with colormap.
@@ -124,6 +137,30 @@ def overlay_prediction_mask(
         If return_ax is True, return the matplotlib ax object. Else,
         return the overlay array.
 
+    Examples:
+        >>> from tiatoolbox.utils.visualization import overlay_prediction_mask
+        >>> import numpy as np
+        >>> from matplotlib import pyplot as plt
+        >>> # Generate a random example; replace with your own data
+        >>> img = np.random.randint(0, 256, size=(256, 256, 3), dtype=np.uint8)
+        >>> prediction = np.random.randint(0, 3, size=(256, 256), dtype=np.uint8)
+        >>> label_info = {
+        ...     0: ("Background", (0, 0, 0)),
+        ...     1: ("Tumor", (255, 0, 0)),
+        ...     2: ("Stroma", (0, 255, 0))
+        ... }
+        >>> # Example usage of overlay_prediction_mask
+        >>> ax = overlay_prediction_mask(
+        ...     img=img,
+        ...     prediction=prediction,
+        ...     alpha=0.5,
+        ...     label_info=label_info,
+        ...     min_val=0.0,
+        ...     ax=None,
+        ...     return_ax=True
+        ... )
+        >>> plt.show()
+
     """
     # Validate inputs
     if img.shape[:2] != prediction.shape[:2]:
@@ -310,6 +347,25 @@ def overlay_probability_map(
         If return_ax is True, return the matplotlib ax object. Else,
         return the overlay array.
 
+    Examples:
+        >>> from tiatoolbox.utils.visualization import overlay_probability_map
+        >>> import numpy as np
+        >>> from matplotlib import pyplot as plt
+        >>> # Generate a random example; replace with your own data
+        >>> img = np.random.randint(0, 256, size=(256, 256, 3), dtype=np.uint8)
+        >>> probability_map = np.random.rand(256, 256).astype(np.float32)
+        >>> # Example usage of overlay_probability_map
+        >>> ax = overlay_probability_map(
+        ...     img=img,
+        ...     prediction=probability_map,
+        ...     alpha=0.35,
+        ...     colour_map="jet",
+        ...     min_val=0.0,
+        ...     ax=None,
+        ...     return_ax=True,
+        ... )
+        >>> plt.show()
+
     """
     prediction = prediction.astype(np.float32)
     img = _validate_overlay_probability_map(img, prediction, min_val)
@@ -455,6 +511,40 @@ def overlay_prediction_contours(
         :class:`numpy.ndarray`:
             The overlaid image.
 
+    Examples:
+        >>> from tiatoolbox.utils.visualization import overlay_prediction_contours
+        >>> import numpy as np
+        >>> from matplotlib import pyplot as plt
+        >>> # Generate a random example; replace with your own data
+        >>> canvas = np.zeros((256, 256, 3), dtype=np.uint8)
+        >>> inst_dict = {
+        ...     1: {
+        ...         "type": 0,
+        ...         "contour": [[50, 50], [60, 45], [70, 50],
+        ...                     [70, 60], [60, 65], [50, 60]],
+        ...         "centroid": [60, 55]
+        ...         },
+        ...     2: {
+        ...         "type": 1,
+        ...         "contour": [[100, 100], [120, 100], [120, 120], [100, 120]],
+        ...         "centroid": [110, 110]
+        ...         }
+        ... }
+        >>> type_colours = {
+        ...     0: ("Type A", (0, 255, 0)),
+        ...     1: ("Type B", (0, 0, 255))
+        ... }
+        >>> # Example usage of overlay_prediction_contours
+        >>> overlaid_canvas = overlay_prediction_contours(
+        ...     canvas=canvas,
+        ...     inst_dict=inst_dict,
+        ...     type_colours=type_colours,
+        ...     line_thickness=1,
+        ...     draw_dot=True
+        ... )
+        >>> plt.imshow(overlaid_canvas)
+        >>> plt.show()
+
     """
     overlay = np.copy(canvas)
 
@@ -531,6 +621,28 @@ def plot_graph(
         edge_size (int):
             Line width of the edge.
 
+    Examples:
+        >>> from tiatoolbox.utils.visualization import plot_graph
+        >>> import numpy as np
+        >>> # Generate a random example; replace with your own data
+        >>> canvas = np.zeros((256, 256, 3), dtype=np.uint8)
+        >>> num_nodes = 10
+        >>> nodes = np.random.randint(0, 255, size=(num_nodes, 2))
+        >>> num_edges = 15
+        >>> edges = np.random.randint(0, num_nodes, size=(num_edges, 2))
+        >>> node_colors = np.random.randint(0, 256, size=(num_nodes, 3))
+        >>> edge_colors = np.random.randint(0, 256, size=(num_edges, 3))
+        >>> # Example usage of overlay_prediction_contours
+        >>> overlaid_canvas = plot_graph(
+        ...     canvas=canvas,
+        ...     nodes=nodes,
+        ...     edges=edges,
+        ...     node_colors=node_colors,
+        ...     node_size=8,
+        ...     edge_colors=edge_colors,
+        ...     edge_size=3
+        ... )
+
     """
     if isinstance(node_colors, tuple):
         node_colors_list = np.array([node_colors] * len(nodes))