dippykit.metrics module¶

Module of various metrics-based functions

This module contains an assortment of functions that provide insight into image and signal data. They provide a means for high-level analysis.

dippykit.metrics.PSNR(im_1: numpy.ndarray, im_2: numpy.ndarray, max_signal_value: typing.Union[int, float] = None) → float[source]¶

Calculates the peak signal-to-noise ratio between two images in dB

Calculates the peak signal-to-noise ratio in decibels between two input images. The ratio is defined as -20 * log₁₀ (max_signal_value / X) where max_signal_value is the maximum possible value in either image and X is the mean of all elements in the ndarray (im_1 - im_2)². The two images must have the same dtype.

If max_signal_value is not specified and the two images have unsigned integer dtype, then max_signal_value is assumed to be the largest value possible in the dtype. If max_signal_value is not specified and the two images have float dtype and all their values are between 0.0 and 1.0 inclusive, then max_signal_value is assumed to be 1.0.

Parameters:	im_1 (`numpy.ndarray`) – An image to be compared. im_2 (`numpy.ndarray`) – An image to be compared. max_signal_value (`int` or `float`) – (Optional) The maximum possible signal value in either image. (This is not necessarily the maximum value of either image).
Return type:	`float`
Returns:	The decibel peak signal-to-noise ratio.

Examples:

>>> import numpy as np
>>> im = np.array([[0.5  , 0.125],
...                [0.25 , 0.   ]])
>>> im_2 = im / 2
>>> PSNR(im, im_2)
16.880806619058927
>>> im = np.array([[100,  20],
...                [ 40,   0]])
>>> im_2 = im / 2
>>> PSNR(im, im_2, 255)
19.380190974762105

dippykit.metrics.contrast(im: numpy.ndarray) → float[source]¶

Calculates the contrast value of an image

Calculates the contrast value of an image. The contrast value of the image is defined as the difference between the maximum pixel value and the minimum pixel value divided by the sum of the same values. Therefore, the return value of this function is a float between 0.0 and 1.0.

Parameters:	im (`numpy.ndarray`) – An image to be examined.
Return type:	`float`
Returns:	The contrast value of the image (float between 0.0 and 1.0).

Examples:

>>> import numpy as np
>>> im_1 = np.array([[0.5  , 0.125],
...                  [0.25 , 0.   ]])
>>> contrast(im_1)
1.0
>>> im_2 = np.array([[125, 125],
...                  [125, 125]])
>>> contrast(im_2)
0.0

dippykit.metrics.MSE(im: numpy.ndarray, im_ref: numpy.ndarray = None) → float[source]¶

Calculates the mean squared error of an image or images

For one image argument:

Calculates the mean squared error of an error image. The mean squared error is defined as the mean of all squared elements in the error image.
For two image arguments:

Calculates the mean squared error between two images. The mean squared error is defined as the mean of all squared elements in the ndarray (im - im_ref).

Parameters:	im (`numpy.ndarray`) – An image to be examined. im_ref (`numpy.ndarray`) – (Optional) A reference image for im to be compared against.
Return type:	`float`
Returns:	The mean squared error of the image(s).

Examples:

>>> import numpy as np
>>> im_1 = np.array([[0.5  , 0.125],
...                  [0.25 , 0.   ]])
>>> MSE(im_1)
0.08203125
>>> im_2 = np.array([[0.   , 0.125],
...                  [0.25 , 0.   ]])
>>> MSE(im_1, im_2)
0.0625

dippykit.metrics.energy(im: numpy.ndarray) → float[source]¶

Calculates the energy of an image

Calculates the energy of an image. The energy is defined as the sum of all squared elements in the image.

Parameters:	im (`numpy.ndarray`) – An image to be examined.
Return type:	`float`
Returns:	The energy of the image.

Examples:

>>> import numpy as np
>>> im_1 = np.array([[0.5  , 0.125],
...                  [0.25 , 0.   ]])
>>> energy(im_1)
0.328125
>>> im_2 = np.array([[125, 125],
...                  [125, 125]])
>>> energy(im_2)
62500

dippykit.metrics.MAD(im: numpy.ndarray, im_ref: numpy.ndarray = None) → float[source]¶

Calculates the mean absolute difference of an image or images

For one image argument:

Calculates the mean absolute difference of an error image. The mean absolute difference is defined as the mean of the absolute value of all elements in the error image.
For two image arguments:

