Registry / ai-ml / ssim.js

ssim.js

JSON →
library3.5.0jsnpmunverified

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.

npm install ssim.js
INSTALL
IMPORT
SIG · SSIM.JS
S
ssim.js
ai-mljavascriptv3.5.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ssim
✓ import ssim from 'ssim.js';
✗ 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
✓ const ssim = require('ssim.js');
✗ 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`.

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();
Debug
Known issues
gotchassim.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()`.
affects: >=1.0.0
breakingVersion 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.
affects: >=3.0.0
gotchaThe 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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'width')
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'
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.
Upgrade
Version history
3.5.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
20
OpenAI (training)
1
Resources
ssim.js — npm install ssim.js · libregistry