compimg package

How to use

Here is the simple example of how one can compare one image to another.

>>> import numpy as np
>>> from compimg.similarity import MSE
>>> img = np.ones((20,20), dtype = np.uint8)
>>> reference = np.ones((20,20), dtype = np.uint8)
>>> MSE().compare(img, img)
0.0

All metrics implement single interface so it is easy to use multiple of them for example you could run:

>>> import numpy as np
>>> from compimg.similarity import MSE, PSNR, SSIM
>>> for metric in [MSE(), PSNR(), SSIM()]:
...     img = np.ones((20,20), dtype = np.uint8)
...     reference = np.zeros((20,20), dtype = np.uint8)
...     value = round(metric.compare(img, reference), 2)
...     print(f"{metric.__class__.__name__} = {value}")
MSE = 1.0
PSNR = 48.13
SSIM = 0.87

compimg implicitly converts image to intermediate type (float64) to avoid overflow/underflow when doing calculation. Its advised to leave this type as is, albeit it is possible to change it. For example you could sacrafice precision to improve processing speed by changing it to float32 or even float16.

>>> import numpy as np
>>> import compimg
>>> import compimg.similarity
>>> compimg.config.intermediate_type = np.dtype(np.float32)
>>> # code that uses similarity metrics

Submodules

compimg.exceptions module

compimg exceptions module

exception compimg.exceptions.DifferentDTypesError(dtype1, dtype2)

Bases: Exception

exception compimg.exceptions.DifferentShapesError(shape1, shape2)

Bases: Exception

exception compimg.exceptions.KernelBiggerThanImageError(kernel_shape, image_shape)

Bases: Exception

exception compimg.exceptions.KernelNot2DArray(dims)

Bases: Exception

exception compimg.exceptions.KernelShapeNotOddError(kernel_shape)

Bases: Exception

exception compimg.exceptions.NegativePadAmountError(amount)

Bases: Exception

compimg.similarity module

Module with routines for computing similarity between images.

class compimg.similarity.GSSIM(k1=0.01, k2=0.03)

Bases: compimg.similarity.SimilarityMetric

Gradient-Based Structural similarity index according to the paper “GRADIENT-BASED STRUCTURAL SIMILARITY FOR IMAGE QUALITY ASSESSMENT” by Chen et al.

__abstractmethods__ = frozenset()

__init__(k1=0.01, k2=0.03)

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'compimg.similarity'

compare(image, reference)

Performs comparison.

Parameters:

• image (ndarray) – Image that is being compared.
• reference (ndarray) – Image that we compare to.

Return type:

float

Returns:

Numerical result of the comparison.

class compimg.similarity.MAE

Bases: compimg.similarity.SimilarityMetric

Mean absolute error.

__abstractmethods__ = frozenset()

__module__ = 'compimg.similarity'

compare(image, reference)

Performs comparison.

Parameters:

• image (ndarray) – Image that is being compared.
• reference (ndarray) – Image that we compare to.

Return type:

float

Returns:

Numerical result of the comparison.

class compimg.similarity.MSE

Bases: compimg.similarity.SimilarityMetric

Mean squared error.

__abstractmethods__ = frozenset()

__module__ = 'compimg.similarity'

compare(image, reference)

Performs comparison.

Parameters:

• image (ndarray) – Image that is being compared.
• reference (ndarray) – Image that we compare to.

Return type:

float

Returns:

Numerical result of the comparison.

class compimg.similarity.PSNR

Bases: compimg.similarity.SimilarityMetric

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

__abstractmethods__ = frozenset()

__module__ = 'compimg.similarity'

compare(image, reference)

Performs comparison.

Parameters:

• image (ndarray) – Image that is being compared.
• reference (ndarray) – Image that we compare to.

Return type:

float

Returns:

Numerical result of the comparison.

class compimg.similarity.RMSE

Bases: compimg.similarity.SimilarityMetric

Root mean squared error.

__abstractmethods__ = frozenset()

__module__ = 'compimg.similarity'

compare(image, reference)

Performs comparison.

Parameters:

• image (ndarray) – Image that is being compared.
• reference (ndarray) – Image that we compare to.

Return type:

float

Returns:

Numerical result of the comparison.

class compimg.similarity.SSIM(k1=0.01, k2=0.03)

