kaiko-eva 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

eva/vision/data/wsi/backends/openslide.py

@@ -0,0 +1,73 @@
+"""Module for loading data from WSI files using the OpenSlide library."""
+
+from typing import Sequence, Tuple
+
+import numpy as np
+import openslide
+from typing_extensions import override
+
+from eva.vision.data.wsi.backends import base
+
+
+class WsiOpenslide(base.Wsi):
+    """Class for loading data from WSI files using the OpenSlide library."""
+
+    _wsi: openslide.OpenSlide
+
+    @override
+    def open_file(self, file_path: str) -> openslide.OpenSlide:
+        return openslide.OpenSlide(file_path)
+
+    @property
+    @override
+    def level_dimensions(self) -> Sequence[Tuple[int, int]]:
+        return self._wsi.level_dimensions
+
+    @property
+    @override
+    def level_downsamples(self) -> Sequence[float]:
+        return self._wsi.level_downsamples
+
+    @property
+    @override
+    def mpp(self) -> float:
+        # TODO: add overwrite_mpp class attribute to allow setting a default value
+        if self._wsi.properties.get(openslide.PROPERTY_NAME_MPP_X) and self._wsi.properties.get(
+            openslide.PROPERTY_NAME_MPP_Y
+        ):
+            x_mpp = float(self._wsi.properties[openslide.PROPERTY_NAME_MPP_X])
+            y_mpp = float(self._wsi.properties[openslide.PROPERTY_NAME_MPP_Y])
+        elif (
+            self._wsi.properties.get("tiff.XResolution")
+            and self._wsi.properties.get("tiff.YResolution")
+            and self._wsi.properties.get("tiff.ResolutionUnit")
+        ):
+            unit = self._wsi.properties.get("tiff.ResolutionUnit")
+            if unit not in _conversion_factor_to_micrometer:
+                raise ValueError(f"Unit {unit} not supported.")
+
+            conversion_factor = float(_conversion_factor_to_micrometer.get(unit))  # type: ignore
+            x_mpp = conversion_factor / float(self._wsi.properties["tiff.XResolution"])
+            y_mpp = conversion_factor / float(self._wsi.properties["tiff.YResolution"])
+        else:
+            raise ValueError("`mpp` cannot be obtained for this slide.")
+
+        return (x_mpp + y_mpp) / 2.0
+
+    @override
+    def _read_region(
+        self, location: Tuple[int, int], level: int, size: Tuple[int, int]
+    ) -> np.ndarray:
+        return np.array(self._wsi.read_region(location, level, size))
+
+
+_conversion_factor_to_micrometer = {
+    "meter": 10**6,
+    "decimeter": 10**5,
+    "centimeter": 10**4,
+    "millimeter": 10**3,
+    "micrometer": 1,
+    "nanometer": 10**-3,
+    "picometer": 10**-6,
+    "femtometer": 10**-9,
+}

eva/vision/data/wsi/backends/pil.py

@@ -0,0 +1,52 @@
+"""Module for loading data from standard image file formats PIL library."""
+
+from typing import Sequence, Tuple
+
+import numpy as np
+import PIL.Image
+from typing_extensions import override
+
+from eva.vision.data.wsi.backends import base
+
+
+class PILImage(base.Wsi):
+    """Class for loading data from standard image file formats using PIL library."""
+
+    _wsi: PIL.Image.Image
+
+    @override
+    def open_file(self, file_path: str) -> PIL.Image.Image:
+        return PIL.Image.open(file_path).convert("RGB")
+
+    @property
+    @override
+    def level_dimensions(self) -> Sequence[Tuple[int, int]]:
+        return [self._wsi.size]
+
+    @property
+    @override
+    def level_downsamples(self) -> Sequence[float]:
+        return [1.0]
+
+    @property
+    @override
+    def mpp(self) -> float:
+        if self._overwrite_mpp is None:
+            raise ValueError("Please specify the mpp using the `overwrite_mpp` argument.")
+        return self._overwrite_mpp
+
+    @override
+    def _read_region(
+        self, location: Tuple[int, int], level: int, size: Tuple[int, int]
+    ) -> np.ndarray:
+        width, height = size[0], size[1]
+        patch = self._wsi.crop(
+            # (left, upper, right, lower)
+            (
+                location[0],
+                location[1],
+                location[0] + width,
+                location[1] + height,
+            )
+        )
+        return np.array(patch)

