ssim_raster: SSIM index for raster images

In SSIMmap: The Structural Similarity Index Measure for Maps

SSIM index for raster images

Description

This function calculates the Structural Similarity Index Measure (SSIM) between two raster images. It can return either global SSIM summaries or local SSIM raster layers. Optional permutation-based statistical inference can also be performed for global or local SSIM values.

Usage

ssim_raster(
  map1,
  map2,
  global = TRUE,
  w = 1,
  transform = c("normal_score", "percentile", "none", "minmax"),
  k1 = NULL,
  k2 = NULL,
  do_test = FALSE,
  local_test = FALSE,
  R = 1000,
  fdr = TRUE,
  alpha = 0.05,
  seed = NULL
)

Arguments

map1	A single-layer terra::SpatRaster object representing the first raster map.
map2	A single-layer terra::SpatRaster object representing the second raster map.
global	Logical. If TRUE, the function returns global summary statistics of SSIM, SIM, SIV, and SIP. If FALSE, it returns local raster layers for each cell. Default is TRUE.
w	Integer. Radius of the local moving window used to calculate local SSIM components. For example, w = 1 uses a 3 x 3 window, and w = 2 uses a 5 x 5 window. Default is 1.
transform	Character. Transformation applied to both raster maps before SSIM calculation. Options are "normal_score", "percentile", "none", and "minmax". Default is "normal_score".
k1	Numeric. Constant used to stabilize the luminance component of SSIM. If NULL, the default value 0.01 is used.
k2	Numeric. Constant used to stabilize the contrast and structure components of SSIM. If NULL, the default value 0.03 is used.
do_test	Logical. If TRUE, a permutation-based statistical test is performed. Default is FALSE.
local_test	Logical. If TRUE and global = FALSE, local permutation tests are performed for each raster cell. If FALSE, local SSIM layers are returned without p-values. Default is FALSE.
R	Integer. Number of permutations used for statistical inference. Default is 1000.
fdr	Logical. If TRUE, p-values are adjusted using the Benjamini-Hochberg false discovery rate correction. Default is TRUE.
alpha	Numeric. Significance level used to determine significant SSIM values. Default is 0.05.
seed	Optional integer. Random seed used for permutation testing. Default is NULL.

Details

The SSIM index is calculated as the product of three components: similarity in mean intensity, similarity in variance, and similarity in spatial pattern. These components are returned as SIM, SIV, and SIP, respectively.

The local SSIM calculation uses a square moving window with size (2 * w + 1) x (2 * w + 1).

When do_test = TRUE, permutation testing is performed by randomly permuting the values of map2 over the overlapping non-NA cells and recalculating SSIM values.

Value

If global = TRUE and do_test = FALSE, a list containing a summary table of global SSIM, SIM, SIV, and SIP values is returned.

If global = TRUE and do_test = TRUE, a list containing the summary table, permutation null distributions, p-values, and optionally q-values is returned.

If global = FALSE and do_test = FALSE, a terra::SpatRaster object with four layers is returned: SSIM, SIM, SIV, and SIP.

If global = FALSE, do_test = TRUE, and local_test = TRUE, a terra::SpatRaster object is returned with local SSIM component layers, p-value layers, optionally q-value layers, and significance layers.

Examples

## Not run: 
library(terra)

# Global SSIM summary
g1 <- ssim_raster(
  map1,
  map2,
  global = TRUE,
  w = 1
)

# Local SSIM raster layers
l1 <- ssim_raster(
  map1,
  map2,
  global = FALSE,
  w = 1
)

# Local SSIM with permutation test
l2 <- ssim_raster(
  map1,
  map2,
  global = FALSE,
  w = 1,
  do_test = TRUE,
  local_test = TRUE,
  R = 999
)

## End(Not run)

SSIMmap documentation built on May 8, 2026, 1:07 a.m.