Calculates the mean absolute difference between two images. The mean absolute difference is defined as the mean of the absolute value of all elements in the ndarray (im - im_ref).

Parameters:	im (`numpy.ndarray`) – An image to be examined. im_ref (`numpy.ndarray`) – (Optional) A reference image for im to be compared against.
Return type:	`float`
Returns:	The mean absolute difference of the image(s).

Examples:

>>> import numpy as np
>>> im_1 = np.array([[0.5  , 0.125],
...                  [0.25 , 0.   ]])
>>> MAD(im_1)
0.21875
>>> im_2 = np.array([[0.   , 0.125],
...                  [0.25 , 0.   ]])
>>> MAD(im_1, im_2)
0.125

dippykit.metrics.MADev(im: numpy.ndarray) → float[source]¶

Calculates the mean absolute deviation of an image

Calculates the mean absolute deviation of an image. The mean absolute deviation is defined as the mean of the absolute value of all differences between elements in the image and the mean value of all elements in the image.

Parameters:	im (`numpy.ndarray`) – An image to be examined.
Return type:	`float`
Returns:	The mean absolute deviation of the image.

Examples:

>>> import numpy as np
>>> im_1 = np.array([[15, 15],
...                  [15, 15]])
>>> MADev(im_1)
0.0
>>> im_2 = np.array([[15, 20],
...                  [10, 15]])
>>> MADev(im_2)
2.5

dippykit.metrics.entropy(im: numpy.ndarray) → float[source]¶

Calculates the entropy of an image

Calculates the entropy of an image. The entropy is equivalent to the expected value of the number of bits used to encode a single pixel in the optimal encoding case. It is a lower bound on the amount of information required to represent the image (per pixel). The entropy is defined by the sum of all pixel value probabilities times the logarithm-base-2 of the inverse pixel probability.

This function requires that the input image have either an integer or unsigned integer dtype.

Parameters:	im (`numpy.ndarray`) – An image to be examined.
Return type:	`float`
Returns:	The entropy of the image.

Examples:

>>> import numpy as np
>>> im_1 = np.array([[15, 15],
...                  [15, 15]])
>>> entropy(im_1)
-0.0
>>> im_2 = np.array([[15, 20],
...                  [10, 15]])
>>> entropy(im_2)
1.5

dippykit.metrics.SSIM(im_1: numpy.ndarray, im_2: numpy.ndarray, K1: float = 0.01, K2: float = 0.03, use_gaussian_window: bool = None, window_size: int = None, data_range: float = None, sigma: float = None, auto_downsample: bool = None, use_sample_covariance: bool = None, like_matlab: bool = False, **kwargs) → typing.Tuple[float, numpy.ndarray][source]¶

Returns the mean SSIM index and SSIM image for a comparison of two images

Given two images, this function will return the mean SSIM index and the full SSIM image.

This function is essentially a wrapper for skimage.metrics.structural_similarity, so more detailed documentation may be found there.

Parameters:	im_1 (`numpy.ndarray`) – The first image in the comparison im_2 (`numpy.ndarray`) – The second image in the comparison K1 (`float`) – (default=0.01) The K1 parameter used in the SSIM calculation K2 (`float`) – (default=0.03) The K2 parameter used in the SSIM calculation use_gaussian_window (`bool`) – (default=False) If set to True, this function will use a gaussian window for the SSIM calculation window_size (`int`) – (Optional) The size of the window to be used in the SSIM calculation. If use_gaussian_window is set to True, then this argument is ignored. data_range (`float`) – (Optional) The range of values that the image can span. If this parameter is not set, then the range will be determined from the minimum and maximum values of the images. For uint8 images, this value should be 255. sigma (`float`) – (Optional) If use_gaussian_window is set to True, this parameter determines the sigma used for the gaussian window. auto_downsample (`bool`) – (default=True) If set to True, this function will automatically downsample the inputs. The downsampling consists of finding the smallest of the images’ first two dimensions (number of rows and number of columns), dividing this value by 256, rounding the output, and setting this final value as the scaling factor (sf). A square (sf x sf) lowpass averaging filter is then applied to both images with mode ‘same’. Finally, the two images are downsampled by sf in each dimension. use_sample_covariance (`bool`) – (default=False) If set to True, this function will use sample covariances in its calculations. Otherwise, covariances of 1 will be used. like_matlab (`bool`) – If set to True, this function will act like the Matlab function ssim_index. This is merely a specific configuration of the above parameters. kwargs – For a full list of keyword arguments, see skimage.metrics.structural_similarity.
Return type:	`(float, numpy.ndarray)`
Returns:	A tuple of two elements. The first element is the mean SSIM index. The second element is the full SSIM image.

