Input Validation

Data-based

Quality (No-reference)

pymdma.image.measures.input_val.DOM

Computes DOM sharpness score for an image. It is effective in detecting motion-blur, de-focused images or inherent properties of imaging system.

Objective: Sharpness

Parameters:

Name	Type	Description	Default
width	int	Width of the edge filter.	2
sharpness_threshold	int	Threshold for considering if a pixel is sharp or not.	2
edge_threshold	float	Threshold for edge.	0.0001
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Kumar et al., Sharpness estimation for document and scene images (2012). https://ieeexplore.ieee.org/document/6460868

Code was adapted from: pydom, Sharpness Estimation for Document and Scene Images. https://github.com/umang-singhal/pydom

Examples:

>>> dom = DOM()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = dom.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/dom.py

class DOM(Metric):
    """Computes DOM sharpness score for an image. It is effective in detecting
    motion-blur, de-focused images or inherent properties of imaging system.

    **Objective**: Sharpness

    Parameters
    ----------
    width : int, optional, default=2
        Width of the edge filter.
    sharpness_threshold : int, optional, default=2
        Threshold for considering if a pixel is sharp or not.
    edge_threshold : float, optional, default=0.0001
        Threshold for edge.
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Kumar et al., Sharpness estimation for document and scene images (2012).
    https://ieeexplore.ieee.org/document/6460868

    Code was adapted from:
    pydom, Sharpness Estimation for Document and Scene Images.
    https://github.com/umang-singhal/pydom

    Examples
    --------
    >>> dom = DOM()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = dom.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = True
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        width: int = 2,
        sharpness_threshold: int = 2,
        edge_threshold: float = 0.0001,
        blur: bool = False,
        blur_size: tuple = (5, 5),
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.width = width
        self.sharpness_threshold = sharpness_threshold
        self.edge_threshold = edge_threshold
        self.blur = blur
        self.blur_size = blur_size
        if blur:
            logger.warning("Applying Gaussian Blur to the images may lead to non-deterministic results.")

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes DOM score for an image.

        Parameters
        ----------
        imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.

        Returns
        -------
        result: MetricResult
            DOM score for each image.
        """
        scores = [
            _get_sharpness(
                img,
                self.width,
                self.sharpness_threshold,
                self.edge_threshold,
                self.blur,
                self.blur_size,
            )
            for img in imgs
        ]

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": scores},
        )

pymdma.image.measures.input_val.Tenengrad

Computes Tenengrad score for an image. Sharpness measure based on the gradient magnitude.

Objective: Sharpness

Parameters:

Name	Type	Description	Default
kernel_size	int	Size of the Sobel kernel.	3
threshold	int	Threshold for valid gradient pixels. Used to supress noise, smooth the curve and impose sensitivity.	0
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Groen et al., A Comparison of Different Focus Functions for Use in Autofocus Algorithms (1984) https://onlinelibrary.wiley.com/doi/pdf/10.1002/cyto.990060202

More information on Tenengrad: Her et al., Research of Image Sharpness Assessment Algorithm for Autofocus (2019) https://ieeexplore.ieee.org/abstract/document/8980980

Examples:

>>> tenengrad = Tenengrad()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = tenengrad.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class Tenengrad(Metric):
    """Computes Tenengrad score for an image. Sharpness measure based on the
    gradient magnitude.

    **Objective**: Sharpness

    Parameters
    ----------
    kernel_size : int, optional, default=3
        Size of the Sobel kernel.
    threshold : int, optional, default=0
        Threshold for valid gradient pixels. Used to supress noise, smooth the curve and impose sensitivity.
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Groen et al., A Comparison of Different Focus Functions for Use in Autofocus Algorithms (1984)
    https://onlinelibrary.wiley.com/doi/pdf/10.1002/cyto.990060202

    More information on Tenengrad:
    Her et al., Research of Image Sharpness Assessment Algorithm for Autofocus (2019)
    https://ieeexplore.ieee.org/abstract/document/8980980

    Examples
    --------
    >>> tenengrad = Tenengrad()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = tenengrad.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        kernel_size: int = 3,
        threshold: int = 0,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.threshold = threshold
        self.ksize = kernel_size

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes Tenengrad score for a list of images.

        Parameters
        ----------
        imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.

        Returns
        -------
        result: MetricResult
            Tenengrad score for each image.
        """
        scores = []
        for img in imgs:
            if len(img.shape) == 3:
                img = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)

            gradient_x = cv2.Sobel(img, cv2.CV_64F, 1, 0, ksize=self.ksize)
            gradient_y = cv2.Sobel(img, cv2.CV_64F, 0, 1, ksize=self.ksize)

            x_y_gradients = np.sqrt(gradient_x**2 + gradient_y**2)

            x_y_gradients[x_y_gradients < self.threshold] = 0

            scores.append(np.mean(x_y_gradients))

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": scores},
        )