eva/vision/data/wsi/backends/tiffslide.py

@@ -0,0 +1,42 @@
+"""Module for loading data from WSI files using the OpenSlide library."""
+
+from typing import Sequence, Tuple
+
+import numpy as np
+import tiffslide  # type: ignore
+from typing_extensions import override
+
+from eva.vision.data.wsi.backends import base
+
+
+class WsiTiffslide(base.Wsi):
+    """Class for loading data from WSI files using the TiffSlide library."""
+
+    _wsi: tiffslide.TiffSlide
+
+    @override
+    def open_file(self, file_path: str) -> tiffslide.TiffSlide:
+        return tiffslide.TiffSlide(file_path)
+
+    @property
+    @override
+    def level_dimensions(self) -> Sequence[Tuple[int, int]]:
+        return self._wsi.level_dimensions
+
+    @property
+    @override
+    def level_downsamples(self) -> Sequence[float]:
+        return self._wsi.level_downsamples
+
+    @property
+    @override
+    def mpp(self) -> float:
+        x_mpp = float(self._wsi.properties[tiffslide.PROPERTY_NAME_MPP_X])
+        y_mpp = float(self._wsi.properties[tiffslide.PROPERTY_NAME_MPP_Y])
+        return (x_mpp + y_mpp) / 2.0
+
+    @override
+    def _read_region(
+        self, location: Tuple[int, int], level: int, size: Tuple[int, int]
+    ) -> np.ndarray:
+        return np.array(self._wsi.read_region(location, level, size))

eva/vision/data/wsi/patching/__init__.py

@@ -0,0 +1,6 @@
+"""WSI Patching API."""
+
+from eva.vision.data.wsi.patching import samplers
+from eva.vision.data.wsi.patching.coordinates import PatchCoordinates
+
+__all__ = ["samplers", "PatchCoordinates"]

eva/vision/data/wsi/patching/coordinates.py

