Welcome to compimg’s documentation!¶

compimg¶

PyPI PyPI - Python Version PyPI - Wheel License Documentation Status

Branches:master: CircleCIdevelop: CircleCI

Introduction¶

For full documentation visit documentation site.

Image similarity metrics are often used in image quality assessment for performance evaluation of image restoration and reconstruction algorithms. They require two images:

test image (image of interest)
reference image (image we compare against)

Such metrics produce numerical values.

Such methods are are widely called full/reduced-reference methods for assessing image quality.

compimg package is all about calculating similarity between images. It provides image similarity metrics (PSNR, SSIM etc.) that are widely used to asses image quality.

import numpy as np
from compimg.similarity import SSIM
some_grayscale_image = np.ones((20,20), dtype=np.uint8)
identical_image = np.ones((20,20), dtype=np.uint8)
result = SSIM().compare(some_grayscale_image, identical_image)
assert result == 1.0

Features¶

common metrics for calculating similarity of one image to another
images are treated as numpy arrays which makes compimg compatible with most image processing packages
only scipy (and inherently numpy) as a dependency

Installation¶

compimg is available on PyPI. You can install it using pip:pip install compimg

Note¶

Keep in mind that metrics are not aware of what kind of image you are passing. If metric relies on intensity values and you have YCbCr image you should pass only the first channel to the computing routine.

Help¶

If you have any problems or questions please post an issue.

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: numpy.dtype, dtype2: numpy.dtype)[source]¶: Bases: Exception

exception compimg.exceptions.DifferentShapesError(shape1: Sequence[int], shape2: Sequence[int])[source]¶: Bases: Exception

exception compimg.exceptions.KernelBiggerThanImageError(kernel_shape: Sequence[int], image_shape: Sequence[int])[source]¶: Bases: Exception

exception compimg.exceptions.KernelNot2DArray(dims: int)[source]¶: Bases: Exception

exception compimg.exceptions.KernelShapeNotOddError(kernel_shape: Sequence[int])[source]¶: Bases: Exception

exception compimg.exceptions.NegativePadAmountError(amount)[source]¶: Bases: Exception

compimg.similarity module¶

compimg.windows module¶

Module with SlidingWindow interface and its implementations.

class compimg.windows.IdentitySlidingWindow(shape: Tuple[int, int], stride: Tuple[int, int])[source]¶

Bases: compimg.windows.SlidingWindow

Slides through the image without making any changes.

slide(image: numpy.ndarray) → Generator[numpy.ndarray, None, None][source]¶

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

Parameters:	image – Image to slide over.
Returns:	Generator that returns views returned by window.

class compimg.windows.SlidingWindow[source]¶

Bases: abc.ABC

slide(image: numpy.ndarray) → Generator[numpy.ndarray, None, None][source]¶

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

Parameters:	image – Image to slide over.
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: numbers.Number, amount: int)[source]¶

Bases: compimg.pads.Pad

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