pymdma.image.measures.input_val.TenengradRelative

Computes Tenengrad score for an image in relation to a blurred instance of itself. Sharpness measure based on the gradient magnitude.

Objective: Sharpness

Parameters:

Name	Type	Description	Default
kernel_size	int	Size of the Sobel kernel.	3
threshold	int	Threshold for valid gradient pixels. Used to supress noise, smooth the curve and impose sensitivity.	0
criteria	str	Criteria for relative tenengrad score. Can be ratio or diff.	"ratio"
blur_factor	float	Degree of blurring to apply to the image. The lower the value, the more blurred the image. Must be in the range [0., 1.].	0.0
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Groen et al., A Comparison of Different Focus Functions for Use in Autofocus Algorithms (1984) https://onlinelibrary.wiley.com/doi/pdf/10.1002/cyto.990060202

More information on Tenengrad: Her et al., Research of Image Sharpness Assessment Algorithm for Autofocus (2019) https://ieeexplore.ieee.org/abstract/document/8980980

Examples:

>>> tenengrad = TenengradRelative()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = tenengrad.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class TenengradRelative(Metric):
    """Computes Tenengrad score for an image in relation to a blurred instance
    of itself. Sharpness measure based on the gradient magnitude.

    **Objective**: Sharpness

    Parameters
    ----------
    kernel_size : int, optional, default=3
        Size of the Sobel kernel.
    threshold : int, optional, default=0
        Threshold for valid gradient pixels. Used to supress noise, smooth the curve and impose sensitivity.
    criteria : str, optional, default="ratio"
        Criteria for relative tenengrad score. Can be `ratio` or `diff`.
    blur_factor : float, optional, default=0.0
        Degree of blurring to apply to the image. The lower the value, the more blurred the image.
        Must be in the range [0., 1.].
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Groen et al., A Comparison of Different Focus Functions for Use in Autofocus Algorithms (1984)
    https://onlinelibrary.wiley.com/doi/pdf/10.1002/cyto.990060202

    More information on Tenengrad:
    Her et al., Research of Image Sharpness Assessment Algorithm for Autofocus (2019)
    https://ieeexplore.ieee.org/abstract/document/8980980

    Examples
    --------
    >>> tenengrad = TenengradRelative()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = tenengrad.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        kernel_size: int = 3,
        threshold: int = 0,
        criteria: Literal["ratio", "diff"] = "ratio",
        blur_factor: float = 0.0,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.ksize = kernel_size
        self.trheshold = threshold
        assert criteria in ["ratio", "diff"], f"Unsupported criteria for relative tenengrad: {criteria}"
        self.criteria = criteria

        assert 0.0 <= blur_factor <= 1.0, "Blur factor must be in the range [0., 1.]"
        self.blur_factor = blur_factor

        self.tenengrad = Tenengrad(ksize=kernel_size, threshold=threshold)

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes TenengradRelative score for a list of images.

        Parameters
        ----------
        imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.

        Returns
        -------
        result: MetricResult
            Tenengrad score for each image.
        """
        relative_metrics = []
        for img in imgs:
            img_blur = np.asarray(ImageEnhance.Sharpness(Image.fromarray(img)).enhance(self.blur_factor))

            tenengrad_metric_img = self.tenengrad.compute([img]).instance_level.value[0]
            tenengrad_metric_img_blur = self.tenengrad.compute([img_blur]).instance_level.value[0]

            relative_metrics.append(
                (
                    tenengrad_metric_img_blur / tenengrad_metric_img
                    if self.criteria == "ratio"
                    else tenengrad_metric_img_blur - tenengrad_metric_img
                ),
            )

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": relative_metrics},
        )

pymdma.image.measures.input_val.EME

Computes the Measure of Enhancement (EME) score. Quantifies the enhancement of an image by measuring the contrast ratio of the image. Adapted from: https://www.researchgate.net/publication/244268659_A_New_Measure_of_Image_Enhancement

Objective: Contrast

Parameters:

Name	Type	Description	Default
blocks_size	tuple of int	Size of the blocks to divide the image into.	(100, 100)
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Agaian et al., A New Measure of Image Enhancement (2000). https://www.researchgate.net/publication/244268659_A_New_Measure_of_Image_Enhancement

Examples:

