@blazediff/gmsd
High-performance GMSD (Gradient Magnitude Similarity Deviation) perceptual image quality metric. Structure-aware similarity scoring using Prewitt gradients on luma channel.
Installation
npm install @blazediff/gmsd
API
gmsd(a, b, options?)
Compares two RGBA images of the same size and returns a GMSD score.
interface Image {
data: Uint8Array | Uint8ClampedArray; // RGBA, width * height * 4 bytes. Buffer works too.
width: number;
height: number;
}
type GmsdResult =
| { kind: "compared"; score: number } // 0 when identical, higher is more different (typically 0-0.35)
| { kind: "dimension-mismatch"; a: Size; b: Size };
Images of different sizes return kind: "dimension-mismatch". A buffer that does not hold width * height * 4 bytes, or an output of the wrong size, throws.
| Option | Type | Default | Description | Hint |
|---|---|---|---|---|
downsample |
0 | 1 | 0 | Downsampling factor | 0 = full resolution, 1 = 2x downsample (faster, slight accuracy loss) |
c |
number | 170 | Stability constant | Prevents division by zero. 170 is from original MATLAB implementation for 8-bit images |
output |
Image | none | Draws the gradient similarity map | White is identical gradient structure, black is different, gray is partial similarity |
Usage
import { gmsd } from '@blazediff/gmsd';
const result = gmsd(image1, image2, { downsample: 0, c: 170 });
// Lower score = better quality (0 = perfect match)
if (result.kind === 'compared') console.log(`GMSD score: ${result.score.toFixed(4)}`);
// With the GMS map drawn into an RGBA buffer
const output = { data: new Uint8ClampedArray(width * height * 4), width, height };
gmsd(image1, image2, { output });
Migrating from 1.x
| 1.x | Now |
|---|---|
gmsd(a.data, b.data, out, width, height, options) | gmsd(a, b, { ...options, output: { data: out, width, height } }) |
returns number | returns { kind: "compared", score } |
| grayscale input (1 byte per pixel) | RGBA input only |
References
Based on the paper:
Xue, W., Zhang, L., Mou, X., & Bovik, A. C. (2013). "Gradient Magnitude Similarity Deviation: A Highly Efficient Perceptual Image Quality Index." IEEE Transactions on Image Processing, 22(2), 684-695.