Image SSIM

Common errors

• Error: Images must have identical dimensions for SSIM calculation.

  cause Attempting to calculate SSIM between two images that do not have the same width and height. The SSIM algorithm requires pixel-by-pixel correspondence.
  fix Ensure both input `ImageData` objects have identical `width` and `height` properties before calling `ssim`. Resize one or both images if necessary, although resizing can introduce its own artifacts that affect SSIM.

• TypeError: Cannot read properties of undefined (reading 'data') or other properties of ImageData.

  cause The `ssim` function was called with an argument that is not an `ImageData`-like object, meaning it lacks `data`, `width`, or `height` properties, or `data` is not a `Uint8ClampedArray` (or `Uint8Array`).
  fix Verify that both arguments passed to `ssim` are valid `ImageData` objects or objects structurally identical to `ImageData`, specifically having `data: Uint8ClampedArray`, `width: number`, and `height: number` properties.

Warnings

• gotcha The package is currently at version 0.2.0. While functional, pre-1.0.0 versions may introduce breaking API changes in minor releases without strict adherence to semantic versioning, although this package has been stable for a long time.
  Fix: Always pin to an exact version or use a lockfile to ensure stability in production environments. Review the GitHub repository for any recent activity or unreleased changes.
• gotcha The `ssim` function expects image data in a specific `ImageData`-like format (an object with `data: Uint8ClampedArray`, `width: number`, `height: number`). Providing malformed or incorrect data structures will lead to errors or inaccurate results.
  Fix: Ensure input images are properly pre-processed into `ImageData` objects or objects mimicking its structure, especially if handling images from different sources (e.g., Node.js buffers vs. browser canvas data).
• gotcha SSIM is primarily defined for grayscale images. When comparing color images, this implementation (and many others) implicitly convert to grayscale or process channels independently. This can lead to SSIM values that may not perfectly reflect human perception of color differences, and some SSIM variants are not rotationally symmetric.
  Fix: Be aware that SSIM might not capture all aspects of perceived quality for color images. For critical applications, consider explicitly converting images to a luminance channel before calculation or exploring more advanced multi-scale or color-aware image quality metrics like MS-SSIM or DSSIM for improved perceptual accuracy.
• gotcha The SSIM algorithm can be computationally intensive, especially for large images or if performed frequently. Performance can vary significantly between environments (browser vs. Node.js) and hardware.
  Fix: For performance-critical applications, consider downsampling images before SSIM calculation, optimizing the image loading/processing pipeline, or offloading calculations to Web Workers in the browser or separate processes in Node.js. Benchmarking with representative image sizes is recommended.
• gotcha Many SSIM implementations exist, and their results can vary due to subtle differences in parameters, color space handling, and internal calculations. Comparing SSIM values from different libraries directly might not yield consistent results.
  Fix: If comparing results with other SSIM tools or research papers, verify the specific algorithm, parameters (e.g., window size, constants), and color space conversion used by each implementation. Consistency is best achieved by using the same library throughout your project.

Install

• npm install image-ssim npm
• yarn add image-ssim yarn
• pnpm add image-ssim pnpm

Imports

• ssim
  wrong:

  import ssim from 'image-ssim';

  correct:

  import { ssim } from 'image-ssim';

  The primary SSIM calculation function is a named export.
• ssim
  wrong:

  const ssim = require('image-ssim');

  correct:

  const { ssim } = require('image-ssim');

  CommonJS `require` for Node.js environments. The module exports a named `ssim` function.

Quickstart

Demonstrates how to calculate the SSIM between two mock ImageData objects, including a case for identical images and a case for differing images, and handles dimension mismatch.

import { ssim } from 'image-ssim';

// Helper to create a mock ImageData object for demonstration
const createMockImageData = (width: number, height: number, fillValue: number): ImageData => {
  const data = new Uint8ClampedArray(width * height * 4);
  for (let i = 0; i < data.length; i += 4) {
    data[i] = fillValue;     // Red
    data[i + 1] = fillValue; // Green
    data[i + 2] = fillValue; // Blue
    data[i + 3] = 255;       // Alpha
  }
  return { data, width, height };
};

const width = 100;
const height = 100;

// Create two identical images
const imageA = createMockImageData(width, height, 128);
const imageB = createMockImageData(width, height, 128);

// Create a slightly different image
const imageC = createMockImageData(width, height, 138);

// Calculate SSIM between identical images (should be close to 1)
const ssimValueAB = ssim(imageA, imageB);
console.log(`SSIM (Image A vs B - identical): ${ssimValueAB}`);

// Calculate SSIM between different images
const ssimValueAC = ssim(imageA, imageC);
console.log(`SSIM (Image A vs C - different): ${ssimValueAC}`);

// Example with different dimensions (will throw an error if not handled)
try {
  const imageD = createMockImageData(50, 50, 128);
  ssim(imageA, imageD);
} catch (e: any) {
  console.error(`Error with different dimensions: ${e.message}`);
}