Implementation:Kornia Kornia SSIM3D 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 3D volumetric images, extending the standard SSIM metric to the spatial-depth dimension.

Description

The ssim3d function and SSIM3D module compute the Structural Similarity index between two 3D (volumetric) images. This is the three-dimensional extension of the standard SSIM metric, using the same formula:

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. Local statistics are computed using a 3D Gaussian kernel (via get_gaussian_kernel3d and filter3d) with a configurable window size and sigma of 1.5 in all three dimensions.

The implementation supports two padding modes: same (output retains the same spatial dimensions as the input) and valid (output covers only the valid 3D convolution area). Input tensors must have shape (B, C, D, H, W), where D is the depth dimension.

Both a functional interface (ssim3d) and an nn.Module wrapper (SSIM3D) are provided.

Usage

Import this metric when evaluating quality of 3D volumetric data such as medical imaging volumes (CT scans, MRI), video sequences treated as 3D volumes, or any task involving 3D image-to-image comparison.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/metrics/ssim3d.py
• Lines: 1-190

Signature

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

class SSIM3D(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 ssim3d, SSIM3D

I/O Contract

Inputs

Name	Type	Required	Description
img1	torch.Tensor	Yes	The first input 3D image with shape (B, C, D, H, W).
img2	torch.Tensor	Yes	The second input 3D image with shape (B, C, D, H, W). Must match img1 shape.
window_size	int	Yes	The size of the 3D Gaussian kernel used to smooth the images for local statistics computation. The kernel is cubic (window_size x window_size x window_size).
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 3D SSIM index map with shape (B, C, D, H, W) when padding is same, or smaller spatial dimensions when padding is valid. Values range from -1 to 1, where 1 indicates identical volumes.

Usage Examples

import torch
from kornia.metrics import ssim3d, SSIM3D

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

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

# Using valid padding
ssim_map_valid = ssim3d(input1, input2, window_size=5, padding="valid")

Related Pages

• Principle:Kornia_Kornia_Image_Quality_Metrics