{"id":5397,"library":"pyiqa","title":"PyTorch Toolbox for Image Quality Assessment","description":"pyiqa is a comprehensive PyTorch-based toolbox for Image Quality Assessment (IQA), offering reimplementations of numerous mainstream full-reference (FR) and no-reference (NR) metrics. It aims for GPU acceleration, often outperforming MATLAB counterparts, and provides calibrated results against official scripts where available. The library is actively maintained with frequent releases, adding new metrics, features, and bug fixes.","status":"active","version":"0.1.15.post2","language":"en","source_language":"en","source_url":"https://github.com/chaofengc/IQA-PyTorch","tags":["image-quality-assessment","pytorch","deep-learning","computer-vision","full-reference","no-reference","iqa"],"install":[{"cmd":"pip install pyiqa","lang":"bash","label":"Install stable version"},{"cmd":"pip install uv\nuv pip install pyiqa","lang":"bash","label":"Install faster with uv"},{"cmd":"pip install git+https://github.com/chaofengc/IQA-PyTorch.git","lang":"bash","label":"Install latest GitHub version"}],"dependencies":[{"reason":"Runtime environment","package":"python","version":">=3.8"},{"reason":"Core deep learning framework","package":"pytorch","version":">=1.12"},{"reason":"Image processing utilities","package":"torchvision","version":">=0.13"},{"reason":"GPU acceleration (optional)","package":"cuda","version":">=10.2","optional":true},{"reason":"Numerical operations","package":"numpy"},{"reason":"Image loading and processing","package":"opencv-python-headless"},{"reason":"Image loading and processing","package":"pillow"},{"reason":"Scientific computing","package":"scipy"},{"reason":"Progress bars","package":"tqdm"}],"imports":[{"symbol":"create_metric","correct":"from pyiqa import create_metric"},{"symbol":"list_models","correct":"from pyiqa import list_models"},{"note":"imread2tensor is directly exposed at the top level since recent versions for convenience.","wrong":"from pyiqa.utils import imread2tensor","symbol":"imread2tensor","correct":"from pyiqa import imread2tensor"}],"quickstart":{"code":"import pyiqa\nimport torch\n\n# List all available metrics\nprint(\"Available metrics:\", pyiqa.list_models())\n\ndevice = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n\n# Create a Full-Reference (FR) metric (e.g., LPIPS)\n# For gradient propagation (e.g., as a loss function), set as_loss=True\niqa_fr_metric = pyiqa.create_metric('lpips', device=device, as_loss=True)\nprint(f\"LPIPS metric ('lower_better'): {iqa_fr_metric.lower_better}\")\n\n# Create a No-Reference (NR) metric (e.g., NIQE)\niqa_nr_metric = pyiqa.create_metric('niqe', device=device)\nprint(f\"NIQE metric ('lower_better'): {iqa_nr_metric.lower_better}\")\n\n# Dummy image tensors (Batch, Channels, Height, Width), RGB, 0~1 range\nimg1 = torch.rand(1, 3, 256, 256).to(device)\nimg2 = torch.rand(1, 3, 256, 256).to(device)\n\n# Compute FR score\nscore_fr = iqa_fr_metric(img1, img2)\nprint(f\"LPIPS score: {score_fr.item():.4f}\")\n\n# Compute NR score\nscore_nr = iqa_nr_metric(img1)\nprint(f\"NIQE score: {score_nr.item():.4f}\")\n\n# Example of using a metric as a loss function (requires as_loss=True)\nloss = score_fr # LPIPS is lower_better, directly usable as loss\nloss.backward() # Gradients will be computed\nprint(\"Backward pass complete for LPIPS loss.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to v0.1.13 or newer. For users in mainland China, set `export HF_ENDPOINT=https://hf-mirror.com` for faster downloads.","message":"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.","severity":"breaking","affected_versions":"<0.1.13"},{"fix":"Consult `Model Cards` documentation for specific metrics or test for `backward()` compatibility.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of potential minor result variations when comparing outputs across v0.1.12 and earlier versions. Ensure consistent evaluation protocols for reproducibility.","message":"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.","severity":"gotcha","affected_versions":"<0.1.12"},{"fix":"Upgrade to `v0.1.14.1` or newer, where this bug has been resolved.","message":"A critical bug affecting `inception_score` calculation was present in version 0.1.14, leading to incorrect results.","severity":"deprecated","affected_versions":"0.1.14"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"<0.1.6.beta"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}