{"id":14935,"library":"ssim.js","title":"SSIM.JS Image Similarity","description":"ssim.js is a JavaScript library that provides an implementation of the Structural Similarity Index (SSIM) algorithm, which measures the perceived similarity between two images. Unlike traditional metrics like PSNR or MSE, SSIM correlates more closely with human visual perception, yielding a score between 0 and 1, where 1 indicates perfect similarity. The library also supports MSSIM (Multi-scale SSIM) and can generate SSIM maps. The current stable version is 3.5.0, with releases occurring infrequently, often several months apart, as seen from the recent release history. Its key differentiator is providing a readily available, pure JavaScript SSIM implementation suitable for both Node.js and browser environments, often used in image processing, quality assessment, and content-based image retrieval applications.","status":"active","version":"3.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/obartra/ssim","tags":["javascript","ssim","mssim","ssim_map","image","compare","structural","similarity","processing","typescript"],"install":[{"cmd":"npm install ssim.js","lang":"bash","label":"npm"},{"cmd":"yarn add ssim.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add ssim.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary SSIM function is a default export, not a named export. This applies to both ESM and TypeScript.","wrong":"import { ssim } from 'ssim.js';","symbol":"ssim","correct":"import ssim from 'ssim.js';"},{"note":"For CommonJS, the main ssim function is accessed directly from the `require` call, as it's a default export.","wrong":"const { ssim } = require('ssim.js');","symbol":"ssim","correct":"const ssim = require('ssim.js');"},{"note":"TypeScript users can import the `SSIMResult` type for type-checking the return value of the `ssim` function, which includes `mssim` and `performance`.","symbol":"SSIMResult","correct":"import type { SSIMResult } from 'ssim.js';"}],"quickstart":{"code":"import { createCanvas, loadImage } from 'canvas';\nimport ssim from 'ssim.js';\nimport { readFileSync } from 'fs';\n\n// Load images (replace with actual image paths or buffers)\n// In a browser, loadImage would be from the DOM, e.g., an <img> element.\n// For Node.js, we simulate with `canvas` library or direct buffer.\n\nasync function compareImages() {\n  try {\n    // For this example, we create dummy images or load from disk.\n    // In a real scenario, these would be actual image buffers/data.\n    const imgBuffer1 = readFileSync('./image1.png'); // Ensure you have image1.png and image2.png\n    const imgBuffer2 = readFileSync('./image2.png');\n\n    const image1 = await loadImage(imgBuffer1);\n    const image2 = await loadImage(imgBuffer2);\n\n    // ssim.js expects image data in a specific format (e.g., ImageData or a compatible buffer).\n    // Here we convert the loaded image to a format ssim.js can process.\n    // The `canvas` library helps create a compatible buffer.\n    const canvas1 = createCanvas(image1.width, image1.height);\n    const ctx1 = canvas1.getContext('2d');\n    ctx1.drawImage(image1, 0, 0, image1.width, image1.height);\n    const imageData1 = ctx1.getImageData(0, 0, image1.width, image1.height);\n\n    const canvas2 = createCanvas(image2.width, image2.height);\n    const ctx2 = canvas2.getContext('2d');\n    ctx2.drawImage(image2, 0, 0, image2.width, image2.height);\n    const imageData2 = ctx2.getImageData(0, 0, image2.width, image2.height);\n\n    const { mssim, performance } = ssim(imageData1, imageData2);\n\n    console.log(`Structural Similarity (MSSIM): ${mssim}`);\n    console.log(`Calculation Performance: ${performance}ms`);\n    if (mssim > 0.95) {\n      console.log('The images are very similar.');\n    } else {\n      console.log('The images show significant differences.');\n    }\n  } catch (error) {\n    console.error('Error comparing images:', error);\n    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`).');\n  }\n}\n\ncompareImages();","lang":"typescript","description":"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."},"warnings":[{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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()`.","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`.","error":"TypeError: Cannot read properties of undefined (reading 'width')"},{"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.","cause":"The `ssim.js` package has not been installed or the import path is incorrect.","error":"Error: Cannot find module 'ssim.js'"}],"ecosystem":"npm"}