Note

This function wraps around functions from other packages. Reading these functions’ documentations may be useful. See the See also section for more information.

See also

skimage.metrics.structural_similarity: Documentation of the structural_similarity function from Scikit Image
SSIM Wikipedia Page: Wikipedia page describing the formulae for SSIM calculations

dippykit.metrics.SSIM_luminance(im_1: numpy.ndarray, im_2: numpy.ndarray, K1: float = 0.01, K2: float = 0.03, use_gaussian_window: bool = None, window_size: int = None, data_range: float = None, sigma: float = None, auto_downsample: bool = None, use_sample_covariance: bool = None, like_matlab: bool = False, **kwargs) → typing.Tuple[float, numpy.ndarray][source]¶

Returns the mean luminance component of the SSIM index and luminance component of the SSIM image for a comparison of two images

Given two images, this function will return the mean luminance component of the SSIM index and luminance component of the full SSIM image.

This function is heavily based on skimage.metrics.structural_similarity, so more detailed documentation may be found there.

Parameters:	im_1 (`numpy.ndarray`) – The first image in the comparison im_2 (`numpy.ndarray`) – The second image in the comparison K1 (`float`) – (default=0.01) The K1 parameter used in the SSIM calculation K2 (`float`) – (default=0.03) The K2 parameter used in the SSIM calculation use_gaussian_window (`bool`) – (default=False) If set to True, this function will use a gaussian window for the SSIM calculation window_size (`int`) – (Optional) The size of the window to be used in the SSIM calculation. If use_gaussian_window is set to True, then this argument is ignored. data_range (`float`) – (Optional) The range of values that the image can span. If this parameter is not set, then the range will be determined from the minimum and maximum values of the images. For uint8 images, this value should be 255. sigma (`float`) – (Optional) If use_gaussian_window is set to True, this parameter determines the sigma used for the gaussian window. auto_downsample (`bool`) – (default=True) If set to True, this function will automatically downsample the inputs. The downsampling consists of finding the smallest of the images’ first two dimensions (number of rows and number of columns), dividing this value by 256, rounding the output, and setting this final value as the scaling factor (sf). A square (sf x sf) lowpass averaging filter is then applied to both images with mode ‘same’. Finally, the two images are downsampled by sf in each dimension. use_sample_covariance (`bool`) – (default=False) If set to True, this function will use sample covariances in its calculations. Otherwise, covariances of 1 will be used. like_matlab (`bool`) – If set to True, this function will act like the Matlab function ssim_index. This is merely a specific configuration of the above parameters. kwargs – For a full list of keyword arguments, see skimage.metrics.structural_similarity.
Return type:	`(float, numpy.ndarray)`
Returns:	A tuple of two elements. The first element is the mean SSIM index. The second element is the full SSIM image.

See also

skimage.metrics.structural_similarity: Documentation of the structural_similarity function from Scikit Image
SSIM Wikipedia Page: Wikipedia page describing the formulae for SSIM calculations

dippykit.metrics.SSIM_contrast(im_1: numpy.ndarray, im_2: numpy.ndarray, K1: float = 0.01, K2: float = 0.03, use_gaussian_window: bool = None, window_size: int = None, data_range: float = None, sigma: float = None, auto_downsample: bool = None, use_sample_covariance: bool = None, like_matlab: bool = False, **kwargs) → typing.Tuple[float, numpy.ndarray][source]¶

Returns the mean contrast component of the SSIM index and contrast component of the SSIM image for a comparison of two images

Given two images, this function will return the mean contrast component of the SSIM index and contrast component of the full SSIM image.

This function is heavily based on skimage.metrics.structural_similarity, so more detailed documentation may be found there.

