pyiqa.archs.afine_arch
======================

.. py:module:: pyiqa.archs.afine_arch

.. autoapi-nested-parse::

   A-FINE architecture for generalized image quality assessment.

   Reference:
           Chen, D., Wu, T., Ma, K., and Zhang, L.
           Toward Generalized Image Quality Assessment: Relaxing the Perfect
           Reference Quality Assumption. CVPR 2025.

   Project page:
           https://github.com/ChrisDud0257/AFINE

   This implementation is intended for inference with pretrained checkpoints.









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

.. py:data:: default_model_urls

.. py:function:: scale_finalscore(score, yita1=100, yita2=0, yita3=-1.971, yita4=-2.3734)

   Map raw A-FINE score to a bounded, human-readable range.

   :param score: Raw score tensor.
   :type score: torch.Tensor
   :param yita1: Upper bound of target range.
   :type yita1: float
   :param yita2: Lower bound of target range.
   :type yita2: float
   :param yita3: Logistic midpoint parameter.
   :type yita3: float
   :param yita4: Logistic scale parameter.
   :type yita4: float

   :returns: Scaled score tensor.
   :rtype: torch.Tensor


.. py:class:: AFINEQhead(chns=(3, 768, 768, 768, 768, 768, 768, 768, 768, 768, 768, 768, 768), feature_out_channel=1, input_dim=768, hidden_dim=128, mean=(0.48145466, 0.4578275, 0.40821073), std=(0.26862954, 0.26130258, 0.27577711))

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


   Naturalness head used by A-FINE.

   This head aggregates mean and variance statistics from CLIP feature maps and
   predicts the no-reference naturalness term.

   :param chns: Channel dimensions for input image and feature
                levels.
   :type chns: tuple[int, ...]
   :param feature_out_channel: Number of output channels for the score head.
   :type feature_out_channel: int
   :param input_dim: Channel dimension of CLIP feature tokens.
   :type input_dim: int
   :param hidden_dim: Hidden width for projection layers.
   :type hidden_dim: int
   :param mean: RGB normalization mean.
   :type mean: tuple[float, float, float]
   :param std: RGB normalization standard deviation.
   :type std: tuple[float, float, float]


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


.. py:class:: AFINEDhead(chns=(3, 768, 768, 768, 768, 768, 768, 768, 768, 768, 768, 768, 768), mean=(0.48145466, 0.4578275, 0.40821073), std=(0.26862954, 0.26130258, 0.27577711))

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


   Fidelity head used by A-FINE.

   The module computes similarity statistics between distorted and reference
   features and outputs a full-reference fidelity term.

   :param chns: Channel dimensions for each feature level.
   :type chns: tuple[int, ...]
   :param mean: RGB normalization mean.
   :type mean: tuple[float, float, float]
   :param std: RGB normalization standard deviation.
   :type std: tuple[float, float, float]


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


.. py:class:: AFINENLM_NR_Fit(yita1=2, yita2=-2, yita3=3.7833, yita4=7.5676)

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


   Nonlinear calibration layer for the naturalness branch.


   .. py:method:: forward(x)


.. py:class:: AFINENLM_FR_Fit_with_limit(yita1=2, yita2=-2, yita3=-24.1335, yita4=8.1093, yita3_upper=-21, yita3_lower=-27, yita4_upper=9, yita4_lower=7)

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


   Bounded nonlinear calibration layer for the fidelity branch.


   .. py:method:: forward(x)


.. py:class:: AFINELearnLambda(k=5)

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


   Adaptive fusion layer for naturalness and fidelity terms.


   .. py:method:: forward(x_nr, ref_nr, xref_fr)


.. py:class:: AFINE(model_type='afine_all_scale', clip_backbone='ViT-B/32', step=32, num_patch=15, pretrained=True, pretrained_model_path=None, url_key='afine')

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


   A-FINE inference model.

   :param model_type: Output type.
                      Supported values are ``"afine_all_scale"``, ``"afine_all"``,
                      ``"afine_fr"``, and ``"afine_nr"``.
   :type model_type: str
   :param clip_backbone: CLIP backbone identifier.
   :type clip_backbone: str
   :param step: Kept for compatibility with original config interface.
   :type step: int
   :param num_patch: Kept for compatibility with original config interface.
   :type num_patch: int
   :param pretrained: Kept for compatibility. This implementation expects
                      a pretrained checkpoint.
   :type pretrained: bool
   :param pretrained_model_path: Local checkpoint path. If ``None``,
                                 the model is downloaded from ``url_key``.
   :type pretrained_model_path: str | None
   :param url_key: Key used to resolve default checkpoint URL.
   :type url_key: str

   .. rubric:: Example

   >>> metric = AFINE(model_type='afine_all_scale')
   >>> dis = torch.rand(1, 3, 224, 224)
   >>> ref = torch.rand(1, 3, 224, 224)
   >>> score = metric(dis, ref)


   .. py:method:: forward(dis, ref=None)

      Run A-FINE scoring.

      :param dis: Distorted image tensor with shape
                  ``(N, 3, H, W)``.
      :type dis: torch.Tensor
      :param ref: Optional reference image tensor with the
                  same shape as ``dis``. If ``None``, ``dis`` is reused.
      :type ref: torch.Tensor | None

      :returns: Score tensor according to ``model_type``.
      :rtype: torch.Tensor

      :raises AssertionError: If image height or width is not divisible by 32.
      :raises ValueError: If ``model_type`` is unsupported.

      .. rubric:: Notes

      Lower values indicate better quality for A-FINE terms.