Fast single-threaded GMSD (Gradient Magnitude Similarity Deviation) metric for CI visual testing
npm install @blazediff/gmsd
High-performance GMSD (Gradient Magnitude Similarity Deviation) perceptual image quality metric. Structure-aware similarity scoring using Prewitt gradients on luma channel.
``bash`
npm install @blazediff/gmsd
Compare two images using GMSD perceptual similarity metric and return a similarity score.
| Parameter | Type | Description |
|---|---|---|
image1 | Uint8Array | Uint8ClampedArray | First image data (RGBA or grayscale) |
image2 | Uint8Array | Uint8ClampedArray | Second image data (RGBA or grayscale) |
output | Uint8Array | Uint8ClampedArray | undefined | Optional output buffer for GMS similarity map visualization |
width | number | Image width in pixels |
height | number | Image height in pixels |
options | object | GMSD options (optional) |
Returns: GMSD score where 0 = identical, higher values = more differences (typically 0-0.35 range)
| 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 |
`typescript
import { gmsd } from '@blazediff/gmsd';
// Basic comparison
const score = gmsd(
image1.data,
image2.data,
undefined,
width,
height,
{
downsample: 0,
c: 170,
}
);
// Lower score = better quality (0 = perfect match)
console.log(GMSD score: ${score.toFixed(4)});
// With GMS map output for visualization
const output = new Uint8ClampedArray(width height 4);
const score = gmsd(
image1.data,
image2.data,
output, // Will be filled with grayscale similarity map
width,
height,
{}
);
// output now contains:
// - White pixels (255): identical gradient structure
// - Black pixels (0): different gradient structure
// - Gray shades: partial similarity
``
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.
- Original MATLAB implementation
- Mathematical formula verification