Parameters:	im_1 (`numpy.ndarray`) – The first image in the comparison im_2 (`numpy.ndarray`) – The second image in the comparison K1 (`float`) – (default=0.01) The K1 parameter used in the SSIM calculation K2 (`float`) – (default=0.03) The K2 parameter used in the SSIM calculation use_gaussian_window (`bool`) – (default=False) If set to True, this function will use a gaussian window for the SSIM calculation window_size (`int`) – (Optional) The size of the window to be used in the SSIM calculation. If use_gaussian_window is set to True, then this argument is ignored. data_range (`float`) – (Optional) The range of values that the image can span. If this parameter is not set, then the range will be determined from the minimum and maximum values of the images. For uint8 images, this value should be 255. sigma (`float`) – (Optional) If use_gaussian_window is set to True, this parameter determines the sigma used for the gaussian window. auto_downsample (`bool`) – (default=True) If set to True, this function will automatically downsample the inputs. The downsampling consists of finding the smallest of the images’ first two dimensions (number of rows and number of columns), dividing this value by 256, rounding the output, and setting this final value as the scaling factor (sf). A square (sf x sf) lowpass averaging filter is then applied to both images with mode ‘same’. Finally, the two images are downsampled by sf in each dimension. use_sample_covariance (`bool`) – (default=False) If set to True, this function will use sample covariances in its calculations. Otherwise, covariances of 1 will be used. like_matlab (`bool`) – If set to True, this function will act like the Matlab function ssim_index. This is merely a specific configuration of the above parameters. kwargs – For a full list of keyword arguments, see skimage.metrics.structural_similarity.
Return type:	`(float, numpy.ndarray)`
Returns:	A tuple of two elements. The first element is the mean SSIM index. The second element is the full SSIM image.

See also

skimage.metrics.structural_similarity: Documentation of the structural_similarity function from Scikit Image
SSIM Wikipedia Page: Wikipedia page describing the formulae for SSIM calculations

dippykit.metrics.SSIM_structure(im_1: numpy.ndarray, im_2: numpy.ndarray, K1: float = 0.01, K2: float = 0.03, use_gaussian_window: bool = None, window_size: int = None, data_range: float = None, sigma: float = None, auto_downsample: bool = None, use_sample_covariance: bool = None, like_matlab: bool = False, **kwargs) → typing.Tuple[float, numpy.ndarray][source]¶

Returns the mean structure component of the SSIM index and structure component of the SSIM image for a comparison of two images

Given two images, this function will return the mean structure component of the SSIM index and structure component of the full SSIM image.

This function is heavily based on skimage.metrics.structural_similarity, so more detailed documentation may be found there.

Parameters:	im_1 (`numpy.ndarray`) – The first image in the comparison im_2 (`numpy.ndarray`) – The second image in the comparison K1 (`float`) – (default=0.01) The K1 parameter used in the SSIM calculation K2 (`float`) – (default=0.03) The K2 parameter used in the SSIM calculation use_gaussian_window (`bool`) – (default=False) If set to True, this function will use a gaussian window for the SSIM calculation window_size (`int`) – (Optional) The size of the window to be used in the SSIM calculation. If use_gaussian_window is set to True, then this argument is ignored. data_range (`float`) – (Optional) The range of values that the image can span. If this parameter is not set, then the range will be determined from the minimum and maximum values of the images. For uint8 images, this value should be 255. sigma (`float`) – (Optional) If use_gaussian_window is set to True, this parameter determines the sigma used for the gaussian window. auto_downsample (`bool`) – (default=True) If set to True, this function will automatically downsample the inputs. The downsampling consists of finding the smallest of the images’ first two dimensions (number of rows and number of columns), dividing this value by 256, rounding the output, and setting this final value as the scaling factor (sf). A square (sf x sf) lowpass averaging filter is then applied to both images with mode ‘same’. Finally, the two images are downsampled by sf in each dimension. use_sample_covariance (`bool`) – (default=False) If set to True, this function will use sample covariances in its calculations. Otherwise, covariances of 1 will be used. like_matlab (`bool`) – If set to True, this function will act like the Matlab function ssim_index. This is merely a specific configuration of the above parameters. kwargs – For a full list of keyword arguments, see skimage.metrics.structural_similarity.
Return type:	`(float, numpy.ndarray)`
Returns:	A tuple of two elements. The first element is the mean SSIM index. The second element is the full SSIM image.

See also

skimage.metrics.structural_similarity: Documentation of the structural_similarity function from Scikit Image
SSIM Wikipedia Page: Wikipedia page describing the formulae for SSIM calculations