@@ -0,0 +1,98 @@
+"""A module for handling coordinates of patches from a whole-slide image."""
+
+import dataclasses
+import functools
+from typing import List, Tuple
+
+from eva.vision.data.wsi import backends
+from eva.vision.data.wsi.patching import samplers
+from eva.vision.data.wsi.patching.mask import Mask, get_mask, get_mask_level
+
+LRU_CACHE_SIZE = 32
+
+
+@dataclasses.dataclass
+class PatchCoordinates:
+    """A class to store coordinates of patches from a whole-slide image.
+
+    Args:
+        x_y: A list of (x, y) coordinates of the patches (refer to level 0).
+        width: The width of the patches, in pixels (refers to level_idx).
+        height: The height of the patches, in pixels (refers to level_idx).
+        level_idx: The level index at which to extract the patches.
+        mask: The foreground mask of the wsi.
+    """
+
+    x_y: List[Tuple[int, int]]
+    width: int
+    height: int
+    level_idx: int
+    mask: Mask | None = None
+
+    @classmethod
+    def from_file(
+        cls,
+        wsi_path: str,
+        width: int,
+        height: int,
+        sampler: samplers.Sampler,
+        target_mpp: float,
+        overwrite_mpp: float | None = None,
+        backend: str = "openslide",
+    ) -> "PatchCoordinates":
+        """Create a new instance of PatchCoordinates from a whole-slide image file.
+
+        Patches will be read from the level that is closest to the specified target_mpp.
+
+        Args:
+            wsi_path: The path to the whole-slide image file.
+            width: The width of the patches to be extracted, in pixels.
+            height: The height of the patches to be extracted, in pixels.
+            target_mpp: The target microns per pixel (mpp) for the patches.
+            overwrite_mpp: The microns per pixel (mpp) value to use when missing in WSI metadata.
+            sampler: The sampler to use for sampling patch coordinates.
+            backend: The backend to use for reading the whole-slide images.
+        """
+        wsi = backends.wsi_backend(backend)(wsi_path, overwrite_mpp)
+
+        # Sample patch coordinates at level 0
+        mpp_ratio_0 = target_mpp / wsi.mpp
+        sample_args = {
+            "width": int(mpp_ratio_0 * width),
+            "height": int(mpp_ratio_0 * height),
+            "layer_shape": wsi.level_dimensions[0],
+        }
+        if isinstance(sampler, samplers.ForegroundSampler):
+            mask_level_idx = get_mask_level(wsi, width, height, target_mpp)
+            sample_args["mask"] = get_mask(wsi, mask_level_idx)
+
+        x_y = list(sampler.sample(**sample_args))
+
+        # Scale dimensions to level that is closest to the target_mpp
+        level_idx = wsi.get_closest_level(target_mpp)
+        mpp_ratio = target_mpp / (wsi.mpp * wsi.level_downsamples[level_idx])
+        scaled_width, scaled_height = int(mpp_ratio * width), int(mpp_ratio * height)
+
+        return cls(x_y, scaled_width, scaled_height, level_idx, sample_args.get("mask"))
+
+
+@functools.lru_cache(LRU_CACHE_SIZE)
+def get_cached_coords(
+    file_path: str,
+    width: int,
+    height: int,
+    target_mpp: float,
+    overwrite_mpp: float | None,
+    sampler: samplers.Sampler,
+    backend: str,
+) -> PatchCoordinates:
+    """Get a cached instance of PatchCoordinates for the specified parameters."""
+    return PatchCoordinates.from_file(
+        wsi_path=file_path,
+        width=width,
+        height=height,
+        target_mpp=target_mpp,
+        overwrite_mpp=overwrite_mpp,
+        backend=backend,
+        sampler=sampler,
+    )

eva/vision/data/wsi/patching/mask.py

