microssim 0.0.1__py3-none-any.whl

microssim/__init__.py

@@ -0,0 +1,11 @@
+"""MicroSSIM and MicroMS3IM metrics to compare images."""
+
+from .micro_ms3im import MicroMS3IM, micro_multiscale_structural_similarity
+from .micro_ssim import MicroSSIM, micro_structural_similarity
+
+__all__ = [
+    "MicroSSIM",
+    "micro_structural_similarity",
+    "MicroMS3IM",
+    "micro_multiscale_structural_similarity",
+]

microssim/conftest.py

@@ -0,0 +1,39 @@
+"""File used to discover python modules and run doctest.
+
+See https://sybil.readthedocs.io/en/latest/use.html#pytest
+"""
+
+from pathlib import Path
+
+import pytest
+from pytest import TempPathFactory
+from sybil import Sybil
+from sybil.parsers.codeblock import PythonCodeBlockParser
+from sybil.parsers.doctest import DocTestParser
+
+
+@pytest.fixture(scope="module")
+def my_path(tmpdir_factory: TempPathFactory) -> Path:
+    """Fixture used in doctest to create a temporary directory.
+
+    Parameters
+    ----------
+    tmpdir_factory : TempPathFactory
+        Temporary path factory from pytest.
+
+    Returns
+    -------
+    Path
+        Temporary directory path.
+    """
+    return tmpdir_factory.mktemp("my_path")
+
+
+pytest_collect_file = Sybil(
+    parsers=[
+        DocTestParser(),
+        PythonCodeBlockParser(future_imports=["print_function"]),
+    ],
+    pattern="*.py",
+    fixtures=["my_path"],
+).pytest()

microssim/image_processing/__init__.py

@@ -0,0 +1,13 @@
+"""Image processing utilities."""
+
+__all__ = [
+    "get_background",
+    "remove_background",
+    "linearize_list",
+    "normalize_min_max",
+    "compute_norm_parameters",
+]
+
+from .background import get_background, remove_background
+from .linearize import linearize_list
+from .micro_ssim_normalization import compute_norm_parameters, normalize_min_max

microssim/image_processing/background.py

@@ -0,0 +1,52 @@
+"""Background calculation and removal functions."""
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def get_background(x: NDArray, percentage: float = 3) -> float:
+    """
+    Compute the value of the background based on the percentile.
+
+    This method simply run `np.percentile` on the input image.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        The input image.
+    percentage : float, default=3
+        Percentage for the percentile.
+
+    Returns
+    -------
+    float
+        The value of the background.
+    """
+    return np.percentile(x, percentage, keepdims=True)
+
+
+def remove_background(
+    x: NDArray, percentage: float = 3, dtype: type = np.float32
+) -> NDArray:
+    """
+    Remove the background from an image.
+
+    Parameters
+    ----------
+    x : NDArray
+        The input image.
+    percentage : float, default=3
+        Percentage for the percentile.
+    dtype : type, default=np.float32
+        Data type for the output image.
+
+    Returns
+    -------
+    NDArray
+        The image with the background removed.
+    """
+
+    # get percentile
+    perc_val = get_background(x, percentage).astype(dtype, copy=False)
+
+    return x.astype(dtype, copy=False) - perc_val

microssim/image_processing/care_normalization.py