>>> eme = EME()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = eme.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class EME(Metric):
    """
    Computes the Measure of Enhancement (EME) score.
    Quantifies the enhancement of an image by measuring the contrast ratio of the image.
    Adapted from: https://www.researchgate.net/publication/244268659_A_New_Measure_of_Image_Enhancement

    **Objective**: Contrast

    Parameters
    ----------
    blocks_size : tuple of int, optional, default=(100, 100)
        Size of the blocks to divide the image into.
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Agaian et al., A New Measure of Image Enhancement (2000).
    https://www.researchgate.net/publication/244268659_A_New_Measure_of_Image_Enhancement

    Examples
    --------
    >>> eme = EME()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = eme.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        blocks_size: Tuple[int, int] = (100, 100),
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.block_size = blocks_size

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes the Measure of Enhancement (EME) score for a list of
        images.

        Parameters
        ----------
        imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.

        Returns
        -------
        result: MetricResult
            EME score for each image.
        """
        emes = []
        for img in imgs:
            if len(img.shape) == 3:
                img = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
            img_width = img.shape[0]
            img_height = img.shape[1]
            n_steps_width = int(img_width / self.block_size[0])
            n_steps_height = int(img_height / self.block_size[1])
            total_contrast_ratio = 0
            total_blocks = 0
            for w_step in range(0, n_steps_width):
                w_cords = (w_step * self.block_size[0], (w_step + 1) * self.block_size[0])
                for h_step in range(1, n_steps_height):
                    h_cords = (h_step * self.block_size[1], (h_step + 1) * self.block_size[1])
                    cur_block = img[w_cords[0] : w_cords[1], h_cords[0] : h_cords[1]]
                    if np.min(cur_block) < 0.1:
                        min_val = 0.1
                    else:
                        min_val = np.min(cur_block)
                    if np.max(cur_block) < 0.1:
                        max_val = 0.1
                    else:
                        max_val = np.max(cur_block)
                    contrast_ratio_block = 20 * np.log(max_val / min_val)
                    total_contrast_ratio += contrast_ratio_block
                    total_blocks += 1

            emes.append(total_contrast_ratio / total_blocks if total_blocks > 0 else 0)

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": emes},
        )

pymdma.image.measures.input_val.ExposureBrightness

Computes Exposure and Brightness level Metric. Values higher than 1 indicate overexposure, while values closer to 0 indicate underexposure.

Objective: Exposure and Brightness

Parameters:

Name	Type	Description	Default
**kwargs	dict	Additional keyword arguments for compatibility.	{}

Examples:

>>> exposure_brightness = ExposureBrightness()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = exposure_brightness.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class ExposureBrightness(Metric):
    """Computes Exposure and Brightness level Metric. Values higher than 1
    indicate overexposure, while values closer to 0 indicate underexposure.

    **Objective**: Exposure and Brightness

    Parameters
    ----------
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    Examples
    --------
    >>> exposure_brightness = ExposureBrightness()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = exposure_brightness.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        **kwargs,
    ):
        super().__init__(**kwargs)

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes exposure level for a list of images.

        Parameters
        ----------
        imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.

        Returns
        -------
        result: MetricResult
            Exposure score for each image.
        """
        exposure_levels = []
        for img in imgs:
            if len(img.shape) == 3:
                img = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)

            mean, std = cv2.meanStdDev(img)
            exposure_levels.append((mean[0][0] + 2 * std[0][0]) / 255)

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": exposure_levels},
        )

pymdma.image.measures.input_val.Brightness

Computes brightness level of an image.

Objective: Brightness

Parameters:

Name	Type	Description	Default
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Darel Rex Finley, HSP Color Model — Alternative to HSV (HSB) and HSL (2006). http://alienryderflex.com/hsp.html

Marian Stefanescu, Measuring and enhancing image quality attributes (2021). https://towardsdatascience.com/measuring-enhancing-image-quality-attributes-234b0f250e10

Examples:

>>> brightness = Brightness()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = brightness.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class Brightness(Metric):
    """Computes brightness level of an image.

    **Objective**: Brightness

    Parameters
    ----------
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Darel Rex Finley, HSP Color Model — Alternative to HSV (HSB) and HSL (2006).
    http://alienryderflex.com/hsp.html

    Marian Stefanescu, Measuring and enhancing image quality attributes (2021).
    https://towardsdatascience.com/measuring-enhancing-image-quality-attributes-234b0f250e10

    Examples
    --------
    >>> brightness = Brightness()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = brightness.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        **kwargs,
    ):
        super().__init__(**kwargs)

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes brightness level for a list of images.

        Parameters
        ----------
        imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.

        Returns
        -------
        result: MetricResult
            Brightness score for each image.
        """
        scores = []
        for img in imgs:
            assert img.shape[-1] == 3, "Image should be in RGB format"
            nr_of_pixels = len(img) * len(img[0])

            img = img.astype(np.float32)
            r_vals = 0.299 * img[:, :, 0] ** 2
            g_vals = 0.587 * img[:, :, 1] ** 2
            b_vals = 0.114 * img[:, :, 2] ** 2
            total_brightness = np.sqrt(r_vals + g_vals + b_vals).sum()

            scores.append(total_brightness / nr_of_pixels)

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": scores},
        )

pymdma.image.measures.input_val.Colorfulness

Computes colorfulness level of an image.

Objective: Colorfulness

Parameters:

Name	Type	Description	Default
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Hasler et al., Measuring colourfulness in natural images (2003). https://infoscience.epfl.ch/server/api/core/bitstreams/77f5adab-e825-4995-92db-c9ff4cd8bf5a/content

