{"id":8427,"library":"piq","title":"PyTorch Image Quality (PIQ)","description":"PIQ (PyTorch Image Quality) is a collection of measures and metrics for automatic image quality assessment in image-to-image tasks such as denoising, super-resolution, and image generation. Currently at version 0.8.0, the library offers both functional interfaces for calculating metrics and PyTorch modules for using them as loss functions. It has a regular release cadence, with minor versions released every 1-2 months, continually extending its set of measures and metrics.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/photosynthesis-team/piq","tags":["pytorch","image-quality","metrics","computer-vision","deep-learning"],"install":[{"cmd":"pip install piq","lang":"bash","label":"PyPI"},{"cmd":"conda install piq -c photosynthesis-team -c conda-forge -c pytorch","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Core dependency for all image quality metrics and loss functions.","package":"torch","optional":false},{"reason":"Required for the Geometry Score (GS) metric.","package":"gudhi","optional":true}],"imports":[{"symbol":"ssim","correct":"from piq import ssim"},{"symbol":"SSIMLoss","correct":"from piq import SSIMLoss"},{"symbol":"brisque","correct":"from piq import brisque"},{"symbol":"CLIPIQA","correct":"from piq import CLIPIQA"},{"note":"The library was renamed from PhotoSynthesis.Metrics to piq in v0.4.1. Use 'from piq import ...' instead.","wrong":"from PhotoSynthesis.Metrics import ssim","symbol":"PhotoSynthesis.Metrics"}],"quickstart":{"code":"import torch\nfrom piq import ssim, SSIMLoss\n\n# Example tensors (batch_size, channels, height, width)\nx = torch.rand(4, 3, 256, 256, requires_grad=True)\ny = torch.rand(4, 3, 256, 256)\n\n# 1. Functional interface: Compute SSIM as a measure\nssim_index = ssim(x, y, data_range=1.)\nprint(f\"SSIM index: {ssim_index.item():0.4f}\")\n\n# 2. Class interface: Use SSIM as a loss function\nloss_fn = SSIMLoss(data_range=1.)\noutput_loss = loss_fn(x, y)\noutput_loss.backward() # Backpropagate the loss\nprint(f\"SSIM Loss: {output_loss.item():0.4f}\")","lang":"python","description":"This quickstart demonstrates how to calculate the Structural Similarity Index (SSIM) using both the functional interface to get a metric value and the class-based interface to use it as a loss function for gradient computation. Input tensors `x` and `y` are random PyTorch tensors, typically representing predicted and target images. The `data_range` parameter is crucial and should match the actual pixel value range of the input images (e.g., `1.0` for images in `[0, 1]` or `255.0` for images in `[0, 255]`)."},"warnings":[{"fix":"Update all import statements to use `from piq import ...`.","message":"The library underwent a significant rename from `PhotoSynthesis.Metrics` to `piq` in version 0.4.1. Code using old import paths (e.g., `from PhotoSynthesis.Metrics import ssim`) will fail.","severity":"breaking","affected_versions":"<=0.4.0"},{"fix":"Update your PyTorch and torchvision installations to a version greater than `1.5.0`.","message":"Backpropagation for the `brisque` metric is not available when using `torch==1.5.0` due to a known bug in PyTorch's `argmin` and `argmax` operations.","severity":"gotcha","affected_versions":"torch==1.5.0"},{"fix":"Ensure input tensors are normalized to the expected `data_range` (e.g., `[0, 1]`) or provide the correct `data_range` argument. For specific metrics, consult documentation for `allow_negative` flags or shape requirements (e.g., `multi_scale_gmsd` requires `height, width >= 2 ** number_of_scales + 1`).","message":"Many PIQ metrics expect input tensors to have specific value ranges (e.g., non-negative for image pixels) or shapes. Default input validation includes checks like `assert torch.all(tensor >= 0)`, which can raise errors if inputs are outside expected bounds, particularly when using metrics as loss functions without a final activation. Some metrics (since v0.5.4) offer an `allow_negative=True` flag.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your Python script with the `-O` flag (e.g., `python -O your_script.py`) to disable all assertions.","message":"For performance-critical applications, PIQ's extensive input validation (assertions) can introduce overhead. These checks can be disabled globally.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure input tensors are normalized to the `data_range` expected by the metric (e.g., `data_range=1.0` for `[0,1]`, `data_range=255.0` for `[0,255]`). Apply an activation function (like `torch.sigmoid`) to your model's output if it produces values outside the expected positive range and the metric doesn't support negative values via a flag. Some metrics have an `allow_negative=True` flag to permit negative inputs.","cause":"Some PIQ metrics or loss functions validate that input tensor values are non-negative by default (e.g., expecting image pixels in [0, 1] or [0, 255]). If your network outputs values outside this range and no appropriate activation (like `sigmoid`) is applied, or `data_range` is incorrect, this error occurs.","error":"RuntimeError: Expected input to be non-negative, but got values outside this range."},{"fix":"Verify the shape of your input tensors. If your images are `NHWC`, use `tensor.permute(0, 3, 1, 2)` to convert them to `NCHW` before passing to PIQ functions. Also, check specific metric documentation for any minimum height/width requirements (e.g., `multi_scale_gmsd`).","cause":"PIQ metrics typically expect image tensors in `NCHW` format (Batch, Channels, Height, Width). A common mistake is providing `NHWC` (Batch, Height, Width, Channels) or incorrect spatial dimensions.","error":"Input tensor shape mismatch. Expected NCHW, got NWHC."},{"fix":"Update your import statements to use the new package name: `from piq import ssim` (or other desired metrics).","cause":"You are attempting to import from `PhotoSynthesis.Metrics`, which was the old package name. The library was renamed to `piq` in version 0.4.1.","error":"AttributeError: module 'PhotoSynthesis.Metrics' has no attribute 'ssim'"},{"fix":"Ensure that the `prediction` and `target` tensors passed to PIQ metrics have identical shapes across all dimensions (batch size, channels, height, width). Resample or crop images if necessary before comparison.","cause":"This generic PyTorch error indicates that the dimensions of the two input tensors (e.g., `prediction` and `target` images) do not match, which is a common requirement for full-reference image quality metrics.","error":"RuntimeError: The size of tensor a (256) must match the size of tensor b (512) at non-singleton dimension 2"}]}