@blazediff/gmsd

Fast single-threaded GMSD (Gradient Magnitude Similarity Deviation) metric for perceptual image quality assessment. Perfect for CI visual testing where you need a similarity score rather than pixel-by-pixel differences.

Installation


npm install @blazediff/gmsd


pnpm add @blazediff/gmsd


yarn add @blazediff/gmsd


bun add @blazediff/gmsd

Features

Perceptual metric - Measures gradient similarity, not just pixel differences
Similarity score - Returns 0-1 value (1 = identical, 0 = completely different)
Compression tolerant - Detects structural changes even with JPEG artifacts
Fast computation - Optimized single-threaded implementation for CI environments
GMS map output - Optional grayscale visualization of gradient similarity
TypeScript support out of the box

What is GMSD?

GMSD (Gradient Magnitude Similarity Deviation) is a perceptual image quality metric that:

Measures how similar gradient structures are between images
Returns a score from 0 to 1 (higher = more similar)
Is more tolerant to compression artifacts than pixel-by-pixel comparison
Detects structural and edge changes that are perceptually significant

For detailed mathematical explanation, see the GMSD package FORMULA.md .

API Reference

`gmsd(image1, image2, output, width, height, options?)`

Compares two images using GMSD 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 GMS map visualization
`width`	`number`	Width of the images in pixels
`height`	`number`	Height of the images in pixels
`options`	`GmsdOptions`	Comparison options (optional)

Options

Option	Type	Default	Description
`downsample`	`0` or `1`	`0`	Downsample factor (0 = no downsampling, 1 = half)
`c`	`number`	`170`	Constant for numerical stability (tuned for Prewitt)

Returns

number - Difference score between 0 and 1:

0.0 - Images are identical or perceptually identical
0.0-0.05 - Very low difference (minor compression artifacts)
0.05-0.15 - Low difference (noticeable but small changes)
0.15-0.35 - Moderate similarity (significant structural differences)
>0.35 - High difference (major differences)

Score Guidelines:

Use threshold >0.0 for strict regression testing
Use threshold >0.15 for loose regression testing with compression
Scores below 0.35 indicate substantial visual differences