plenoptic.metric.nlpd#

plenoptic.metric.nlpd(img1, img2, epsilon=1e-10)[source]#

Compute the normalized Laplacian Pyramid Distance.

As described in Laparra et al., 2016 [12], this is an image quality metric based on the transformations associated with the early visual system: local luminance subtraction and local contrast gain control.

A laplacian pyramid subtracts a local estimate of the mean luminance at six scales. Then a local gain control divides these centered coefficients by a weighted sum of absolute values in spatial neighborhood.

These weights parameters were optimized for redundancy reduction over an training database of (undistorted) natural images, as described in the paper. Parameters were copied from matlab code used for the paper, found online [13].

Note that we compute root mean squared error for each scale, and then average over these, effectively giving larger weight to the lower frequency coefficients (which are fewer in number, due to subsampling).

Changed in version 2.0.0: Made epsilon parameter public (previously, was hard-coded to 1e-10).

Parameters:

  • img1 (Tensor) – The first image or batch of images of shape (batch, channel, height, width).

  • img2 (Tensor) – The second image or batch of images of shape (batch, channel, height, width). The heights and widths of img1 and img2 must be the same. The numbers of batches and channels of img1 and img2 need to be broadcastable: either they are the same or one of them is 1. The output will be computed separately for each channel (so channels are treated in the same way as batches). Both images should have values between 0 and 1. Otherwise, the result may be inaccurate, and we will raise a warning (but will still compute it).

  • epsilon (float (default: 1e-10)) – Float added to the computation of the average distance on each band, helpful for stabilizing gradient around zero for optimization purposes. Note that the distance between two identical images will thus be sqrt(epsilon) (see Examples).

Return type:

Tensor

Returns:

distance – The normalized Laplacian Pyramid distance, with shape (batch, channel).

Raises:

  • ValueError – If either img1 or img2 is not 4d.

  • ValueError – If img1 and img2 have different height or width.

  • ValueError – If img1 and img2 have different batch or channel, unless one of them has a 1 there, so they can be broadcast.

  • ValueError – If img1 and img2 have different dtypes.

Warns:

  • UserWarning – If either img1 or img2 has multiple channels, as SSIM was designed for grayscale images.

  • UserWarning – If either img1 or img2 has a value outside of range [0, 1].

References

Examples

>>> import plenoptic as po
>>> einstein_img = po.data.einstein()
>>> curie_img = po.data.curie()
>>> po.metric.nlpd(einstein_img, curie_img)
tensor([[1.3507]])

Distance between two identical images is sqrt(epsilon) (this is useful for stabilitizing gradient around zero during optimization):

>>> po.metric.nlpd(einstein_img, einstein_img)
tensor([[1.0000e-05]])
>>> po.metric.nlpd(einstein_img, einstein_img, epsilon=1e-20)
tensor([[1.0000e-10]])