pyiqa.archs.fgresq_arch
=======================

.. py:module:: pyiqa.archs.fgresq_arch

.. autoapi-nested-parse::

   FGResQ metric implementation.

   Reference:
       Sheng, X., Pan, X., Yang, Z., Chen, P., and Li, L.
       Fine-grained Image Quality Assessment for Perceptual Image Restoration.
       AAAI 2026.

   Reference URL:
       https://github.com/sxfly99/FGResQ









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

.. py:data:: default_model_urls

.. py:function:: load_checkpoint(model_path)

   Load and normalize a checkpoint state dict.

   :param model_path: Path to the checkpoint file.
   :type model_path: str

   :returns: Cleaned state dict.
   :rtype: dict


.. py:function:: get_pooler_output(model, x)

   Extract pooled CLIP visual features.

   :param model: CLIP vision backbone.
   :type model: CLIPVisionModel
   :param x: Input tensor.
   :type x: torch.Tensor

   :returns: Pooled feature tensor.
   :rtype: torch.Tensor


.. py:class:: FGResQ(clip_model='openai/clip-vit-base-patch16', task_clip_model='openai/clip-vit-base-patch16', clip_freeze=True, pretrained=True, pretrained_model_path=None, degradation_model_path=None, input_size=224, resize_size=256, default_mean=OPENAI_CLIP_MEAN, default_std=OPENAI_CLIP_STD, score_scale=0.3)

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


   FGResQ no-reference image quality model.

   :param clip_model: HuggingFace CLIP vision backbone id.
   :type clip_model: str
   :param task_clip_model: CLIP backbone for the degradation-aware branch.
   :type task_clip_model: str
   :param clip_freeze: Whether to freeze the main CLIP backbone.
   :type clip_freeze: bool
   :param pretrained: Whether to load official pretrained weights.
   :type pretrained: bool
   :param pretrained_model_path: Optional local checkpoint path for
                                 the main FGResQ weights.
   :type pretrained_model_path: str | None
   :param degradation_model_path: Optional local checkpoint path for
                                  the degradation branch weights.
   :type degradation_model_path: str | None
   :param input_size: Final center crop size.
   :type input_size: int
   :param resize_size: Resize size before center crop.
   :type resize_size: int
   :param The network returns a single quality score when only ``x0`` is given:
   :param :
   :param and returns ``quality0``:
   :param ``quality1``:
   :param ``rank``:
   :param and ``rank_prob``:
   :param when both ``x0`` and ``x1`` are provided.:
   :param default_mean: Input normalization mean.
   :type default_mean: tuple[float, float, float]
   :param default_std: Input normalization std.
   :type default_std: tuple[float, float, float]
   :param score_scale: Scale factor used before the sigmoid output head.
   :type score_scale: float


   .. py:method:: load_degradation_weights(model_path)

      Load degradation-branch weights.

      :param model_path: Path to the degradation checkpoint.
      :type model_path: str



   .. py:method:: load_pretrained_weights(model_path)

      Load main FGResQ weights.

      :param model_path: Path to the FGResQ checkpoint.
      :type model_path: str



   .. py:method:: preprocess(x)

      Preprocess an input image tensor.

      :param x: Input tensor with shape ``(N, C, H, W)``.
      :type x: torch.Tensor

      :returns: Preprocessed tensor.
      :rtype: torch.Tensor



   .. py:method:: get_quality_features(x)

      Extract FGResQ quality features.

      :param x: Preprocessed image tensor.
      :type x: torch.Tensor

      :returns: Concatenated quality features.
      :rtype: torch.Tensor



   .. py:method:: forward_single(x)

      Predict single-image quality.

      :param x: Preprocessed image tensor.
      :type x: torch.Tensor

      :returns: Predicted quality score.
      :rtype: torch.Tensor



   .. py:method:: forward_pair(x0, x1)

      Predict pairwise quality and comparison logits.

      :param x0: First preprocessed image tensor.
      :type x0: torch.Tensor
      :param x1: Second preprocessed image tensor.
      :type x1: torch.Tensor

      :returns: Single-image scores
                for both inputs and pairwise comparison logits.
      :rtype: tuple[torch.Tensor, torch.Tensor, torch.Tensor]



   .. py:method:: get_pair_rank(compare_logits)

      Convert comparison logits to a discrete rank label.

      :param compare_logits: Pairwise comparison logits.
      :type compare_logits: torch.Tensor

      :returns: Rank tensor with shape ``(N, 1)`` where
                ``0=image2_better``, ``1=image1_better``, and
                ``2=similar_quality``.
      :rtype: torch.Tensor



   .. py:method:: get_pair_result(quality0, quality1, compare_logits)

      Format pairwise prediction outputs.

      :param quality0: Quality of the first image.
      :type quality0: torch.Tensor
      :param quality1: Quality of the second image.
      :type quality1: torch.Tensor
      :param compare_logits: Pairwise comparison logits.
      :type compare_logits: torch.Tensor

      :returns:     ``quality0``, ``quality1``, ``rank``, and ``rank_prob``.
      :rtype: tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]



   .. py:method:: forward(x0, x1=None)

      Forward pass for FGResQ.

      :param x0: First input tensor.
      :type x0: torch.Tensor
      :param x1: Optional second input tensor.
      :type x1: torch.Tensor | None

      :returns: Output depends on whether ``x1`` is given.
      :rtype: torch.Tensor | tuple