PyTorch Toolbox for Image Quality Assessment

Warnings

• breaking Model weights for metrics were migrated to Hugging Face Hub (chaofengc/IQA-PyTorch-Weights) in v0.1.13. Older versions might try to download from previous locations which could be slower or unavailable.
  Fix: Upgrade to v0.1.13 or newer. For users in mainland China, set `export HF_ENDPOINT=https://hf-mirror.com` for faster downloads.
• gotcha When using metrics as a loss function (`as_loss=True`), gradient propagation is enabled. However, not all metrics within pyiqa fully support backpropagation. Always verify a metric's support for backpropagation if used in a training loop.
  Fix: Consult `Model Cards` documentation for specific metrics or test for `backward()` compatibility.
• gotcha The `set_random_seed` function was removed from the test process in v0.1.12. This change, along with a shift to uniform cropping for some metrics, may lead to slight differences in reported metric results compared to versions prior to v0.1.12.
  Fix: Be aware of potential minor result variations when comparing outputs across v0.1.12 and earlier versions. Ensure consistent evaluation protocols for reproducibility.
• deprecated A critical bug affecting `inception_score` calculation was present in version 0.1.14, leading to incorrect results.
  Fix: Upgrade to `v0.1.14.1` or newer, where this bug has been resolved.
• gotcha The FID (Fréchet Inception Distance) metric typically requires directories of images or precomputed statistics as input, not individual image files, when called from `create_metric`.
  Fix: Provide a path to a directory containing images for both target and reference inputs, or use precomputed statistics, when calculating FID. Refer to `clean-fid` documentation for more details.
• breaking A critical bug in NRQM calculation (stemming from SSIM function usage) was identified and resolved in `v0.1.6.beta`. This also affected the PI (Perceptual Index) metric. Calculations from previous versions may be inaccurate.
  Fix: Upgrade to `v0.1.6.beta` or newer to ensure correct NRQM and PI metric calculations. Recalculate any results obtained with affected older versions.

Install

• pip install pyiqa Install stable version
• pip install uv uv pip install pyiqa Install faster with uv
• pip install git+https://github.com/chaofengc/IQA-PyTorch.git Install latest GitHub version

Imports

• create_metric

  from pyiqa import create_metric

• list_models

  from pyiqa import list_models

• imread2tensor

  from pyiqa import imread2tensor

  imread2tensor is directly exposed at the top level since recent versions for convenience.

Quickstart

This quickstart demonstrates how to list available metrics, create both Full-Reference (FR) and No-Reference (NR) IQA models, perform inference with dummy PyTorch tensors, and use a metric (like LPIPS) as a loss function with gradient propagation.

import pyiqa
import torch

# List all available metrics
print("Available metrics:", pyiqa.list_models())

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# Create a Full-Reference (FR) metric (e.g., LPIPS)
# For gradient propagation (e.g., as a loss function), set as_loss=True
iqa_fr_metric = pyiqa.create_metric('lpips', device=device, as_loss=True)
print(f"LPIPS metric ('lower_better'): {iqa_fr_metric.lower_better}")

# Create a No-Reference (NR) metric (e.g., NIQE)
iqa_nr_metric = pyiqa.create_metric('niqe', device=device)
print(f"NIQE metric ('lower_better'): {iqa_nr_metric.lower_better}")

# Dummy image tensors (Batch, Channels, Height, Width), RGB, 0~1 range
img1 = torch.rand(1, 3, 256, 256).to(device)
img2 = torch.rand(1, 3, 256, 256).to(device)

# Compute FR score
score_fr = iqa_fr_metric(img1, img2)
print(f"LPIPS score: {score_fr.item():.4f}")

# Compute NR score
score_nr = iqa_nr_metric(img1)
print(f"NIQE score: {score_nr.item():.4f}")

# Example of using a metric as a loss function (requires as_loss=True)
loss = score_fr # LPIPS is lower_better, directly usable as loss
loss.backward() # Gradients will be computed
print("Backward pass complete for LPIPS loss.")