@@ -0,0 +1,123 @@
+"""Functions for extracting foreground masks."""
+
+import dataclasses
+from typing import Tuple
+
+import cv2
+import numpy as np
+
+from eva.vision.data.wsi.backends.base import Wsi
+
+
+@dataclasses.dataclass
+class Mask:
+    """A class to store the mask of a whole-slide image."""
+
+    mask_array: np.ndarray
+    """Binary mask array where 1s represent the foreground and 0s represent the background."""
+
+    mask_level_idx: int
+    """WSI level index at which the mask_array was extracted."""
+
+    scale_factors: Tuple[float, float]
+    """Factors to scale x/y coordinates from mask_level_idx to level 0."""
+
+
+def get_mask(
+    wsi: Wsi,
+    mask_level_idx: int,
+    saturation_threshold: int = 20,
+    median_blur_kernel_size: int | None = None,
+    fill_holes: bool = False,
+    holes_kernel_size: Tuple[int, int] = (7, 7),
+    use_otsu: bool = False,
+) -> Mask:
+    """Generates a binary foreground mask for a given WSI.
+
+    The is a simplified version of the algorithm proposed in [1] (CLAM):
+    1. Convert the image to the HSV color space (easier to seperate specific colors with RGB).
+    2. (optional) Apply a median blur to the saturation channel to reduce noise
+        & closing small gaps in the mask. While this yields cleaner masks, this step is the most
+        computationally expensive and thus disabled by default (CLAM uses a value of 7).
+    3. Calculate binary mask by thresholding accross the saturation channel.
+
+    [1] Lu, Ming Y., et al. "Data-efficient and weakly supervised computational
+        pathology on whole-slide images." Nature biomedical engineering 5.6 (2021): 555-570.
+        https://github.com/mahmoodlab/CLAM
+
+    Args:
+        wsi: The WSI object.
+        mask_level_idx: The level index of the WSI at which we want to extract the mask.
+        saturation_threshold: The threshold value for the saturation channel.
+        median_blur_kernel_size: Kernel size for the median blur operation.
+        holes_kernel_size: The size of the kernel for morphological operations to fill holes.
+        fill_holes: Whether to fill holes in the mask.
+        use_otsu: Whether to use Otsu's method for the thresholding operation. If False,
+            a fixed threshold value is used.
+
+    Returns: A Mask object instance.
+    """
+    image = wsi.read_region((0, 0), mask_level_idx, wsi.level_dimensions[mask_level_idx])
+    image = cv2.cvtColor(image, cv2.COLOR_RGB2HSV)
+    image = (
+        cv2.medianBlur(image[:, :, 1], median_blur_kernel_size)
+        if median_blur_kernel_size
+        else image[:, :, 1]
+    )
+
+    threshold_type = cv2.THRESH_BINARY + cv2.THRESH_OTSU if use_otsu else cv2.THRESH_BINARY
+    _, mask_array = cv2.threshold(image, saturation_threshold, 1, threshold_type)
+
+    if fill_holes:
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, holes_kernel_size)
+        mask_array = cv2.dilate(mask_array, kernel, iterations=1)
+        contour, _ = cv2.findContours(mask_array, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_SIMPLE)
+        for cnt in contour:
+            cv2.drawContours(mask_array, [cnt], 0, (1,), -1)
+
+    mask_array = mask_array.astype(np.uint8)
+    scale_factors = (
+        wsi.level_dimensions[0][0] / wsi.level_dimensions[mask_level_idx][0],
+        wsi.level_dimensions[0][1] / wsi.level_dimensions[mask_level_idx][1],
+    )
+
+    return Mask(mask_array=mask_array, mask_level_idx=mask_level_idx, scale_factors=scale_factors)
+
+
+def get_mask_level(
+    wsi: Wsi,
+    width: int,
+    height: int,
+    target_mpp: float,
+    min_mask_patch_pixels: int = 3 * 3,
+) -> int:
+    """For performance reasons, we generate the mask at the lowest resolution level possible.
+
+    However, if minimum resolution level has too few pixels, the patches scaled to that level will
+    be too small or even collapse to a single pixel. This function allows to find the lowest
+    resolution level that yields mask patches with at least `min_mask_patch_pixels` pixels.
+
+    Args:
+        wsi: The WSI object.
+        width: The width of the patches to be extracted, in pixels (at target_mpp).
+        height: The height of the patches to be extracted, in pixels.
+        target_mpp: The target microns per pixel (mpp) for the patches.
+        min_mask_patch_pixels: The minimum number of pixels required for the mask patches.
+            Mask patch refers to width / height at target_mpp scaled down to the WSI level
+            at which the mask is generated.
+    """
+    level_mpps = wsi.mpp * np.array(wsi.level_downsamples)
+    mask_level_idx = None
+
+    for level_idx, level_mpp in reversed(list(enumerate(level_mpps))):
+        mpp_ratio = target_mpp / level_mpp
+        scaled_width, scaled_height = int(mpp_ratio * width), int(mpp_ratio * height)
+
+        if scaled_width * scaled_height >= min_mask_patch_pixels:
+            mask_level_idx = level_idx
+            break
+
+    if mask_level_idx is None:
+        raise ValueError("No level with the specified minimum number of patch pixels available.")
+
+    return mask_level_idx

eva/vision/data/wsi/patching/samplers/__init__.py

