@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

Gradient-based - Measures structural similarity via gradient magnitudes, tolerant to compression artifacts
GMS map output - Optional grayscale visualization of gradient similarity

Mathematical details (FORMULA.md)

API Reference

`gmsd(a, b, options?)`

Compares two RGBA images of the same size with the GMSD metric. a and b are { data, width, height }.


import gmsd from "@blazediff/gmsd";
 
const output = { data: new Uint8ClampedArray(width * height * 4), width, height };
const result = gmsd(a, b, { output });
 
if (result.kind === "compared") console.log(result.score);

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)
`output`	`Image`	-	Draws the GMS map as grayscale

Returns

{ kind: "compared", score }, or { kind: "dimension-mismatch", a, b } when the sizes differ. score is a 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)

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

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