piqa.gmsd#

Gradient Magnitude Similarity Deviation (GMSD) and Multi-Scale Gradient Magnitude Similarity Deviation (MS-GMSD)

This module implements the GMSD and MS-GMSD in PyTorch.

Original

https://www4.comp.polyu.edu.hk/~cslzhang/IQA/GMSD/GMSD.htm

References

Gradient Magnitude Similarity Deviation: An Highly Efficient Perceptual Image Quality Index (Xue et al., 2013)
https://arxiv.org/abs/1308.3052
Gradient Magnitude Similarity Deviation on multiple scales for color image quality assessment (Zhang et al., 2017)
https://ieeexplore.ieee.org/document/7952357

Functions#

gmsd

Returns the GMSD between \(x\) and \(y\), without color space conversion and downsampling.

ms_gmsd

Returns the MS-GMSD between \(x\) and \(y\), without color space conversion.

Classes#

GMSD

Measures the GMSD between an input and a target.

MS_GMSD

Measures the MS-GMSD between an input and a target.

Descriptions#

piqa.gmsd.gmsd(x, y, kernel, value_range=1.0, c=0.00261437908496732, alpha=0.0)#

Returns the GMSD between \(x\) and \(y\), without color space conversion and downsampling.

\(\text{GMSD}(x, y)\) is the standard deviation of the Gradient Magnitude Similarity (GMS).

\[\begin{split}\text{GMS}(x, y) &= \frac{(2 - \alpha) \text{GM}(x) \text{GM}(y) + C} {\text{GM}(x)^2 + \text{GM}(y)^2 - \alpha \text{GM}(x) \text{GM}(y) + C} \\ \text{GM}(z) &= \left\| \nabla z \right\|_2\end{split}\]

where \(\nabla z\) is the result of a gradient convolution over \(z\).

Parameters:

  • x (Tensor) – An input tensor, \((N, 1, H, W)\).

  • y (Tensor) – A target tensor, \((N, 1, H, W)\).

  • kernel (Tensor) – A gradient kernel, \((2, 1, K, K)\).

  • value_range (float) – The value range \(L\) of the inputs (usually 1 or 255).

Note

For the remaining arguments, refer to Xue et al. (2013).

Returns:

The GMSD vector, \((N,)\).

Return type:

Tensor

Example

>>> x = torch.rand(5, 1, 256, 256)
>>> y = torch.rand(5, 1, 256, 256)
>>> kernel = gradient_kernel(prewitt_kernel())
>>> l = gmsd(x, y, kernel)
>>> l.shape
torch.Size([5])
piqa.gmsd.ms_gmsd(x, y, kernel, weights, value_range=1.0, c=0.00261437908496732, alpha=0.5)#

Returns the MS-GMSD between \(x\) and \(y\), without color space conversion.

\[\text{MS-GMSD}(x, y) = \sqrt{\sum^{M}_{i = 1} w_i \text{GMSD}(x^i, y^i)^2}\]

where \(x^i\) and \(y^i\) are obtained by downsampling the initial tensors by a factor \(2^{i - 1}\).

Parameters:

  • x (Tensor) – An input tensor, \((N, 1, H, W)\).

  • y (Tensor) – A target tensor, \((N, 1, H, W)\).

  • kernel (Tensor) – A gradient kernel, \((2, 1, K, K)\).

  • weights (Tensor) – The weights \(w_i\) of the scales, \((M,)\).

  • value_range (float) – The value range \(L\) of the inputs (usually 1 or 255).

Note

For the remaining arguments, refer to Zhang et al. (2017).

Returns:

The MS-GMSD vector, \((N,)\).

Return type:

Tensor

Example

>>> x = torch.rand(5, 1, 256, 256)
>>> y = torch.rand(5, 1, 256, 256)
>>> kernel = gradient_kernel(prewitt_kernel())
>>> weights = torch.rand(4)
>>> l = ms_gmsd(x, y, kernel, weights)
>>> l.shape
torch.Size([5])
class piqa.gmsd.GMSD(downsample=True, kernel=None, reduction='mean', **kwargs)#

Measures the GMSD between an input and a target.

Before applying gmsd, the input and target are converted from RBG to Y, the luminance color space, and downsampled by a factor 2.

Parameters:

  • downsample (bool) – Whether downsampling is enabled or not.

  • kernel (Tensor) – A gradient kernel, \((2, 1, K, K)\). If None, use the Prewitt kernel instead.

  • reduction (str) – Specifies the reduction to apply to the output: 'none', 'mean' or 'sum'.

  • kwargs – Keyword arguments passed to gmsd.

Example

>>> criterion = GMSD()
>>> x = torch.rand(5, 3, 256, 256, requires_grad=True)
>>> y = torch.rand(5, 3, 256, 256)
>>> l = criterion(x, y)
>>> l.shape
torch.Size([])
>>> l.backward()
forward(x, y)#
Parameters:

  • x (Tensor) – An input tensor, \((N, 3, H, W)\).

  • y (Tensor) – A target tensor, \((N, 3, H, W)\).

Returns:

The GMSD vector, \((N,)\) or \(()\) depending on reduction.

Return type:

Tensor

class piqa.gmsd.MS_GMSD(kernel=None, weights=None, reduction='mean', **kwargs)#

Measures the MS-GMSD between an input and a target.

Before applying ms_gmsd, the input and target are converted from RBG to Y, the luminance color space.

Parameters:

  • kernel (Tensor) – A gradient kernel, \((2, 1, K, K)\). If None, use the Prewitt kernel instead.

  • weights (Tensor) – The weights of the scales, \((M,)\). If None, use the MS_GMSD.WEIGHTS instead.

  • reduction (str) – Specifies the reduction to apply to the output: 'none', 'mean' or 'sum'.

  • kwargs – Keyword arguments passed to ms_gmsd.

Example

>>> criterion = MS_GMSD()
>>> x = torch.rand(5, 3, 256, 256, requires_grad=True)
>>> y = torch.rand(5, 3, 256, 256)
>>> l = criterion(x, y)
>>> l.shape
torch.Size([])
>>> l.backward()
WEIGHTS: Tensor = tensor([0.0960, 0.5960, 0.2890, 0.0190])#

Scale weights of Zhang et al. (2017).

forward(x, y)#
Parameters:

  • x (Tensor) – An input tensor, \((N, 3, H, W)\).

  • y (Tensor) – A target tensor, \((N, 3, H, W)\).

Returns:

The MS-GMSD vector, \((N,)\) or \(()\) depending on reduction.

Return type:

Tensor