@@ -0,0 +1,14 @@
+"""Patch Sampler API."""
+
+from eva.vision.data.wsi.patching.samplers.base import ForegroundSampler, Sampler
+from eva.vision.data.wsi.patching.samplers.foreground_grid import ForegroundGridSampler
+from eva.vision.data.wsi.patching.samplers.grid import GridSampler
+from eva.vision.data.wsi.patching.samplers.random import RandomSampler
+
+__all__ = [
+    "ForegroundSampler",
+    "Sampler",
+    "ForegroundGridSampler",
+    "GridSampler",
+    "RandomSampler",
+]

eva/vision/data/wsi/patching/samplers/_utils.py

@@ -0,0 +1,50 @@
+import random
+from typing import Tuple
+
+import numpy as np
+
+
+def set_seed(seed: int) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+
+
+def get_grid_coords_and_indices(
+    layer_shape: Tuple[int, int],
+    width: int,
+    height: int,
+    overlap: Tuple[int, int],
+    shuffle: bool = True,
+    seed: int = 42,
+):
+    """Get grid coordinates and indices.
+
+    Args:
+        layer_shape: The shape of the layer.
+        width: The width of the patches.
+        height: The height of the patches.
+        overlap: The overlap between patches in the grid.
+        shuffle: Whether to shuffle the indices.
+        seed: The random seed.
+    """
+    x_range = range(0, layer_shape[0] - width + 1, width - overlap[0])
+    y_range = range(0, layer_shape[1] - height + 1, height - overlap[1])
+    x_y = [(x, y) for x in x_range for y in y_range]
+
+    indices = list(range(len(x_y)))
+    if shuffle:
+        set_seed(seed)
+        np.random.shuffle(indices)
+    return x_y, indices
+
+
+def validate_dimensions(width: int, height: int, layer_shape: Tuple[int, int]) -> None:
+    """Checks if the width / height is bigger than the layer shape.
+
+    Args:
+        width: The width of the patches.
+        height: The height of the patches.
+        layer_shape: The shape of the layer.
+    """
+    if width > layer_shape[0] or height > layer_shape[1]:
+        raise ValueError("The width / height cannot be bigger than the layer shape.")

eva/vision/data/wsi/patching/samplers/base.py

@@ -0,0 +1,48 @@
+"""Base classes for samplers."""
+
+import abc
+from typing import Generator, Tuple
+
+from eva.vision.data.wsi.patching.mask import Mask
+
+
+class Sampler(abc.ABC):
+    """Base class for samplers."""
+
+    @abc.abstractmethod
+    def sample(
+        self,
+        width: int,
+        height: int,
+        layer_shape: Tuple[int, int],
+        mask: Mask | None = None,
+    ) -> Generator[Tuple[int, int], None, None]:
+        """Sample patche coordinates.
+
+        Args:
+            width: The width of the patches.
+            height: The height of the patches.
+            layer_shape: The shape of the layer.
+            mask: Tuple containing the mask array and the scaling factor with respect to the
+                provided layer_shape. Optional, only required for samplers with foreground
+                filtering.
+
+        Returns:
+            A generator producing sampled patch coordinates.
+        """
+
+
+class ForegroundSampler(Sampler):
+    """Base class for samplers with foreground filtering capabilities."""
+
+    @abc.abstractmethod
+    def is_foreground(
+        self,
+        mask: Mask,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        min_foreground_ratio: float,
+    ) -> bool:
+        """Check if a patch contains sufficient foreground."""

eva/vision/data/wsi/patching/samplers/foreground_grid.py