Code was adapted from: Adrian Rosebrock, Computing image “colorfulness” with OpenCV and Python (2017). https://pyimagesearch.com/2017/06/05/computing-image-colorfulness-with-opencv-and-python/

Examples:

>>> colorfulness = Colorfulness()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = colorfulness.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class Colorfulness(Metric):
    """Computes colorfulness level of an image.

    **Objective**: Colorfulness

    Parameters
    ----------
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Hasler et al., Measuring colourfulness in natural images (2003).
    https://infoscience.epfl.ch/server/api/core/bitstreams/77f5adab-e825-4995-92db-c9ff4cd8bf5a/content

    Code was adapted from:
    Adrian Rosebrock, Computing image “colorfulness” with OpenCV and Python (2017).
    https://pyimagesearch.com/2017/06/05/computing-image-colorfulness-with-opencv-and-python/

    Examples
    --------
    >>> colorfulness = Colorfulness()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = colorfulness.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        **kwargs,
    ):
        super().__init__(**kwargs)

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes colorfulness level of list of images.

        Parameters
        ----------
        imgs : (N, H, W, C) ndarray
            List of arrays representing RGB image of shape (H, W, C).

        Returns
        -------
        result: MetricResult
            Colorfulness score for each image.
        """
        scores = []
        for img in imgs:
            assert len(img.shape) == 3, "Image should be in RGB format"

            img = img.astype(np.float32)
            (r_channel, g_channel, b_channel) = img[:, :, 0], img[:, :, 1], img[:, :, 2]

            rg = np.absolute(r_channel - g_channel)
            yb = np.absolute(0.5 * (r_channel + g_channel) - b_channel)

            (rb_mean, rb_std) = (np.mean(rg), np.std(rg))
            (yb_mean, yb_std) = (np.mean(yb), np.std(yb))

            std_root = np.sqrt((rb_std**2) + (yb_std**2))
            mean_root = np.sqrt((rb_mean**2) + (yb_mean**2))

            scores.append(std_root + (0.3 * mean_root))
        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": scores},
        )

pymdma.image.measures.input_val.CLIPIQA

Compute the CLIP-based IQA score. Wrapper of the PIQ CLIP-IQA metric. Evaluates perceptual quality of an image using a CLIP model.

Objective: General Image Quality

Parameters:

Name	Type	Description	Default
img_size	tuple of int, int	Size for each image. If a single integer is provided, the image will be thumbnail resized. In thumbnail resizing, the aspect ratio is maintained and batch calculation is not allowed (slower computation).	tuple of int
interpolation	int	Interpolation method for resizing.	cv2.INTER_LINEAR
data_range	float	The range of the data. By default, it is assumed to be [0, 255].	255
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Wang et al., Exploring CLIP for Assessing the Look and Feel of Images (2022). https://arxiv.org/abs/2207.12396

This is a wrapper class for the implementation in: piq, PyTorch Image Quality: Metrics for Image Quality Assessment. https://github.com/photosynthesis-team/piq

Examples:

>>> clip_iqa = CLIPIQA()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = clip_iqa.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class CLIPIQA(Metric):
    """Compute the CLIP-based IQA score. Wrapper of the PIQ CLIP-IQA metric.
    Evaluates perceptual quality of an image using a CLIP model.

    **Objective**: General Image Quality

    Parameters
    ----------
    img_size : {tuple of int, int}, optional, default=(512, 512)
        Size for each image. If a single integer is provided, the image will be thumbnail resized.
        In thumbnail resizing, the aspect ratio is maintained and batch calculation is not allowed (slower computation).
    interpolation : int, optional, default=cv2.INTER_LINEAR
        Interpolation method for resizing.
    data_range : float, optional, default=255
        The range of the data. By default, it is assumed to be [0, 255].
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Wang et al., Exploring CLIP for Assessing the Look and Feel of Images (2022).
    https://arxiv.org/abs/2207.12396

    This is a wrapper class for the implementation in:
    piq, PyTorch Image Quality: Metrics for Image Quality Assessment.
    https://github.com/photosynthesis-team/piq

    Examples
    --------
    >>> clip_iqa = CLIPIQA()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = clip_iqa.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        img_size: Union[Tuple[int, int], int] = (512, 512),
        interpolation: int = cv2.INTER_LINEAR,
        data_range: float = 255,
        device: str = "cpu",
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.img_size = img_size
        self.interpolation = interpolation
        self._clip = _clip_iqa(data_range=data_range).to(device)
        self.device = device

        if isinstance(img_size, tuple):
            self._height, self._width = img_size, img_size
            self._batch_calculation = True
        else:
            # thumbnail resize (different image sizes)
            self._height, self._width = img_size, None
            self._batch_calculation = False

        self._height, self._width = img_size if isinstance(img_size, tuple) else (img_size, None)

    def _process_image(self, img: np.ndarray) -> np.ndarray:
        """Resize image to the required size and convert to tensor."""
        img = image_resize(img, height=self._height, width=self._width, inter=self.interpolation)
        return torch.tensor(img).permute(2, 0, 1)

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes CLIPIQA level of a list of images.

        Parameters
        ----------
        imgs : (N, H, W, C) ndarray
            List of arrays representing RGB image of shape (H, W, C).

        Returns
        -------
        result: MetricResult
            CLIPIQA score for each image.
        """
        imgs = [self._process_image(img) for img in imgs]

        if self._batch_calculation:
            imgs = torch.stack(imgs).to(self.device)
            scores = self._clip(imgs).detach().cpu().squeeze(1).tolist()
        else:
            scores = [self._clip(img.unsqueeze(0)).detach().cpu().item() for img in imgs]

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": scores},
        )