Bases: compimg.similarity.SimilarityMetric

Structural similarity index according to the paper from 2004 “Image Quality Assessment: From Error Visibility to Structural Similarity” by Wang et al.

__abstractmethods__ = frozenset()

__init__(k1=0.01, k2=0.03)

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'compimg.similarity'

compare(image, reference)

Performs comparison.

Parameters:

• image (ndarray) – Image that is being compared.
• reference (ndarray) – Image that we compare to.

Return type:

float

Returns:

Numerical result of the comparison.

class compimg.similarity.SimilarityMetric

Bases: abc.ABC

Abstract class for all similarity metrics.

__abstractmethods__ = frozenset({'compare'})

__dict__ = mappingproxy({'__module__': 'compimg.similarity', '__doc__': '\n Abstract class for all similarity metrics.\n\n ', 'compare': <function SimilarityMetric.compare>, '__dict__': <attribute '__dict__' of 'SimilarityMetric' objects>, '__weakref__': <attribute '__weakref__' of 'SimilarityMetric' objects>, '__abstractmethods__': frozenset({'compare'}), '_abc_impl': <_abc_data object>})

__module__ = 'compimg.similarity'

__weakref__

list of weak references to the object (if defined)

compare(image, reference)

Performs comparison.

Parameters:

• image (ndarray) – Image that is being compared.
• reference (ndarray) – Image that we compare to.

Return type:

float

Returns:

Numerical result of the comparison.

compimg.windows module

Module with SlidingWindow interface and its implementations.

class compimg.windows.IdentitySlidingWindow(shape, stride)

Bases: compimg.windows.SlidingWindow

Slides through the image without making any changes.

slide(image)

Using some windows slides over image returning its changed/unchanged fragments.

Parameters:image (ndarray) – Image to slide over. Return type:Generator[ndarray, None, None] Returns:Generator that returns views returned by window.

class compimg.windows.SlidingWindow

Bases: abc.ABC

slide(image)

Using some windows slides over image returning its changed/unchanged fragments.

Parameters:image (ndarray) – Image to slide over. Return type:Generator[ndarray, None, None] Returns:Generator that returns views returned by window.

compimg.pads module

This module defines means to apply padding to images.

class compimg.pads.ConstantPad(value, amount)

Bases: compimg.pads.Pad

Adds rows/columns of chosen value at the edges of an image.

apply(image)

Pads given image.

Parameters:image (ndarray) – Image to pad. Return type:ndarray Returns:Padded image.

class compimg.pads.EdgePad(amount)

Bases: compimg.pads.Pad

Replicates neighbouring pixels at edges.

apply(image)

Pads given image.

Parameters:image (ndarray) – Image to pad. Return type:ndarray Returns:Padded image.

class compimg.pads.FromFunctionPad(function)

Bases: compimg.pads.Pad

apply(image)

Pads given image.

Parameters:image (ndarray) – Image to pad. Return type:ndarray Returns:Padded image.

class compimg.pads.NoPad

Bases: compimg.pads.Pad

Helper class when one has to pass Pad object but does not want apply any padding.

apply(image)

Pads given image.

Parameters:image (ndarray) – Image to pad. Return type:ndarray Returns:Padded image.

class compimg.pads.Pad

Bases: abc.ABC

When performing convolution one needs to decide what to do filter is near border(s). Instances implementing this class address that problem.

apply(image)

Pads given image.

Parameters:image (ndarray) – Image to pad. Return type:ndarray Returns:Padded image.

compimg.kernels module

Image processing using kernels. Includes several ready to be used kernels and convolution routines.

compimg.kernels.convolve(image, kernel)

Performs the convolution using provided kernel.

Attention

Result numpy.ndarray need to be processed properly before it can be used as an image again. For example one could divide its values by 255.0 and then cast its dtype to np.uint8.

Attention

In case when image has multiple channels kernel is going to be used separately for each image channel.

Parameters:

• image (ndarray) – Image on which to perform a convolution.
• kernel (ndarray) – Kernel to be used.

Return type:

ndarray

Returns:

Convolved image (probably of different dtype).

Raises:

• KernelBiggerThanImageError – When kernel does not fit into image.
• KernelShapeNotOddError – When kernel does not is of even shape.
• KernelNot2DArray – When kernel is not a 2 dimensional array.