@@ -0,0 +1,124 @@
+"""Normalization as done in the CSBDEEP library and CARE approach.
+
+Code adapted from https://github.com/CSBDeep/CSBDeep under BSD-3-Clause license.
+"""
+
+from typing import Optional
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def normalize_care(
+    x: NDArray,
+    pmin: float = 3,
+    pmax: float = 99.8,
+    axis: Optional[int] = None,
+    eps: float = 1e-20,
+    dtype: type = np.float32,
+) -> NDArray:
+    """
+    Normalize input image using min and max percentiles.
+
+    This approach was used in the CARE method.
+
+    Parameters
+    ----------
+    x : NDArray
+        Input image.
+    pmin : float, default=3
+        Lower percentile.
+    pmax : float, default=99.8
+        Upper percentile.
+    axis : int or None, default=None
+        Axis or axes along which to compute the percentiles. The default `None` is to
+        compute the percentile(s) over a flattened version of the array.
+    eps : float, default=1e-20
+        Small value to avoid division by zero.
+    dtype : type, default=np.float32
+        Data type of the output.
+
+    Returns
+    -------
+    NDArray
+        Normalized image.
+    """
+    # Compute percentiles
+    mi = np.percentile(x, pmin, axis=axis, keepdims=True)
+    ma = np.percentile(x, pmax, axis=axis, keepdims=True)
+
+    return normalize_min_max(x, mi, ma, eps=eps, dtype=dtype)
+
+
+def normalize_min_max(
+    x: NDArray,
+    min_val: float,
+    max_val: float,
+    eps: float = 1e-20,
+    dtype: type = np.float32,
+) -> NDArray:
+    """
+    Normalize input image using absolute min and max values.
+
+    This approach was used in the CARE method.
+
+    Parameters
+    ----------
+    x : NDArray
+        Input image.
+    min_val : float
+        Lower value.
+    max_val : float
+        Upper value.
+    eps : float, default=1e-20
+        Small value to avoid division by zero.
+    dtype : type, default=np.float32
+        Data type of the output.
+
+    Returns
+    -------
+    NDArray
+        Normalized image.
+    """
+    # change types
+    x = x.astype(dtype, copy=False)
+    min_val = (
+        dtype(min_val) if np.isscalar(min_val) else min_val.astype(dtype, copy=False)
+    )
+    max_val = (
+        dtype(max_val) if np.isscalar(max_val) else max_val.astype(dtype, copy=False)
+    )
+    eps = dtype(eps)
+
+    return (x - min_val) / (max_val - min_val + eps)
+
+
+def normalize_min_mse(x: NDArray, target: NDArray) -> NDArray:
+    """
+    Normalize input image to a target image using minimum mean square error.
+
+    This method performs an affine rescaling of x, such that the mean squared error to
+    target is minimal.
+
+    Parameters
+    ----------
+    x : NDArray
+        Input image.
+    target : NDArray
+        Target image.
+
+    Returns
+    -------
+    NDArray
+        Normalized input image.
+    """
+    # compute covariance
+    cov = np.cov(x.flatten(), target.flatten())
+
+    # scaling factor
+    alpha = cov[0, 1] / (cov[0, 0] + 1e-10)
+
+    # offset
+    beta = target.mean() - alpha * x.mean()
+
+    return alpha * x + beta

microssim/image_processing/linearize.py

@@ -0,0 +1,21 @@
+"""Linearize list of images."""
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def linearize_list(images: list[NDArray]) -> NDArray:
+    """
+    Linearize and concatenate a list of images, avoiding copying the arrays.
+
+    Parameters
+    ----------
+    images : list of numpy.ndarray
+        Input images.
+
+    Returns
+    -------
+    np.ndarray
+        Lineatized and concatenated images.
+    """
+    return np.concatenate([np.ravel(x) for x in images])

microssim/image_processing/micro_ssim_normalization.py