pymdma.image.measures.input_val.BRISQUE

Computes Blind/referenceless Image Spatial Quality Evaluator (BRISQUE) score. Wrapper of the PIQ BRISQUE metric implementation.

Objective: General Image Quality

Parameters:

Name	Type	Description	Default
kernel_size	int	The size of the Gaussian kernel.	7
kernel_sigma	float	The standard deviation of the Gaussian kernel.	7 / 6
data_range	float	The range of the data. By default, it is assumed to be [0, 255].	255
device	str	Device to run the computation.	"cpu"
same_size	bool	If True, all provided images must have the same size (faster computation).	False
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

Mittal et al., No-Reference Image Quality Assessment in the Spatial Domain (2012). https://live.ece.utexas.edu/publications/2012/TIP%20BRISQUE.pdf

This is a wrapper class for the implementation in: piq, PyTorch Image Quality: Metrics for Image Quality Assessment. https://github.com/photosynthesis-team/piq

Examples:

>>> brisque = BRISQUE()
>>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
>>> result: MetricResult = brisque.compute(imgs)

Source code in src/pymdma/image/measures/input_val/data/no_reference.py

class BRISQUE(Metric):
    """Computes  Blind/referenceless Image Spatial Quality Evaluator (BRISQUE)
    score. Wrapper of the PIQ BRISQUE metric implementation.

    **Objective**: General Image Quality

    Parameters
    ----------
    kernel_size : int, optional, default=7
        The size of the Gaussian kernel.
    kernel_sigma : float, optional, default=7 / 6
        The standard deviation of the Gaussian kernel.
    data_range : float, optional, default=255
        The range of the data. By default, it is assumed to be [0, 255].
    device : str, optional, default="cpu"
        Device to run the computation.
    same_size : bool, optional, default=False
        If True, all provided images must have the same size (faster computation).
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    Mittal et al., No-Reference Image Quality Assessment in the Spatial Domain (2012).
    https://live.ece.utexas.edu/publications/2012/TIP%20BRISQUE.pdf

    This is a wrapper class for the implementation in:
    piq, PyTorch Image Quality: Metrics for Image Quality Assessment.
    https://github.com/photosynthesis-team/piq

    Examples
    --------
    >>> brisque = BRISQUE()
    >>> imgs = np.random.rand(20, 100, 100, 3) # (N, H, W, C)
    >>> result: MetricResult = brisque.compute(imgs)
    """

    reference_type = ReferenceType.NONE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = False
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        kernel_size: int = 7,
        kernel_sigma: float = 7 / 6,
        data_range: float = 255,
        device: str = "cpu",
        same_size: bool = False,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.kernel_size = kernel_size
        self.kernel_sigma = kernel_sigma
        self.data_range = data_range
        self._brisque = brisque
        self._batch_calculation = same_size
        self.device = device

    def _process_image(self, img: np.ndarray) -> np.ndarray:
        """Resize image to the required size and convert to tensor."""
        return torch.tensor(img).permute(2, 0, 1)

    def compute(
        self,
        imgs: np.ndarray,
        **kwargs,
    ) -> MetricResult:
        """Computes BRISQUE.

        Parameters
        ----------
        imgs : (N, H, W, C) ndarray
            List of arrays representing RGB image of shape (H, W, C).

        Returns
        -------
        result: MetricResult
            BRISQUE score for each image.
        """
        imgs = [self._process_image(img) for img in imgs]

        if self._batch_calculation:
            imgs = torch.stack(imgs).to(self.device)
            scores = (
                self._brisque(
                    imgs,
                    kernel_size=self.kernel_size,
                    kernel_sigma=self.kernel_sigma,
                    data_range=self.data_range,
                    reduction="none",
                )
                .detach()
                .cpu()
                .tolist()
            )
        else:
            scores = [
                self._brisque(
                    img.unsqueeze(0),
                    kernel_size=self.kernel_size,
                    kernel_sigma=self.kernel_sigma,
                    data_range=self.data_range,
                    reduction="none",
                )
                .detach()
                .cpu()
                .item()
                for img in imgs
            ]

        return DistributionResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": scores},
        )

