Registry / ai-ml / pytorch-msssim

pytorch-msssim

JSON →
library1.0.0pypypi✓ verified 25d ago

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.

pip install pytorch-msssim
INSTALL
IMPORT
SIG · PYTORCH-MSSSIM
P
pytorch-msssim
ai-mlpythonv1.0.0
Install
65.1s avg
Import
5480ms
Disk
4710MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 73.7s
py 3.11
✕ build_error
✓ 66.9s
py 3.12
✕ build_error
✓ 63.3s
py 3.13
✕ build_error
✓ 56.6s
py 3.9
✕ build_error
✕ timeout
4710MB installed
● package 4710MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ssim
from pytorch_msssim import ssim
ms_ssim
from pytorch_msssim import ms_ssim
SSIM
from pytorch_msssim import SSIM
MS_SSIM
from pytorch_msssim import MS_SSIM
pytorch_ssim
import pytorch_ssim
This refers to an older or different library/fork and is not the correct top-level package for `pytorch-msssim`.

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.

import torch from pytorch_msssim import ssim, ms_ssim, SSIM, MS_SSIM # Create two dummy image tensors (batch_size, channels, height, width) # Images are typically non-negative, e.g., 0-255 or 0-1 X = torch.rand(4, 3, 256, 256) * 255 # Example: batch of 4 RGB images, 0-255 range Y = torch.rand(4, 3, 256, 256) * 255 # Another batch for comparison # Calculate SSIM and MS-SSIM values (per image in batch) # data_range should match the maximum possible pixel value (e.g., 255 for 0-255 images) ssim_val = ssim(X, Y, data_range=255, size_average=False) # Returns (N,) tensor ms_ssim_val = ms_ssim(X, Y, data_range=255, size_average=False) # Returns (N,) tensor print(f"SSIM values: {ssim_val}") print(f"MS-SSIM values: {ms_ssim_val}") # Using SSIM/MS_SSIM as a loss function (returns scalar mean loss) # For loss, set size_average=True and typically use 1 - score ssim_loss_module = SSIM(data_range=255, size_average=True, channel=3) ms_ssim_loss_module = MS_SSIM(data_range=255, size_average=True, channel=3) ssim_loss = 1 - ssim_loss_module(X, Y) # A scalar tensor ms_ssim_loss = 1 - ms_ssim_loss_module(X, Y) # A scalar tensor print(f"SSIM Loss: {ssim_loss}") print(f"MS-SSIM Loss: {ms_ssim_loss}")
Debug
Known issues
gotchaInput 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`.
fix
Ensure input tensors `X` and `Y` contain pixel values within `[0, data_range]`.
affects: All versions
gotchaThe `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.
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.
affects: All versions
gotchaInput 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.
fix
For a single image, add a batch dimension: `image.unsqueeze(0)` to make it `(1, C, H, W)`.
affects: All versions
gotchaWhen 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.
fix
Initialize `MS_SSIM(..., normalize='relu')` when using it as a loss in training.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'msssim'
The user is attempting to import the library using 'msssim', but the correct package name for import is 'pytorch_msssim'.
fix
from pytorch_msssim import ssim, ms_ssim
AssertionError: Expected 4D tensor as input, got 3D tensor.
The 'ssim' or 'ms_ssim' function requires input tensors to be 4-dimensional (batch, channels, height, width), but a tensor with fewer dimensions was provided.
fix
Reshape the input tensor to add a batch dimension, typically using `tensor.unsqueeze(0)`. For example: `ssim(img1.unsqueeze(0), img2.unsqueeze(0))`.
RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!
The input tensors (img1 and img2) are located on different compute devices (e.g., one on CPU and one on GPU), which is not allowed for PyTorch operations.
fix
Move both tensors to the same device using `.to(device)`. Example: `device = torch.device('cuda' if torch.cuda.is_available() else 'cpu'); img1 = img1.to(device); img2 = img2.to(device)`.
Upgrade
Version history
1.0.0latest on PyPI · released May 25, 2023
Audit
Dependencies
torchrequiredCore PyTorch library for tensor operations and deep learning framework.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
pytorch-msssim — pip install pytorch-msssim · libregistry