@@ -0,0 +1,84 @@
+"""MicroSSIM normalization functions."""
+
+from typing import Optional, Union
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+# TODO add tests
+def normalize_min_max(
+    images: Union[list[NDArray], NDArray], min_val: float, max_val: float
+) -> Union[list[NDArray], NDArray]:
+    """
+    Normalize the images using provided minimum and maximum values.
+
+    Parameters
+    ----------
+    images : numpy.ndarray or list of numpy.ndarray
+        Image or list of images to normalize.
+    min_val : float
+        Minimum value used in normalization.
+    max_val : float
+        Maximum value used in normalization.
+
+    Returns
+    -------
+    numpy.ndarray or list of numpy.ndarray
+        Normalized image or list of normalized images.
+    """
+    if isinstance(images, list):
+        return [normalize_min_max(x, min_val, max_val) for x in images]
+
+    return (images - min_val) / max_val
+
+
+def compute_norm_parameters(
+    gt: NDArray,
+    pred: NDArray,
+    bg_percentile: float = 3.0,
+    offset_gt: Optional[float] = None,
+    offset_pred: Optional[float] = None,
+    max_val: Optional[float] = None,
+) -> tuple[float, float, float]:
+    """
+    Compute the parameters used to normalize the images for MicroSSIM.
+
+    If the offsets are provided, they are simply returned. Otherwise, they are
+    estimated from the images using the background percentile value.
+
+    If the maximum value is provided, it is simply returned. Otherwise, it is
+    estimated from the ground truth image by checking the maximum value after
+    background subtraction.
+
+    Parameters
+    ----------
+    gt : NDArray
+        Reference image.
+    pred : NDArray
+        Image being compared to the reference.
+    bg_percentile : float, default=3
+        Percentile of the image considered as background.
+    offset_gt : float or None, default=None
+        Estimate of background pixel intensity in the reference image.
+    offset_pred : float or None, default=None
+        Estimate of background pixel intensity in the second image.
+    max_val : float or None, default=None
+        Maximum value used in normalization.
+
+    Returns
+    -------
+    (float, float, float)
+        A tuple containing the ground-truth offset, the prediction offset and the
+        maximum value.
+    """
+    if offset_gt is None:
+        offset_gt = np.percentile(gt, bg_percentile, keepdims=False)
+
+    if offset_pred is None:
+        offset_pred = np.percentile(pred, bg_percentile, keepdims=False)
+
+    if max_val is None:
+        max_val = (gt - offset_gt).max()
+
+    return offset_gt, offset_pred, max_val

microssim/micro_ms3im.py

