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

eva/vision/data/transforms/normalization/rescale_intensity.py

@@ -0,0 +1,53 @@
+"""Intensity level scaling transform."""
+
+import functools
+from typing import Any, Dict, Tuple
+
+import torch
+import torchvision.transforms.v2 as torch_transforms
+from torchvision import tv_tensors
+from typing_extensions import override
+
+from eva.vision.data.transforms.normalization import functional
+
+
+class RescaleIntensity(torch_transforms.Transform):
+    """Stretches or shrinks the image intensity levels."""
+
+    def __init__(
+        self,
+        in_range: Tuple[float, float] | None = None,
+        out_range: Tuple[float, float] = (0.0, 1.0),
+    ) -> None:
+        """Initializes the transform.
+
+        Args:
+            in_range: The input data range. If `None`, it will
+                fetch the min and max of the input image.
+            out_range: The desired intensity range of the output.
+        """
+        super().__init__()
+
+        self._in_range = in_range
+        self._out_range = out_range
+
+    @functools.singledispatchmethod
+    @override
+    def _transform(self, inpt: Any, params: Dict[str, Any]) -> Any:
+        return inpt
+
+    @_transform.register(torch.Tensor)
+    def _(self, inpt: torch.Tensor, params: Dict[str, Any]) -> Any:
+        return functional.rescale_intensity(
+            inpt, in_range=self._in_range, out_range=self._out_range
+        )
+
+    @_transform.register(tv_tensors.Image)
+    def _(self, inpt: tv_tensors.Image, params: Dict[str, Any]) -> Any:
+        scaled_inpt = functional.rescale_intensity(inpt, out_range=self._out_range)
+        return tv_tensors.wrap(scaled_inpt, like=inpt)
+
+    @_transform.register(tv_tensors.BoundingBoxes)
+    @_transform.register(tv_tensors.Mask)
+    def _(self, inpt: tv_tensors.BoundingBoxes | tv_tensors.Mask, params: Dict[str, Any]) -> Any:
+        return inpt

eva/vision/data/wsi/__init__.py

@@ -0,0 +1,16 @@
+"""WSI API."""
+
+from eva.vision.data.wsi.backends import Wsi, get_cached_wsi, wsi_backend
+from eva.vision.data.wsi.patching.coordinates import PatchCoordinates, get_cached_coords
+from eva.vision.data.wsi.patching.mask import Mask, get_mask, get_mask_level
+
+__all__ = [
+    "Wsi",
+    "PatchCoordinates",
+    "Mask",
+    "get_cached_coords",
+    "wsi_backend",
+    "get_cached_wsi",
+    "get_mask",
+    "get_mask_level",
+]

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

@@ -0,0 +1,69 @@
+"""WSI Backends API."""
+
+import functools
+import importlib.util
+from typing import Callable
+
+from eva.vision.data.wsi.backends.base import Wsi
+
+LRU_CACHE_SIZE = 32
+
+
+def _is_openslide_available() -> bool:
+    """Whether the OpenSlide library is available."""
+    return importlib.util.find_spec("openslide") is not None
+
+
+def _is_tiffslide_available() -> bool:
+    """Whether the TiffSlide library is available."""
+    return importlib.util.find_spec("tiffslide") is not None
+
+
+def is_backend_available(backend: str) -> bool:
+    """Whether the specified backend is available."""
+    match backend:
+        case "openslide":
+            return _is_openslide_available()
+        case "tiffslide":
+            return _is_tiffslide_available()
+    return False
+
+
+def wsi_backend(backend: str = "openslide") -> Callable[..., Wsi]:
+    """Returns the backend to use for reading the whole-slide images."""
+    match backend:
+        case "openslide":
+            if _is_openslide_available():
+                from eva.vision.data.wsi.backends.openslide import WsiOpenslide
+
+                return WsiOpenslide
+            else:
+                raise ValueError(
+                    "Missing optional dependency: openslide.\n"
+                    "Please install using `pip install openslide-python`."
+                )
+        case "tiffslide":
+            if _is_tiffslide_available():
+                from eva.vision.data.wsi.backends.tiffslide import WsiTiffslide
+
+                return WsiTiffslide
+            else:
+                raise ValueError(
+                    "Missing optional dependency: tiffslide.\n"
+                    "Please install using `pip install tiffslide`."
+                )
+        case "pil":
+            from eva.vision.data.wsi.backends.pil import PILImage
+
+            return PILImage
+        case _:
+            raise ValueError(f"Unknown WSI backend selected: {backend}")
+
+
+@functools.lru_cache(LRU_CACHE_SIZE)
+def get_cached_wsi(file_path: str, backend: str, overwrite_mpp: float | None = None) -> Wsi:
+    """Returns a cached instance of the whole-slide image backend reader."""
+    return wsi_backend(backend)(file_path, overwrite_mpp)
+
+
+__all__ = ["Wsi", "wsi_backend", "get_cached_wsi", "_is_openslide_available"]

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