@@ -0,0 +1,99 @@
+"""Foreground grid sampler."""
+
+from typing import Tuple
+
+from eva.vision.data.wsi.patching.mask import Mask
+from eva.vision.data.wsi.patching.samplers import _utils, base
+
+
+class ForegroundGridSampler(base.ForegroundSampler):
+    """Sample patches based on a grid, only returning patches containing foreground."""
+
+    def __init__(
+        self,
+        max_samples: int = 20,
+        overlap: Tuple[int, int] = (0, 0),
+        min_foreground_ratio: float = 0.35,
+        seed: int = 42,
+    ) -> None:
+        """Initializes the sampler.
+
+        Args:
+            max_samples: The maximum number of samples to return.
+            overlap: The overlap between patches in the grid.
+            min_foreground_ratio: The minimum amount of foreground
+                within a sampled patch.
+            seed: The random seed.
+        """
+        self.max_samples = max_samples
+        self.overlap = overlap
+        self.min_foreground_ratio = min_foreground_ratio
+        self.seed = seed
+
+    def sample(
+        self,
+        width: int,
+        height: int,
+        layer_shape: Tuple[int, int],
+        mask: Mask,
+    ):
+        """Sample patches from a grid containing foreground.
+
+        Args:
+            width: The width of the patches.
+            height: The height of the patches.
+            layer_shape: The shape of the layer.
+            mask: The mask of the image.
+        """
+        _utils.validate_dimensions(width, height, layer_shape)
+        x_y, indices = _utils.get_grid_coords_and_indices(
+            layer_shape, width, height, self.overlap, seed=self.seed
+        )
+
+        count = 0
+        for i in indices:
+            if count >= self.max_samples:
+                break
+
+            if self.is_foreground(
+                mask=mask,
+                x=x_y[i][0],
+                y=x_y[i][1],
+                width=width,
+                height=height,
+                min_foreground_ratio=self.min_foreground_ratio,
+            ):
+                count += 1
+                yield x_y[i]
+
+    def is_foreground(
+        self,
+        mask: Mask,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        min_foreground_ratio: float,
+    ) -> bool:
+        """Check if a patch contains sufficient foreground.
+
+        Args:
+            mask: The mask of the image.
+            x: The x-coordinate of the patch.
+            y: The y-coordinate of the patch.
+            width: The width of the patch.
+            height: The height of the patch.
+            min_foreground_ratio: The minimum amount of foreground in the patch.
+        """
+        x_, y_ = self._scale_coords(x, y, mask.scale_factors)
+        width_, height_ = self._scale_coords(width, height, mask.scale_factors)
+        patch_mask = mask.mask_array[y_ : y_ + height_, x_ : x_ + width_]
+        return patch_mask.sum() / patch_mask.size >= min_foreground_ratio
+
+    def _scale_coords(
+        self,
+        x: int,
+        y: int,
+        scale_factors: Tuple[float, float],
+    ) -> Tuple[int, int]:
+        return int(x / scale_factors[0]), int(y / scale_factors[1])

eva/vision/data/wsi/patching/samplers/grid.py

@@ -0,0 +1,47 @@
+"""Grid sampler."""
+
+from typing import Generator, Tuple
+
+from eva.vision.data.wsi.patching.samplers import _utils, base
+
+
+class GridSampler(base.Sampler):
+    """Sample patches based on a grid.
+
+    Args:
+        max_samples: The maximum number of samples to return.
+        overlap: The overlap between patches in the grid.
+        seed: The random seed.
+    """
+
+    def __init__(
+        self,
+        max_samples: int | None = None,
+        overlap: Tuple[int, int] = (0, 0),
+        seed: int = 42,
+    ):
+        """Initializes the sampler."""
+        self.max_samples = max_samples
+        self.overlap = overlap
+        self.seed = seed
+
+    def sample(
+        self,
+        width: int,
+        height: int,
+        layer_shape: Tuple[int, int],
+    ) -> Generator[Tuple[int, int], None, None]:
+        """Sample patches from a grid.
+
+        Args:
+            width: The width of the patches.
+            height: The height of the patches.
+            layer_shape: The shape of the layer.
+        """
+        _utils.validate_dimensions(width, height, layer_shape)
+        x_y, indices = _utils.get_grid_coords_and_indices(
+            layer_shape, width, height, self.overlap, seed=self.seed
+        )
+        max_samples = len(indices) if self.max_samples is None else self.max_samples
+        for i in indices[:max_samples]:
+            yield x_y[i]