---

Quality (Full-reference)

pymdma.image.measures.input_val.PSNR

Computes Peak Signal to Noise Ratio (PSNR) between two images.

Objective: Signal-to-noise ratio

Parameters:

Name	Type	Description	Default
data_range	int	Maximum value of the image data (e.g., 255 for 8-bit images).	255
convert_to_grayscale	bool	Whether to convert the images to grayscale before computing PSNR.	False
allow_nan	bool	Whether to allow NaN values in the returned scores.	False
**kwargs	dict	Additional keyword arguments for compatibility (unsused).	{}

References

wikipedia.org: Peak signal-to-noise ratio https://en.wikipedia.org/wiki/Peak_signal-to-noise_ratio

Examples:

>>> psnr = PSNR()
>>> reference_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
>>> target_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
>>> result: MetricResult = psnr.compute(reference_imgs, target_imgs)

Source code in src/pymdma/image/measures/input_val/data/psnr.py

class PSNR(Metric):
    """Computes Peak Signal to Noise Ratio (PSNR) between two images.

    **Objective**: Signal-to-noise ratio

    Parameters
    ----------
    data_range : int, optional, default=255
        Maximum value of the image data (e.g., 255 for 8-bit images).
    convert_to_grayscale : bool, optional, default=False
        Whether to convert the images to grayscale before computing PSNR.
    allow_nan : bool, optional, default=False
        Whether to allow NaN values in the returned scores.
    **kwargs : dict, optional
        Additional keyword arguments for compatibility (unsused).

    References
    ----------
    wikipedia.org: Peak signal-to-noise ratio
    https://en.wikipedia.org/wiki/Peak_signal-to-noise_ratio

    Examples
    --------
    >>> psnr = PSNR()
    >>> reference_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
    >>> target_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
    >>> result: MetricResult = psnr.compute(reference_imgs, target_imgs)
    """

    reference_type = ReferenceType.INSTANCE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = True
    min_value: float = 0.0
    max_value: float = np.inf

    def __init__(
        self,
        data_range: int = 255,
        convert_to_grayscale: bool = False,
        allow_nan: bool = False,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.data_range = data_range
        self.convert_to_grayscale = convert_to_grayscale
        self.allow_nan = allow_nan
        self._eps = 1e-8 if not allow_nan else 0

    def compute(
        self,
        reference_imgs: Sequence[np.ndarray],
        target_imgs: Sequence[np.ndarray],
        **kwargs,
    ) -> MetricResult:
        """Computes PSNR score between two image sets.

        Parameters
        ----------
        reference_imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            Images to use as reference.
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.
        target_imgs : {(N, H, W, C) ndarray, (N, H, W) ndarray}
            Corresponding images to compare with reference.
            List of arrays representing RGB or grayscale image of shape (H, W, C) or (H, W), respectively.

        Returns
        -------
        result : MetricResult
            Instance-level PSNR scores.
            May contain warnings if PSNR is infinite.
        """
        assert len(reference_imgs) == len(target_imgs), "Reference and target images must have the same length"
        assert all(
            ref.shape == targ.shape for ref, targ in zip(reference_imgs, target_imgs)
        ), "Reference and target images must have the same shape"

        # convert images to YIQ and extract luminance
        if self.convert_to_grayscale:
            reference_imgs = [np.sum(ref @ _yiq_from_rgb, axis=-1) for ref in reference_imgs]
            target_imgs = [np.sum(targ @ _yiq_from_rgb, axis=-1) for targ in target_imgs]

        mses = np.array(
            [
                np.mean((ref.astype(np.float32) - targ.astype(np.float32)) ** 2)
                for ref, targ in zip(reference_imgs, target_imgs)
            ],
        )
        psnrs = 20 * np.log10(self.data_range / (np.sqrt(mses) + self._eps))

        warnings = set()
        if np.isinf(psnrs).any():
            warnings.add("Infinite PSNR value. Check if reference image is the same as the target image.")
            logger.warning("Infinite PSNR value. Check if reference image is the same as the target image.")

        return MetricResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": psnrs.tolist()},
            errors=list(warnings) if len(warnings) > 0 else None,
        )

pymdma.image.measures.input_val.SSIM

Computes the Structural Similarity Index (SSIM) between two images. Wrapper of the PIQ SSIMLoss implementation.

Objective: Similarity

Parameters:

Name	Type	Description	Default
kernel_size	int	The side-length of the sliding window used in comparison. Must be an odd value.	11
sigma	float	Sigma of normal distribution.	1.5
k1	float (default: 0.01)	Algorithm parameter, K1 (small constant).	0.01
k2	float (default: 0.03)	Algorithm parameter, K2 (small constant).	0.03
downsample	bool (default: False)	Whether to downsample the images to speed up the computation.	False
data_range	int	Maximum value of the image data (e.g., 255 for 8-bit images).	255
channel_last_dim	bool (default: True)	Indicates if the input images have the color channel as the last dimension. Needed for compatibility with torch operations.	True
device	str	Device to use for computation.	'cpu'
**kwargs	dict	Additional keyword arguments for compatibility (unsused).	{}

