ssim.js

What is ssim.js?

The ssim.js npm package is used for calculating the Structural Similarity Index (SSIM) between two images. SSIM is a method for measuring the similarity between two images, which is often used in the context of image quality assessment.

What are ssim.js's main functionalities?

Calculate SSIM between two images

This feature allows you to calculate the SSIM between two images. The `compare` function takes the paths to two images and returns a promise that resolves with the SSIM value.

const ssim = require('ssim.js');
const img1 = 'path/to/image1.png';
const img2 = 'path/to/image2.png';

ssim.compare(img1, img2).then(result => {
  console.log('SSIM:', result.ssim);
}).catch(err => {
  console.error(err);
});

Calculate SSIM for image buffers

This feature allows you to calculate the SSIM between two image buffers. The `compare` function can also take image buffers as input and returns a promise that resolves with the SSIM value.

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

const img1Buffer = fs.readFileSync('path/to/image1.png');
const img2Buffer = fs.readFileSync('path/to/image2.png');

ssim.compare(img1Buffer, img2Buffer).then(result => {
  console.log('SSIM:', result.ssim);
}).catch(err => {
  console.error(err);
});

Other packages similar to ssim.js

image-ssim

The image-ssim package is another library for calculating the Structural Similarity Index (SSIM) between two images. It provides similar functionality to ssim.js but may have different performance characteristics and API design.

sharp

The sharp package is a high-performance image processing library. While its primary focus is on image transformations (resizing, cropping, etc.), it also includes functionality for comparing images, including SSIM calculations. Sharp is known for its speed and efficiency.

gm

The gm (GraphicsMagick) package is a Node.js wrapper for the GraphicsMagick and ImageMagick tools. It provides a wide range of image processing capabilities, including image comparison and SSIM calculations. It is a more comprehensive tool for image manipulation compared to ssim.js.

README

Process	Status
Build Status
Code Coverage
Code Quality
Commit format
Dependencies
Environments
Documentation

SSIM.JS

SSIM.JS is a pure JavaScript implementation of the multiple SSIM algorithms published by Wang, et al. 2004 on "Image Quality Assessment: From Error Visibility to Structural Similarity".

For a general overview on SSIM check the Wikipedia article here.

This code is a line-by-line port of the original Matlab scripts, they are available here with their datasets.

Validation of results has been done against the results from the Matlab scripts, compared with the javascript implementation and they match the original results with increased resolution (10^-7 instead of 10^-5)

Installation

npm install ssim.js

If you run into any issues during the installation, check the node-canvas installation steps.

Usage

import ssim from 'ssim.js';

ssim('./img1.jpg', './img2.jpg')
	.then(out => console.log(`SSIM: ${out}`))
	.catch(err => console.error('Error generating SSIM', err));

SSIM

The script generates a 2D SSIM map between two windows x and y as follows:

where:

• μ is used to indicate the averages
• σ is used to indicate the variance and covariance (of xy)
• c1 and c2 are small constants added to prevent inestability when μx^2 + μy^2 ≈ 0

Parameters

You can pass a 3rd parameter containing a plain object and any of the following options:

Parameter	Default
windowSize	11
k1	0.01
k2	0.03
bitDepth	8
downsample	true

Output

The program returns a SSIM map, a mean SSIM (MSSIM) and a performance metric (ms to compute). The MSSIM returned value is computed by averaging all SSIM values from the map.

Rationale

The goal of this project is to implement a fully-tested, exact reproduction of the original Matlab scripts to compute SSIM. It also needs to be easy to use, performant and work in as many environments as reasonably possible:

• Isomorphic build (node / browser)
• Reproduction of the original Matlab scripts with a resolution of 10^-7 (±0.0000001)
• Appropriate testing to ensure correct behavior
• Validate results against original datasets

Caveats

• Because of this projects reliance on node-canvas you may run into installation difficulties. Make sure you follow the steps for your platform here.
• When using canvas or node-canvas, images will be retrieved as 8 bits/channel. You can use the bitDepth parameter to modify how SSIM computes the value but it will have no effect on how the image is read.

Roadmap

• Validation of results based on original IVC database.
• Add support for MS-SSIM from Wang, Simoncelli & Bovik, 2003 on "Multi-Scale Structural Similarity for Image Quality Assessment",
• Add support for IW-SSIM from Wang & Qiang, 2011 on "Information Content Weighting for Perceptual Image Quality Assessment".
• Potentially adding support 3-SSIM and 3-MS-SSIM for Li & Bovik, 2008 on "Three-Component Weighted Structural Similarity Index"
• Multiple builds, something like:
  • mx as an isomorphic build (works on node and on the browser) with no external dependencies that takes 3D matrices as input representing the images.
  • node as a node-specific build that uses node-canvas to retrieve the 3D pixel matrix from each image and accepts Buffer, URLs or a file system path as inputs.
  • web as a browser-specific build that relies on the canvas element to retrieve the pixel matrices. It accepts URLs but it's subject to CORS restrictions.
• α, β and γ are currently excluded (default to 1). Parametrize.