SSIM.JS Image Similarity

Common errors

• TypeError: Cannot read properties of undefined (reading 'width')

  cause The input images passed to `ssim()` are not valid `ImageData` objects or compatible structures, likely missing `width` or `height` properties, or being `null`/`undefined`.
  fix Ensure `ssim()` receives correctly formatted image data. In Node.js, use a library like `canvas` to load and process image files into `ImageData` objects. In browsers, use `context.getImageData()`.

• Error: Cannot find module 'ssim.js'

  cause The `ssim.js` package has not been installed or the import path is incorrect.
  fix Run `npm install ssim.js` or `yarn add ssim.js`. Verify the import statement `import ssim from 'ssim.js';` for ESM or `const ssim = require('ssim.js');` for CommonJS.

Warnings

• gotcha ssim.js expects raw image pixel data, typically as an `ImageData` object (in browsers) or a compatible buffer structure (in Node.js). Directly passing file paths or `Buffer` objects from file reads will not work without pre-processing the image into a pixel array format.
  Fix: Use a library like `canvas` (for Node.js) or browser `CanvasRenderingContext2D.getImageData()` to convert loaded images into `ImageData` objects or similar pixel arrays before passing them to `ssim()`.
• breaking Version 3.0.0 introduced Bezkrovny's SSIM algorithm as a feature. While not explicitly marked as a breaking change in the release notes, new algorithm implementations can sometimes subtly alter default behavior or results compared to previous versions, potentially affecting applications sensitive to exact SSIM scores.
  Fix: Review results for critical applications if upgrading from pre-3.0.0 versions to ensure consistent SSIM scores. If discrepancies are observed, check options to configure the specific algorithm or parameters being used.
• gotcha The performance of SSIM calculation can be significant for large images, especially in JavaScript environments. The `performance` property in the result object indicates the computation time.
  Fix: Consider pre-scaling images down before SSIM calculation if exact pixel-level detail is not critical, or perform calculations in a web worker or background thread to avoid blocking the main thread in browser environments.

Install

• npm install ssim.js npm
• yarn add ssim.js yarn
• pnpm add ssim.js pnpm

Imports

• ssim
  wrong:

  import { ssim } from 'ssim.js';

  correct:

  import ssim from 'ssim.js';

  The primary SSIM function is a default export, not a named export. This applies to both ESM and TypeScript.
• ssim
  wrong:

  const { ssim } = require('ssim.js');

  correct:

  const ssim = require('ssim.js');

  For CommonJS, the main ssim function is accessed directly from the `require` call, as it's a default export.
• SSIMResult

  import type { SSIMResult } from 'ssim.js';

  TypeScript users can import the `SSIMResult` type for type-checking the return value of the `ssim` function, which includes `mssim` and `performance`.

Quickstart

This quickstart demonstrates how to load two image files (using `@napi-rs/canvas` or `canvas` in Node.js, or browser APIs) and compute their SSIM score, printing the result to the console. It includes error handling and a basic interpretation of the SSIM score.

import { createCanvas, loadImage } from 'canvas';
import ssim from 'ssim.js';
import { readFileSync } from 'fs';

// Load images (replace with actual image paths or buffers)
// In a browser, loadImage would be from the DOM, e.g., an <img> element.
// For Node.js, we simulate with `canvas` library or direct buffer.

async function compareImages() {
  try {
    // For this example, we create dummy images or load from disk.
    // In a real scenario, these would be actual image buffers/data.
    const imgBuffer1 = readFileSync('./image1.png'); // Ensure you have image1.png and image2.png
    const imgBuffer2 = readFileSync('./image2.png');

    const image1 = await loadImage(imgBuffer1);
    const image2 = await loadImage(imgBuffer2);

    // ssim.js expects image data in a specific format (e.g., ImageData or a compatible buffer).
    // Here we convert the loaded image to a format ssim.js can process.
    // The `canvas` library helps create a compatible buffer.
    const canvas1 = createCanvas(image1.width, image1.height);
    const ctx1 = canvas1.getContext('2d');
    ctx1.drawImage(image1, 0, 0, image1.width, image1.height);
    const imageData1 = ctx1.getImageData(0, 0, image1.width, image1.height);

    const canvas2 = createCanvas(image2.width, image2.height);
    const ctx2 = canvas2.getContext('2d');
    ctx2.drawImage(image2, 0, 0, image2.width, image2.height);
    const imageData2 = ctx2.getImageData(0, 0, image2.width, image2.height);

    const { mssim, performance } = ssim(imageData1, imageData2);

    console.log(`Structural Similarity (MSSIM): ${mssim}`);
    console.log(`Calculation Performance: ${performance}ms`);
    if (mssim > 0.95) {
      console.log('The images are very similar.');
    } else {
      console.log('The images show significant differences.');
    }
  } catch (error) {
    console.error('Error comparing images:', error);
    console.log('Please ensure you have two image files (e.g., image1.png, image2.png) in the same directory and have installed `canvas` (`npm install canvas`).');
  }
}

compareImages();