@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(image1, image2, output, width, height, options)

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

Usage

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

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.