Implementation:Kornia Kornia SSIM Metric

Knowledge Sources	Kornia
Domains	Vision, Metrics
Last Updated	2026-02-09 15:00 GMT

Overview

Computes the Structural Similarity (SSIM) index map between two 2D images, measuring perceptual image quality based on luminance, contrast, and structure.

Description

The ssim function and SSIM module compute the Structural Similarity index between two images. The SSIM index is defined as:

SSIM(x, y) = (2 * mu_x * mu_y + C1)(2 * sigma_xy + C2) / ((mu_x^2 + mu_y^2 + C1)(sigma_x^2 + sigma_y^2 + C2))

where C1 = (0.01 * L)^2 and C2 = (0.03 * L)^2 are stabilization constants derived from the dynamic range L of the pixel values. Local statistics (means and variances) are computed using separable Gaussian filtering with a configurable window size and a fixed sigma of 1.5.

The implementation supports two padding modes: same (output has the same spatial dimensions as the input) and valid (output only covers the valid convolution area, matching the original MATLAB implementation). The result is a per-pixel SSIM map of shape (B, C, H, W), which can be averaged to obtain a scalar SSIM score.

Both a functional interface (ssim) and an nn.Module wrapper (SSIM) are provided.

Usage

Import this metric when evaluating perceptual image quality for tasks such as image super-resolution, denoising, compression, or any image-to-image translation task. SSIM is preferred over PSNR when a perceptually meaningful quality measure is needed.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/metrics/ssim.py
• Lines: 1-189

Signature

def ssim(
    img1: torch.Tensor,
    img2: torch.Tensor,
    window_size: int,
    max_val: float = 1.0,
    eps: float = 1e-12,
    padding: str = "same",
) -> torch.Tensor:

class SSIM(nn.Module):
    def __init__(
        self,
        window_size: int,
        max_val: float = 1.0,
        eps: float = 1e-12,
        padding: str = "same"
    ) -> None: ...
    def forward(self, img1: torch.Tensor, img2: torch.Tensor) -> torch.Tensor: ...

Import

from kornia.metrics import ssim, SSIM

I/O Contract

Inputs

Name	Type	Required	Description
img1	torch.Tensor	Yes	The first input image with shape (B, C, H, W).
img2	torch.Tensor	Yes	The second input image with shape (B, C, H, W). Must match img1 shape.
window_size	int	Yes	The size of the Gaussian kernel used to smooth the images for local statistics computation.
max_val	float	No	The dynamic range of the images. Defaults to 1.0.
eps	float	No	Small value for numerical stability when dividing. Defaults to 1e-12.
padding	str	No	same or valid. Controls whether the output has the same spatial size as input (same) or only covers valid convolution area (valid). Defaults to same.

Outputs

Name	Type	Description
ssim_map	torch.Tensor	The SSIM index map with shape (B, C, H, W) when padding is same, or smaller spatial dimensions when padding is valid. Values range from -1 to 1, where 1 indicates identical images.

Usage Examples

import torch
from kornia.metrics import ssim, SSIM

# Functional interface
input1 = torch.rand(1, 4, 5, 5)
input2 = torch.rand(1, 4, 5, 5)
ssim_map = ssim(input1, input2, window_size=5)  # shape: 1x4x5x5
mean_ssim = ssim_map.mean()

# Module interface
ssim_module = SSIM(window_size=5, max_val=1.0)
ssim_map = ssim_module(input1, input2)  # shape: 1x4x5x5

# Using valid padding (matches MATLAB SSIM)
ssim_map_valid = ssim(input1, input2, window_size=5, padding="valid")

Related Pages

• Principle:Kornia_Kornia_Image_Quality_Metrics