References

This class is a wrapper of the implementation from: piq, PyTorch Image Quality: Metrics and Measure for Image Quality Assessment, https://github.com/photosynthesis-team/piq

Examples:

>>> ssim = SSIM()
>>> reference_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
>>> target_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
>>> result: MetricResult = ssim.compute(reference_imgs, target_imgs)

Source code in src/pymdma/image/measures/input_val/data/ssim.py

class SSIM(Metric):
    """Computes the Structural Similarity Index (SSIM) between two images.
    Wrapper of the PIQ SSIMLoss implementation.

    **Objective**: Similarity

    Parameters
    ----------
    kernel_size : int
        The side-length of the sliding window used in comparison. Must be an odd value.
    sigma : float
        Sigma of normal distribution.
    k1 : float (default: 0.01)
        Algorithm parameter, K1 (small constant).
    k2 : float (default: 0.03)
        Algorithm parameter, K2 (small constant).
    downsample : bool (default: False)
        Whether to downsample the images to speed up the computation.
    data_range : int
        Maximum value of the image data (e.g., 255 for 8-bit images).
    channel_last_dim : bool (default: True)
        Indicates if the input images have the color channel as the last dimension.
        Needed for compatibility with torch operations.
    device : str
        Device to use for computation.
    **kwargs : dict, optional
        Additional keyword arguments for compatibility (unsused).

    References
    ----------
    This class is a wrapper of the implementation from:
    piq, PyTorch Image Quality: Metrics and Measure for Image Quality Assessment,
    https://github.com/photosynthesis-team/piq

    Examples
    --------
    >>> ssim = SSIM()
    >>> reference_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
    >>> target_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
    >>> result: MetricResult = ssim.compute(reference_imgs, target_imgs)
    """

    reference_type = ReferenceType.INSTANCE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = True
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        kernel_size: int = 11,
        sigma: float = 1.5,
        k1: float = 0.01,
        k2: float = 0.03,
        downsample: bool = False,
        data_range: int = 255,
        channel_last_dim: bool = True,
        device: str = "cpu",
        **kwargs,
    ):
        super().__init__(**kwargs)
        self._ssim = SSIMLoss(
            kernel_size=kernel_size,
            kernel_sigma=sigma,
            k1=k1,
            k2=k2,
            downsample=downsample,
            data_range=data_range,
            reduction="none",
        ).to(device)
        self.channel_last_dim = channel_last_dim
        self.device = device

    def compute(
        self,
        reference_imgs: Sequence[Union[np.ndarray, Tensor]],
        target_imgs: Sequence[Union[np.ndarray, Tensor]],
        **kwargs,
    ) -> MetricResult:
        """Computes SSIM score.

        Parameters
        ----------
        reference_imgs : (N, H, W, C) ndarray or tensor
            Images to use as reference.
            List of arrays representing a RGB image of shape (H, W, C).
            For (C, H, W) images, set channel_last_dim to False.
        target_imgs : (N, H, W, C) ndarray or tensor
            Corresponding images to compare with reference.
            List of arrays representing a RGB image of shape (H, W, C).
            For (C, H, W) images, set channel_last_dim to False.

        Returns
        -------
        result : MetricResult
            Instance-level SSIM scores.
        """
        reference_imgs, target_imgs = _validate_inputs(reference_imgs, target_imgs, self.channel_last_dim)

        # do batch calculation on all images (if same shape)
        _batch_calculation = len({ref.shape for ref in reference_imgs}) == 1
        if _batch_calculation:
            reference_imgs = torch.stack(reference_imgs).to(self.device)
            target_imgs = torch.stack(target_imgs).to(self.device)
            ssims = self._ssim(reference_imgs, target_imgs).detach().cpu()
            ssims = (1 - ssims).tolist()
        else:
            ssims = []
            for ref, targ in zip(reference_imgs, target_imgs):
                ssims.append(1 - self._ssim(ref.unsqueeze(0).to(self.device), targ.unsqueeze(0).to(self.device)).item())

        return MetricResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": ssims},
        )

pymdma.image.measures.input_val.MSSSIM

Computes the Multiscale Structural Similarity Index (MSSSIM) between two images. Wrapper of the PIQ MultiScaleSSIMLoss implementation.

Objective: Similarity

Parameters:

