{"id":11076,"library":"image-ssim","title":"Image SSIM","description":"Image SSIM is a TypeScript/JavaScript library for calculating the Structural Similarity (SSIM) index between two images, suitable for both browser and server environments. This metric aims to quantify perceived image quality and similarity more effectively than traditional methods like PSNR or MSE, by focusing on structural information. Currently at version 0.2.0, this package is relatively stable for its core functionality, though its low version number suggests it may not receive frequent major feature updates or breaking changes typical of rapidly evolving libraries. Its key differentiator is providing a straightforward, cross-platform implementation of the SSIM algorithm, based on established references in the field. It is designed for developers needing a perceptual image comparison tool without heavy external dependencies. While the `npm` package `img-ssim` offers similar functionality, it uses image paths/URLs and callbacks, whereas `image-ssim` expects raw `ImageData`-like objects and returns a Promise or direct value, making `image-ssim` more suitable for in-memory image processing workflows.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/darosh/image-ssim-js","tags":["javascript","browser","compare","image","server","similarity","ssim","typescript"],"install":[{"cmd":"npm install image-ssim","lang":"bash","label":"npm"},{"cmd":"yarn add image-ssim","lang":"bash","label":"yarn"},{"cmd":"pnpm add image-ssim","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary SSIM calculation function is a named export.","wrong":"import ssim from 'image-ssim';","symbol":"ssim","correct":"import { ssim } from 'image-ssim';"},{"note":"CommonJS `require` for Node.js environments. The module exports a named `ssim` function.","wrong":"const ssim = require('image-ssim');","symbol":"ssim","correct":"const { ssim } = require('image-ssim');"}],"quickstart":{"code":"import { ssim } from 'image-ssim';\n\n// Helper to create a mock ImageData object for demonstration\nconst createMockImageData = (width: number, height: number, fillValue: number): ImageData => {\n  const data = new Uint8ClampedArray(width * height * 4);\n  for (let i = 0; i < data.length; i += 4) {\n    data[i] = fillValue;     // Red\n    data[i + 1] = fillValue; // Green\n    data[i + 2] = fillValue; // Blue\n    data[i + 3] = 255;       // Alpha\n  }\n  return { data, width, height };\n};\n\nconst width = 100;\nconst height = 100;\n\n// Create two identical images\nconst imageA = createMockImageData(width, height, 128);\nconst imageB = createMockImageData(width, height, 128);\n\n// Create a slightly different image\nconst imageC = createMockImageData(width, height, 138);\n\n// Calculate SSIM between identical images (should be close to 1)\nconst ssimValueAB = ssim(imageA, imageB);\nconsole.log(`SSIM (Image A vs B - identical): ${ssimValueAB}`);\n\n// Calculate SSIM between different images\nconst ssimValueAC = ssim(imageA, imageC);\nconsole.log(`SSIM (Image A vs C - different): ${ssimValueAC}`);\n\n// Example with different dimensions (will throw an error if not handled)\ntry {\n  const imageD = createMockImageData(50, 50, 128);\n  ssim(imageA, imageD);\n} catch (e: any) {\n  console.error(`Error with different dimensions: ${e.message}`);\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Images must have identical dimensions for SSIM calculation."},{"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.","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`).","error":"TypeError: Cannot read properties of undefined (reading 'data') or other properties of ImageData."}],"ecosystem":"npm"}