piqa.fsim#

Feature Similarity (FSIM)

This module implements the FSIM in PyTorch.

Original

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

References

FSIM: A Feature Similarity Index for Image Quality Assessment (Zhang et al., 2011)
https://ieeexplore.ieee.org/document/5705575
Image Features From Phase Congruency (Kovesi, 1999)

Functions#

fsim

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

pc_filters

Returns the log-Gabor filters for phase_congruency.

phase_congruency

Returns the Phase Congruency (PC) of \(x\).

Classes#

FSIM

Measures the FSIM between an input and a target.

Descriptions#

piqa.fsim.fsim(x, y, pc_x, pc_y, kernel, value_range=1.0, t1=0.85, t2=0.0024605920799692428, t3=0.0030757400999615533, t4=0.0030757400999615533, lmbda=0.03)#

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

Parameters:

  • x (Tensor) – An input tensor, \((N, 3 \text{ or } 1, H, W)\).

  • y (Tensor) – A target tensor, \((N, 3 \text{ or } 1, H, W)\).

  • pc_x (Tensor) – The input phase congruency, \((N, H, W)\).

  • pc_y (Tensor) – The target phase congruency, \((N, 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 Zhang et al. (2011).

Returns:

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

Return type:

Tensor

Example

>>> x = torch.rand(5, 3, 256, 256)
>>> y = torch.rand(5, 3, 256, 256)
>>> filters = pc_filters(x)
>>> pc_x = phase_congruency(x[:, :1], filters)
>>> pc_y = phase_congruency(y[:, :1], filters)
>>> kernel = gradient_kernel(scharr_kernel())
>>> l = fsim(x, y, pc_x, pc_y, kernel)
>>> l.shape
torch.Size([5])
piqa.fsim.pc_filters(x, scales=4, orientations=4, wavelength=6.0, factor=2.0, sigma_f=0.5978, sigma_theta=0.6545)#

Returns the log-Gabor filters for phase_congruency.

Parameters:

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

  • scales (int) – The number of scales, \(S_1\).

  • orientations (int) – The number of orientations, \(S_2\).

Note

For the remaining arguments, refer to Kovesi (1999).

Returns:

The filters tensor, \((S_1, S_2, H, W)\).

Return type:

Tensor

piqa.fsim.phase_congruency(x, filters, value_range=1.0, k=2.0, rescale=1.7, eps=1e-08)#

Returns the Phase Congruency (PC) of \(x\).

Parameters:

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

  • filters (Tensor) – The frequency domain filters, \((S_1, S_2, H, W)\).

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

Note

For the remaining arguments, refer to Kovesi (1999).

Returns:

The PC tensor, \((N, H, W)\).

Return type:

Tensor

Example

>>> x = torch.rand(5, 1, 256, 256)
>>> filters = pc_filters(x)
>>> pc = phase_congruency(x, filters)
>>> pc.shape
torch.Size([5, 256, 256])
class piqa.fsim.FSIM(chromatic=True, downsample=True, kernel=None, reduction='mean', **kwargs)#

Measures the FSIM between an input and a target.

Before applying fsim, the input and target are converted from RBG to Y(IQ) and downsampled to a 256-ish resolution.

Parameters:

  • chromatic (bool) – Whether to use the chromatic channels (IQ) or not.

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

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

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

  • kwargs – Keyword arguments passed to fsim.

Example

>>> criterion = FSIM()
>>> x = torch.rand(5, 3, 256, 256, requires_grad=True)
>>> y = torch.rand(5, 3, 256, 256)
>>> l = 1 - 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 FSIM vector, \((N,)\) or \(()\) depending on reduction.

Return type:

Tensor