{"id":3252,"library":"pytorch-msssim","title":"PyTorch MS-SSIM","description":"pytorch-msssim provides a fast and differentiable implementation of Multi-Scale Structural Similarity (MS-SSIM) and Structural Similarity (SSIM) index for PyTorch. It is designed to be efficient by using separable Gaussian kernels. The library is currently at version 1.0.0, with releases occurring as needed rather than on a strict schedule.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/VainF/pytorch-msssim","tags":["pytorch","ssim","ms-ssim","image processing","loss function","computer vision","quality assessment"],"install":[{"cmd":"pip install pytorch-msssim","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core PyTorch library for tensor operations and deep learning framework.","package":"torch","optional":false}],"imports":[{"symbol":"ssim","correct":"from pytorch_msssim import ssim"},{"symbol":"ms_ssim","correct":"from pytorch_msssim import ms_ssim"},{"symbol":"SSIM","correct":"from pytorch_msssim import SSIM"},{"symbol":"MS_SSIM","correct":"from pytorch_msssim import MS_SSIM"},{"note":"This refers to an older or different library/fork and is not the correct top-level package for `pytorch-msssim`.","wrong":"import pytorch_ssim","symbol":"pytorch_ssim"}],"quickstart":{"code":"import torch\nfrom pytorch_msssim import ssim, ms_ssim, SSIM, MS_SSIM\n\n# Create two dummy image tensors (batch_size, channels, height, width)\n# Images are typically non-negative, e.g., 0-255 or 0-1\nX = torch.rand(4, 3, 256, 256) * 255 # Example: batch of 4 RGB images, 0-255 range\nY = torch.rand(4, 3, 256, 256) * 255 # Another batch for comparison\n\n# Calculate SSIM and MS-SSIM values (per image in batch)\n# data_range should match the maximum possible pixel value (e.g., 255 for 0-255 images)\nssim_val = ssim(X, Y, data_range=255, size_average=False) # Returns (N,) tensor\nms_ssim_val = ms_ssim(X, Y, data_range=255, size_average=False) # Returns (N,) tensor\n\nprint(f\"SSIM values: {ssim_val}\")\nprint(f\"MS-SSIM values: {ms_ssim_val}\")\n\n# Using SSIM/MS_SSIM as a loss function (returns scalar mean loss)\n# For loss, set size_average=True and typically use 1 - score\nssim_loss_module = SSIM(data_range=255, size_average=True, channel=3)\nms_ssim_loss_module = MS_SSIM(data_range=255, size_average=True, channel=3)\n\nssim_loss = 1 - ssim_loss_module(X, Y) # A scalar tensor\nms_ssim_loss = 1 - ms_ssim_loss_module(X, Y) # A scalar tensor\n\nprint(f\"SSIM Loss: {ssim_loss}\")\nprint(f\"MS-SSIM Loss: {ms_ssim_loss}\")","lang":"python","description":"This quickstart demonstrates how to calculate SSIM and MS-SSIM between two batches of images and how to use the SSIM and MS_SSIM classes as loss functions. Ensure your input tensors `X` and `Y` are of shape `(N, C, H, W)` and `data_range` is set correctly for your pixel value range."},"warnings":[{"fix":"Ensure input tensors `X` and `Y` contain pixel values within `[0, data_range]`.","message":"Input images must be non-negative and denormalized to the expected `data_range`. If your images are normalized (e.g., -1 to 1), you must denormalize them to a range like [0, 1] or [0, 255] before passing them to `ssim` or `ms_ssim`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When using `ssim` directly, consider setting `nonnegative_ssim=True` if negative SSIM values are undesirable or cause further issues in your pipeline. For training stability with MS-SSIM, `normalize='relu'` can be beneficial.","message":"The `nonnegative_ssim=True` parameter is recommended for SSIM to prevent negative output values, though it defaults to `False` for consistency with other implementations like TensorFlow/scikit-image. For MS-SSIM, intermediate SSIM responses are internally forced to be non-negative to avoid NaN results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For a single image, add a batch dimension: `image.unsqueeze(0)` to make it `(1, C, H, W)`.","message":"Input tensors `X` and `Y` must be 4-dimensional `(N, C, H, W)` (batch_size, channels, height, width). Passing single 3D images (e.g., `(C, H, W)`) will lead to errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Initialize `MS_SSIM(..., normalize='relu')` when using it as a loss in training.","message":"When using MS-SSIM as a loss function for training, especially with unstable models, setting the `normalize` parameter (e.g., `normalize='relu'`) in the `MS_SSIM` module can significantly improve training stability and help avoid NaN results. This `normalize` option is adapted from a different implementation to enhance training robustness.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}