Name	Type	Description	Default
kernel_size	int	The side-length of the sliding window used in comparison. Must be an odd value.	11
sigma	float	Sigma of normal distribution.	1.5
k1	float (default: 0.01)	Algorithm parameter, K1 (small constant).	0.01
k2	float (default: 0.03)	Algorithm parameter, K2 (small constant).	0.03
scale_weights	list	Weights for different scales.	None
data_range	int	Maximum value of the image data (e.g., 255 for 8-bit images).	255
channel_last_dim	bool (default: True)	Indicates if the input images have the color channel as the last dimension. Needed for compatibility with torch operations.	True
device	str	Device to use for computation.	'cpu'
**kwargs	dict	Additional keyword arguments for compatibility.	{}

References

This class is a wrapper of the implementation from: piq, PyTorch Image Quality: Metrics and Measure for Image Quality Assessment, https://github.com/photosynthesis-team/piq

Examples:

>>> mssim = MSSIM()
>>> reference_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
>>> target_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
>>> result: MetricResult = mssim.compute(reference_imgs, target_imgs)

Source code in src/pymdma/image/measures/input_val/data/ssim.py

class MSSSIM(Metric):
    """Computes the Multiscale Structural Similarity Index (MSSSIM) between two
    images. Wrapper of the PIQ MultiScaleSSIMLoss implementation.

    **Objective**: Similarity

    Parameters
    ----------
    kernel_size : int
        The side-length of the sliding window used in comparison. Must be an odd value.
    sigma : float
        Sigma of normal distribution.
    k1 : float (default: 0.01)
        Algorithm parameter, K1 (small constant).
    k2 : float (default: 0.03)
        Algorithm parameter, K2 (small constant).
    scale_weights : list, optional
        Weights for different scales.
    data_range : int
        Maximum value of the image data (e.g., 255 for 8-bit images).
    channel_last_dim : bool (default: True)
        Indicates if the input images have the color channel as the last dimension.
        Needed for compatibility with torch operations.
    device : str
        Device to use for computation.
    **kwargs : dict, optional
        Additional keyword arguments for compatibility.

    References
    ----------
    This class is a wrapper of the implementation from:
    piq, PyTorch Image Quality: Metrics and Measure for Image Quality Assessment,
    https://github.com/photosynthesis-team/piq

    Examples
    --------
    >>> mssim = MSSIM()
    >>> reference_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
    >>> target_imgs = np.random.rand(20, 256, 256, 3) # (N, H, W, C)
    >>> result: MetricResult = mssim.compute(reference_imgs, target_imgs)
    """

    reference_type = ReferenceType.INSTANCE
    evaluation_level = EvaluationLevel.INSTANCE
    metric_group = MetricGroup.QUALITY

    higher_is_better: bool = True
    min_value: float = 0.0
    max_value: float = 1.0

    def __init__(
        self,
        kernel_size: int = 11,
        sigma: float = 1.5,
        k1: float = 0.01,
        k2: float = 0.03,
        scale_weights: Optional[Sequence[float]] = None,
        data_range: int = 255,
        channel_last_dim: bool = True,
        device: str = "cpu",
        **kwargs,
    ):
        super().__init__(**kwargs)

        if scale_weights is not None:
            scale_weights = torch.tensor(scale_weights)

        self._mssim = MultiScaleSSIMLoss(
            kernel_size=kernel_size,
            kernel_sigma=sigma,
            k1=k1,
            k2=k2,
            scale_weights=scale_weights,
            data_range=data_range,
            reduction="none",
        ).to(device)
        self.channel_last_dim = channel_last_dim
        self.device = device

    def compute(
        self,
        reference_imgs: Sequence[Union[np.ndarray, Tensor]],
        target_imgs: Sequence[Union[np.ndarray, Tensor]],
        **kwargs,
    ) -> MetricResult:
        """Computes MSSIM score.

        Parameters
        ----------
        reference_imgs : (N, H, W, C) ndarray
            Images to use as reference.
            List of arrays representing a RGB image of shape (H, W, C).
            For (C, H, W) images, set channel_last_dim to False.
        target_imgs : (N, H, W, C) ndarray
            Corresponding images to compare with reference.
            List of arrays representing a RGB image of shape (H, W, C).
            For (C, H, W) images, set channel_last_dim to False.

        Returns
        -------
        result : MetricResult
            Instance-level MSSIM scores.
        """
        reference_imgs, target_imgs = _validate_inputs(reference_imgs, target_imgs, self.channel_last_dim)

        _batch_calculation = len({ref.shape for ref in reference_imgs}) == 1
        if _batch_calculation:
            reference_imgs = torch.stack(reference_imgs).to(self.device)
            target_imgs = torch.stack(target_imgs).to(self.device)
            mssims = self._mssim(reference_imgs, target_imgs).detach().cpu()
            mssims = (1 - mssims).tolist()
        else:
            mssims = []
            for ref, targ in zip(reference_imgs, target_imgs):
                mssims.append(
                    1 - self._mssim(ref.unsqueeze(0).to(self.device), targ.unsqueeze(0).to(self.device)).item(),
                )

        return MetricResult(
            instance_level={"dtype": OutputsTypes.ARRAY, "subtype": "float", "value": mssims},
        )