@blazediff/ssim

Fast SSIM (Structural Similarity Index) implementations for perceptual image quality assessment. Includes standard SSIM, MS-SSIM (Multi-Scale SSIM), and Hitchhiker’s SSIM for various use cases and performance requirements.

Installation


npm install @blazediff/ssim


pnpm add @blazediff/ssim


yarn add @blazediff/ssim


bun add @blazediff/ssim

Features

Three variants - Standard SSIM, MS-SSIM, and Hitchhiker’s SSIM (~4x faster)
MATLAB-compatible - Standard SSIM matches reference implementation with <0.01% error
SSIM map output - Optional grayscale visualization of similarity

API Reference

All three functions take two images of the same size and one options object, and return a result object:


interface Image {
  data: Uint8Array | Uint8ClampedArray; // RGBA, width * height * 4 bytes. Buffer works too.
  width: number;
  height: number;
}
 
type SsimResult =
  | { kind: "compared"; score: number } // 0-1, 1 when identical
  | { kind: "dimension-mismatch"; a: Size; b: Size };

Function	Description
`ssim(a, b, options?)`	Standard SSIM with a Gaussian window and automatic downsampling to about 256px on the short edge, like MATLAB’s `ssim.m`
`msssim(a, b, options?)`	SSIM pooled across a dyadic pyramid, like `msssim.m`. The default five scales need at least 176px on the short edge
`hitchhikersSSIM(a, b, options?)`	Box windows over integral images, pooled by coefficient of variation. About 4x faster than standard SSIM, using integral images for O(1) window computation

A buffer that does not hold width * height * 4 bytes, or an output of the wrong size, throws.

Options

SsimOptions is one type for all three functions, with the field names of @blazediff/ssim-native. Each function reads the shared fields and its own block.

Option	Type	Default	Description
`windowSize`	`number`	`11`	Side of the local window
`k1`	`number`	`0.01`	Luminance stability constant
`k2`	`number`	`0.03`	Contrast stability constant
`bitDepth`	`number`	`8`	Sample bit depth, setting `L = 2^bitDepth - 1`
`output`	`Image`	-	Draws the local score map as grayscale
`msSsim.weights`	`number[]`	`[0.0448, 0.2856, 0.3001, 0.2363, 0.1333]`	`msssim` only. Per-scale weights. The length sets the number of scales
`msSsim.method`	`"product" \| "weighted-sum"`	`"product"`	`msssim` only. How the per-scale scores combine
`hitchhikers.windowStride`	`number`	`windowSize`	`hitchhikersSSIM` only. Distance between window origins
`hitchhikers.covPooling`	`boolean`	`true`	`hitchhikersSSIM` only. Coefficient of Variation pooling (recommended)

Score Interpretation

Score Range	Similarity Level	Description
`1.0`	Identical	Images are identical or perceptually identical
`0.99+`	Excellent	Extremely high similarity (minor compression artifacts)
`0.95-0.99`	Very Good	High similarity (small compression or noise)
`0.90-0.95`	Good	Noticeable but acceptable differences
`0.80-0.90`	Fair	Significant but tolerable differences
`<0.80`	Poor	Major structural differences

Threshold Guidelines: - Use threshold >0.99 for strict visual regression testing - Use threshold >0.95 for standard visual regression testing - Scores below 0.90 indicate substantial visual differences

Usage Examples

SSIM


import ssim from "@blazediff/ssim/ssim";
 
// Basic usage
const result = ssim(img1, img2);
if (result.kind === "compared") console.log(result.score);
 
// With SSIM map output
const output = { data: new Uint8ClampedArray(width * height * 4), width, height };
ssim(img1, img2, { output });
 
// With custom options
ssim(img1, img2, { windowSize: 8, k1: 0.01, k2: 0.03 });

MS-SSIM


import msssim from "@blazediff/ssim/msssim";
 
// Basic usage
const result = msssim(img1, img2);
 
// With SSIM map at finest scale
const output = { data: new Uint8ClampedArray(width * height * 4), width, height };
msssim(img1, img2, { output });
 
// Three scales with custom weights, combined as a weighted sum
msssim(img1, img2, {
  msSsim: { weights: [0.33, 0.33, 0.34], method: "weighted-sum" },
});

Hitchhiker’s SSIM


import hitchhikersSSIM from "@blazediff/ssim/hitchhikers-ssim";
 
// Basic usage with CoV pooling (recommended)
const result = hitchhikersSSIM(img1, img2);
 
// With mean pooling (traditional)
hitchhikersSSIM(img1, img2, { hitchhikers: { covPooling: false } });
 
// With custom window and stride
hitchhikersSSIM(img1, img2, {
  windowSize: 16,
  hitchhikers: { windowStride: 8, covPooling: true }, // Overlapping windows
});

CLI Usage

All three variants are available via the @blazediff/cli CLI:


# Standard SSIM
blazediff-cli ssim image1.png image2.png
 
# MS-SSIM
blazediff-cli msssim image1.png image2.png
 
# Hitchhiker's SSIM
blazediff-cli hitchhikers-ssim image1.png image2.png
 
# With options
blazediff-cli hitchhikers-ssim image1.png image2.png --window-size 16 --no-cov-pooling