@@ -0,0 +1,115 @@
+"""Base Module for loading data from WSI files."""
+
+import abc
+from typing import Any, Sequence, Tuple
+
+import numpy as np
+
+
+class Wsi(abc.ABC):
+    """Base class for loading data from Whole Slide Image (WSI) files."""
+
+    def __init__(self, file_path: str, overwrite_mpp: float | None = None):
+        """Initializes a Wsi object.
+
+        Args:
+            file_path: The path to the WSI file.
+            overwrite_mpp: The microns per pixel (mpp) value to use when missing in WSI metadata.
+        """
+        self._wsi = self.open_file(file_path)
+        self._overwrite_mpp = overwrite_mpp
+
+    @abc.abstractmethod
+    def open_file(self, file_path: str) -> Any:
+        """Opens the WSI file.
+
+        Args:
+            file_path: The path to the WSI file.
+        """
+
+    @property
+    @abc.abstractmethod
+    def level_dimensions(self) -> Sequence[Tuple[int, int]]:
+        """A list of (width, height) tuples for each level, from highest to lowest resolution."""
+
+    @property
+    @abc.abstractmethod
+    def level_downsamples(self) -> Sequence[float]:
+        """A list of downsampling factors for each level, relative to the highest resolution."""
+
+    @property
+    @abc.abstractmethod
+    def mpp(self) -> float:
+        """Microns per pixel at the highest resolution (level 0)."""
+
+    @abc.abstractmethod
+    def _read_region(
+        self, location: Tuple[int, int], level: int, size: Tuple[int, int]
+    ) -> np.ndarray:
+        """Abstract method to read a region at a specified zoom level."""
+
+    def read_region(
+        self, location: Tuple[int, int], level: int, size: Tuple[int, int]
+    ) -> np.ndarray:
+        """Reads and returns image data for a specified region and zoom level.
+
+        Args:
+            location: Top-left corner (x, y) to start reading at level 0.
+            level: WSI level to read from.
+            size: Region size as (width, height) in pixels at the selected read level.
+                Remember to scale the size correctly.
+        """
+        self._verify_location(location, size)
+        data = self._read_region(location, level, size)
+        return self._read_postprocess(data)
+
+    def get_closest_level(self, target_mpp: float) -> int:
+        """Calculate the slide level that is closest to the target mpp.
+
+        Args:
+            slide: The whole-slide image object.
+            target_mpp: The target microns per pixel (mpp) value.
+        """
+        # Calculate the mpp for each level
+        level_mpps = self.mpp * np.array(self.level_downsamples)
+
+        # Ignore levels with higher mpp
+        level_mpps_filtered = level_mpps.copy()
+        level_mpps_filtered[level_mpps_filtered > target_mpp] = 0
+
+        if level_mpps_filtered.max() == 0:
+            # When all levels have higher mpp than target_mpp return the level with lowest mpp
+            level_idx = np.argmin(level_mpps)
+        else:
+            level_idx = np.argmax(level_mpps_filtered)
+
+        return int(level_idx)
+
+    def _verify_location(self, location: Tuple[int, int], size: Tuple[int, int]) -> None:
+        """Verifies that the requested region is within the slide dimensions.
+
+        Args:
+            location: Top-left corner (x, y) to start reading at level 0.
+            size: Region size as (width, height) in pixels at the selected read level.
+        """
+        x_max, y_max = self.level_dimensions[0]
+        x_scale = x_max / self.level_dimensions[0][0]
+        y_scale = y_max / self.level_dimensions[0][1]
+
+        if (
+            int(location[0] + x_scale * size[0]) > x_max
+            or int(location[1] + y_scale * size[1]) > y_max
+        ):
+            raise ValueError(f"Out of bounds region: {location}, {size}")
+
+    def _read_postprocess(self, data: np.ndarray) -> np.ndarray:
+        """Post-processes the read region data.
+
+        Args:
+            data: The read region data as a numpy array of shape (height, width, channels).
+        """
+        # Change color to white where the alpha channel is 0
+        if data.shape[2] == 4:
+            data[data[:, :, 3] == 0] = 255
+
+        return data[:, :, :3]

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",
+]