@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 SSIM Variants - Standard SSIM, MS-SSIM, and Hitchhiker’s SSIM
• Perceptual metric - Measures structural similarity, not just pixel differences
• MATLAB-compatible - Matches reference implementation with <0.01% error
• High performance - Optimized implementations with ~4x faster Hitchhiker’s SSIM
• SSIM map output - Optional grayscale visualization of similarity
• TypeScript support out of the box

What is SSIM?

SSIM (Structural Similarity Index) is a perceptual image quality metric that:

• Measures structural similarity between images (luminance, contrast, structure)
• Returns a score from 0 to 1 (1 = identical, 0 = completely different)
• Correlates better with human perception than MSE or PSNR
• Is widely used in image/video quality assessment

Variants

• SSIM - Standard Gaussian-based implementation, MATLAB-compatible
• MS-SSIM - Multi-scale version for better perceptual correlation
• Hitchhiker’s SSIM - Fast rectangular-window version using integral images (~4x faster)

For detailed mathematical explanation, see the package documentation .

API Reference

Score Interpretation

Usage Examples

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

import msssim from "@blazediff/ssim/msssim";
 
// Basic usage
const score = msssim(img1.data, img2.data, undefined, width, height);
 
// With SSIM map at finest scale
const output = new Uint8ClampedArray(width * height * 4);
const score = msssim(img1.data, img2.data, output, width, height);
 
// With custom scales and weights
const score = msssim(img1.data, img2.data, undefined, width, height, {
  scales: 3,
  weights: [0.33, 0.33, 0.34],
  method: "sum",
});

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

When to Use Each Variant

Use SSIM when:

• You need MATLAB-compatible results for research or comparison
• You want high accuracy with Gaussian weighting
• You need automatic downsampling for large images
• Performance is not critical

Use MS-SSIM when:

• You need multi-scale analysis for better perceptual correlation
• You’re working with images at different resolutions
• You want better correlation with human perception
• You can afford the ~2-3x computation cost

Use Hitchhiker’s SSIM when:

• You need maximum performance (~4x faster than standard SSIM)
• You’re processing large images or many images
• You want O(1) window computation regardless of window size
• You need flexible window stride for overlapping/non-overlapping windows
• CoV pooling provides better perceptual correlation than mean

CLI Usage

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

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

Links

• GitHub Repository 
• NPM Package 
• SSIM Paper  - Wang et al. (2004)
• MS-SSIM Paper  - Wang et al. (2003)
• Hitchhiker’s SSIM Paper  - Venkataramanan et al. (2021)
• Examples →