@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/ssimFeatures
- 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
SSIM
ssim(image1, image2, output, width, height, options?)
Compares two images using standard SSIM metric and returns a similarity score.
Parameters
| Parameter | Type | Description |
|---|---|---|
image1 | Buffer, Uint8Array, or Uint8ClampedArray | Image data of the first image |
image2 | Buffer, Uint8Array, or Uint8ClampedArray | Image data of the second image |
output | Buffer, Uint8Array, Uint8ClampedArray, or undefined | Optional output buffer for SSIM map visualization |
width | number | Width of the images in pixels |
height | number | Height of the images in pixels |
options | SsimOptions | Comparison options (optional) |
Options
| Option | Type | Default | Description |
|---|---|---|---|
windowSize | number | 11 | Size of the Gaussian window |
k1 | number | 0.01 | Algorithm parameter for luminance |
k2 | number | 0.03 | Algorithm parameter for contrast |
L | number | 255 | Dynamic range of pixel values |
Returns
number - SSIM score between 0 and 1
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 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,
});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-poolingLinks
- 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 →
Last updated on