pyiqa.archs.vsi_arch
====================

.. py:module:: pyiqa.archs.vsi_arch

.. autoapi-nested-parse::

   VSI Metric.

   @article{zhang2014vsi,
     title={VSI: A visual saliency-induced index for perceptual image quality assessment},
     author={Zhang, Lin and Shen, Ying and Li, Hongyu},
     journal={IEEE Transactions on Image processing},
     volume={23},
     number={10},
     pages={4270--4281},
     year={2014},
     publisher={IEEE}
   }

   Created by: https://github.com/photosynthesis-team/piq/blob/master/piq/vsi.py

   Modified by: Jiadi Mo (https://github.com/JiadiMo)

   Refer to:
       IQA-Optimization from https://github.com/dingkeyan93/IQA-optimization/blob/master/IQA_pytorch/VSI.py
       Official matlab code is not available







Module Contents
---------------

.. py:function:: vsi(x: torch.Tensor, y: torch.Tensor, data_range: Union[int, float] = 1.0, c1: float = 1.27, c2: float = 386.0, c3: float = 130.0, alpha: float = 0.4, beta: float = 0.02, omega_0: float = 0.021, sigma_f: float = 1.34, sigma_d: float = 145.0, sigma_c: float = 0.001) -> torch.Tensor

   Compute Visual Saliency-induced Index for a batch of images.
   :param x: An input tensor. Shape :math:`(N, C, H, W)`.
   :param y: A target tensor. Shape :math:`(N, C, H, W)`.
   :param data_range: Maximum value range of images (usually 1.0 or 255).
   :param c1: coefficient to calculate saliency component of VSI.
   :param c2: coefficient to calculate gradient component of VSI.
   :param c3: coefficient to calculate color component of VSI.
   :param alpha: power for gradient component of VSI.
   :param beta: power for color component of VSI.
   :param omega_0: coefficient to get log Gabor filter at SDSP.
   :param sigma_f: coefficient to get log Gabor filter at SDSP.
   :param sigma_d: coefficient to get SDSP.
   :param sigma_c: coefficient to get SDSP.

   :returns: Index of similarity between two images. Usually in [0, 1] range.

   .. rubric:: References

   L. Zhang, Y. Shen and H. Li, "VSI: A Visual Saliency-Induced Index for Perceptual
   Image Quality Assessment," IEEE Transactions on Image Processing, vol. 23, no. 10,
   pp. 4270-4281, Oct. 2014, doi: 10.1109/TIP.2014.2346028
   https://ieeexplore.ieee.org/document/6873260

   .. note:: The original method supports only RGB image.


.. py:function:: sdsp(x: torch.Tensor, data_range: Union[int, float] = 255, omega_0: float = 0.021, sigma_f: float = 1.34, sigma_d: float = 145.0, sigma_c: float = 0.001) -> torch.Tensor

   SDSP algorithm for salient region detection from a given image.
   Supports only colour images with RGB channel order.
   :param x: Tensor. Shape :math:`(N, 3, H, W)`.
   :param data_range: Maximum value range of images (usually 1.0 or 255).
   :param omega_0: coefficient for log Gabor filter
   :param sigma_f: coefficient for log Gabor filter
   :param sigma_d: coefficient for the central areas, which have a bias towards attention
   :param sigma_c: coefficient for the warm colors, which have a bias towards attention

   :returns: Visual saliency map
   :rtype: torch.Tensor


.. py:class:: VSI(c1: float = 1.27, c2: float = 386.0, c3: float = 130.0, alpha: float = 0.4, beta: float = 0.02, data_range: Union[int, float] = 1.0, omega_0: float = 0.021, sigma_f: float = 1.34, sigma_d: float = 145.0, sigma_c: float = 0.001)

   Bases: :py:obj:`torch.nn.Module`


   Creates a criterion that measures Visual Saliency-induced Index error between
   each element in the input and target.
   :param data_range: Maximum value range of images (usually 1.0 or 255).
   :param c1: coefficient to calculate saliency component of VSI
   :param c2: coefficient to calculate gradient component of VSI
   :param c3: coefficient to calculate color component of VSI
   :param alpha: power for gradient component of VSI
   :param beta: power for color component of VSI
   :param omega_0: coefficient to get log Gabor filter at SDSP
   :param sigma_f: coefficient to get log Gabor filter at SDSP
   :param sigma_d: coefficient to get SDSP
   :param sigma_c: coefficient to get SDSP

   .. rubric:: References

   L. Zhang, Y. Shen and H. Li, "VSI: A Visual Saliency-Induced Index for Perceptual
   Image Quality Assessment," IEEE Transactions on Image Processing, vol. 23, no. 10,
   pp. 4270-4281, Oct. 2014, doi: 10.1109/TIP.2014.2346028
   https://ieeexplore.ieee.org/document/6873260


   .. py:method:: forward(x, y)

      Computation of VSI as a loss function.
      :param x: An input tensor. Shape :math:`(N, C, H, W)`.
      :param y: A target tensor. Shape :math:`(N, C, H, W)`.

      :returns: Value of VSI loss to be minimized in [0, 1] range.

      .. note::

         Both inputs are supposed to have RGB channels order in accordance with the original approach.
         Nevertheless, the method supports greyscale images, which they are converted to RGB by copying the grey
         channel 3 times.