pyiqa.archs.fid_arch
====================

.. py:module:: pyiqa.archs.fid_arch

.. autoapi-nested-parse::

   FID and clean-fid metric implementation.

   Codes are borrowed from the clean-fid project:
       - https://github.com/GaParmar/clean-fid

   .. rubric:: References

   [1] GANs Trained by a Two Time-Scale Update Rule Converge to a Local Nash Equilibrium.
       Martin Heusel, Hubert Ramsauer, Thomas Unterthiner, Bernhard Nessler, Sepp Hochreiter
       NeurIPS, 2017
   [2] On Aliased Resizing and Surprising Subtleties in GAN Evaluation
       Gaurav Parmar, Richard Zhang, Jun-Yan Zhu
       CVPR, 2022









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

.. py:data:: default_model_urls

.. py:class:: ResizeDataset(files, mode, size=(299, 299))

   Bases: :py:obj:`torch.utils.data.Dataset`


   A placeholder Dataset that enables parallelizing the resize operation
   using multiple CPU cores
   files: list of all files in the folder
   mode:
       - clean: use PIL resize before calculate features
       - legacy_pytorch: do not resize here, but before pytorch model


.. py:function:: get_reference_statistics(name, res, mode='clean', split='test', metric='FID')

   Load precomputed reference statistics for commonly used datasets


.. py:function:: frechet_distance(mu1, sigma1, mu2, sigma2, eps=1e-06)

   Numpy implementation of the Frechet Distance.
   The Frechet distance between two multivariate Gaussians X_1 ~ N(mu_1, C_1)
   and X_2 ~ N(mu_2, C_2) is
           d^2 = ||mu_1 - mu_2||^2 + Tr(C_1 + C_2 - 2*sqrt(C_1*C_2)).
   Stable version by Danica J. Sutherland.
   Params:
       mu1   : Numpy array containing the activations of a layer of the
               inception net (like returned by the function 'get_predictions')
               for generated samples.
       mu2   : The sample mean over activations, precalculated on an
               representative data set.
       sigma1: The covariance matrix over activations for generated samples.
       sigma2: The covariance matrix over activations, precalculated on an
               representative data set.


.. py:function:: maximum_mean_discrepancy(feats1, feats2, kernel_type='polynomial', num_subsets=100, max_subset_size=1000)

.. py:function:: mmd_polynomial_kernel(feats1, feats2, num_subsets=100, max_subset_size=1000)

   Compute the KID score given the sets of features


.. py:function:: mmd_rbf_kernel(x, y, sigma: float = 10.0, scale: int = 1000)

   Compute MMD with RBF kernel, ref to https://github.com/google-research/google-research/blob/master/cmmd/distance.py


.. py:function:: get_folder_features(fdir, model=None, num_workers=12, batch_size=32, test_img_size=(299, 299), device=torch.device('cuda'), mode='clean', description='', verbose=True)

   Compute the inception features for a folder of image files


.. py:class:: DINOv2

   DINOv2 model for feature extraction.

   Provides a wrapper for the DINOv2 vision transformer model for image feature extraction.


.. py:class:: FID(dims: int = 2048, backbone: str = 'inceptionv3')

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


   Implements the Fréchet Inception Distance (FID) and Clean-FID metrics.

   The FID measures the distance between the feature representations of two sets of images,
   one generated by a model and the other from a reference dataset.

   .. attribute:: model

      The feature extraction network.

      :type: nn.Module

   .. attribute:: test_img_size

      Default image size for feature extraction.

      :type: Tuple[int, int]


   .. py:method:: forward(fdir1: Optional[str] = None, fdir2: Optional[str] = None, mode: str = 'clean', distance_type: str = 'frechet', kernel_type: str = 'polynomial', dataset_name: Optional[str] = None, dataset_res: int = 1024, dataset_split: str = 'train', num_workers: int = 4, batch_size: int = 8, device: torch.device = torch.device('cuda'), verbose: bool = True, **kwargs: Any) -> float

      Compute the FID or Clean-FID score between two sets of images.

      :param fdir1: Path to the first folder of images.
      :type fdir1: Optional[str]
      :param fdir2: Path to the second folder of images.
      :type fdir2: Optional[str]
      :param mode: Calculation mode. Defaults to 'clean'.
      :type mode: str, optional
      :param distance_type: Distance metric to use. Defaults to 'frechet'.
      :type distance_type: str, optional
      :param kernel_type: Kernel type for MMD. Defaults to 'polynomial'.
      :type kernel_type: str, optional
      :param dataset_name: Reference dataset name. Defaults to None.
      :type dataset_name: Optional[str], optional
      :param dataset_res: Reference dataset resolution. Defaults to 1024.
      :type dataset_res: int, optional
      :param dataset_split: Reference dataset split. Defaults to 'train'.
      :type dataset_split: str, optional
      :param num_workers: Number of workers for data loading. Defaults to 4.
      :type num_workers: int, optional
      :param batch_size: Batch size for processing. Defaults to 8.
      :type batch_size: int, optional
      :param device: Computation device. Defaults to cuda.
      :type device: torch.device, optional
      :param verbose: Print progress messages. Defaults to True.
      :type verbose: bool, optional

      :returns: FID or distance score between image sets.
      :rtype: float

      :raises ValueError: For invalid input combinations or parameters.