@@ -0,0 +1,200 @@
+"""MicroMS3IM metrics."""
+
+import warnings
+from typing import Optional, Union
+
+import torch
+from numpy.typing import NDArray
+from torch import Tensor
+from torchmetrics.image import MultiScaleStructuralSimilarityIndexMeasure
+
+from microssim.image_processing import normalize_min_max
+from microssim.micro_ssim import MicroSSIM
+
+# TODO implement it in numpy?
+# TODO return types are torch.Tensor
+
+
+def micro_multiscale_structural_similarity(
+    gt: Union[NDArray, list[NDArray]],
+    pred: Union[NDArray, list[NDArray]],
+    *,
+    bg_percentile: int = 3,
+    offset_gt: Optional[float] = None,
+    offset_pred: Optional[float] = None,
+    max_val: Optional[float] = None,
+    ri_factor: Optional[float] = None,
+) -> Union[float, list[float]]:
+    """
+    Compute the mean MicroMS3IM metric between two images.
+
+    MicroSSIM computes a scaled version of the multiscale structural similarity index
+    (MS3IM), in which images are first normalized using an offset and maximum value. A
+    range-invariant factor is then estimated by maximizing a scaled MS3IM metrics
+    between the normalized images.
+
+    If the offsets are not provided, they are estimated from the images using the
+    background percentile value.
+
+    If the maximum value is not provided, it is estimated from the ground truth image
+    by checking the maximum value after background subtraction.
+
+    If the range-invariant factor is not provided, it is estimated from the normalized
+    images.
+
+    Parameters
+    ----------
+    gt : numpy.ndarray or list of numpy.ndarray
+        Reference image.
+    pred : numpy.ndarray or list of numpy.ndarray
+        Image being compared to the reference.
+    bg_percentile : int, default=3
+        Percentile of the image considered as background.
+    offset_gt : float or None, default=None
+        Estimate of background pixel intensity in the reference image.
+    offset_pred : float or None, default=None
+        Estimate of background pixel intensity in the second image.
+    max_val : float or None, default=None
+        Maximum value used in normalization.
+    ri_factor : float or None, default=None
+        Range-invariant factor.
+
+    Returns
+    -------
+    float or list of float
+        Mean MicroSSIM metric between the images, either as a list if the input are
+        lists or array with more than 2 dimensions.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from microssim import micro_multiscale_structural_similarity
+    >>> rng = np.random.default_rng(42)
+    >>> gt = 150 + rng.integers(0, data_range, (100, 100))
+    >>> pred = rng.poisson(gt) / 10. - 100
+    >>> micro_multiscale_structural_similarity(gt, pred)
+    """
+    # generate parameters for the metrics computation
+    micro_ssim = MicroMS3IM(
+        bg_percentile=bg_percentile,
+        offset_gt=offset_gt,
+        offset_pred=offset_pred,
+        max_val=max_val,
+        ri_factor=ri_factor,
+    )
+    micro_ssim.fit(gt, pred)
+
+    # compute the MicroMS3IM metric
+    if isinstance(gt, list) or gt.ndim > 2:
+        return [
+            micro_ssim.score(
+                gt_i,
+                pred_i,
+            )
+            for gt_i, pred_i in zip(gt, pred)
+        ]
+    else:
+        return micro_ssim.score(
+            gt,
+            pred,
+        )
+
+
+class MicroMS3IM(MicroSSIM):
+    """
+    A class computing the MicroMS3IM metric between images.
+
+    In addition to computing the metrics, this class allows to inspect the parameters
+    estimated along the way, such as the offsets, the max value and the range-invariant
+    factor.
+
+    Attributes
+    ----------
+    _bg_percentile : int
+        Percentile of the image considered as background.
+    _offset_pred : float
+        Estimate of background pixel intensity in the prediction image.
+    _offset_gt : float
+        Estimate of background pixel intensity in the ground truth image.
+    _max_val : float
+        Maximum value used in normalization.
+    _ri_factor : float
+        MicroSSIM scaling factor.
+    _initialized : bool
+        Whether the class has been initialized and can compute scores between images.
+    """
+
+    def score(
+        self,
+        gt: NDArray,
+        pred: NDArray,
+        return_individual_components: bool = False,
+        **ms_ssim_kwargs,
+    ) -> float:
+        """Compute the metrics between two arrays.
+
+        Parameters
+        ----------
+        gt : numpy.ndarray
+            Reference array.
+        pred : NDArray
+            Array to be compared to the reference array.
+        return_individual_components : bool, default=False
+            Unused argument.
+        **ms_ssim_kwargs : dict
+            Additional keyword arguments to be passed to the
+            `torchmetrics.image.MultiScaleStructuralSimilarityIndexMeasure` class.
+
+        Returns
+        -------
+        float or ScaledSSIM
+            MicroSSIM metric between the arrays.
+
+        Raises
+        ------
+        ValueError
+            If the `fit` method has not been called before calling this method.
+        ValueError
+            If the groundtruth and prediction arrays have different shapes.
+        ValueError
+            If the arrays are not 2D.
+        """
+        if return_individual_components:
+            warnings.warn(
+                "The `return_individual_components` argument is not supported for "
+                "the MS-SSIM metric. Ignoring it."
+            )
+
+        if not self._initialized:
+            raise ValueError(
+                "MicroSSIM was not initialized, call the `fit` method first. It is "
+                "advised to run the `fit` method on entire datasets rather than on "
+                "pairs of images."
+            )
+
+        if gt.shape != pred.shape:
+            raise ValueError("Groundtruth and prediction must have the same shape.")
+
+        if gt.ndim != 2:
+            raise ValueError("Only 2D images are supported.")
+
+        if ms_ssim_kwargs is None:
+            ms_ssim_kwargs = {}
+
+        # normalize the images
+        gt_norm = normalize_min_max(gt, self._offset_gt, self._max_val)
+        pred_norm = normalize_min_max(pred, self._offset_pred, self._max_val)
+
+        # convert to torch tensors
+        gt_torch = torch.Tensor(gt_norm[None, None])
+        pred_torch = torch.Tensor(pred_norm[None, None])
+
+        # rescale
+        pred_torch = pred_torch * self._ri_factor
+
+        # compute the MS-SSIM
+        ms_ssim = MultiScaleStructuralSimilarityIndexMeasure(
+            data_range=gt_norm.max() - gt_norm.min(), **ms_ssim_kwargs
+        )
+
+        return ms_ssim(pred_torch, gt_torch)