Skip to content
This repository has been archived by the owner on Dec 7, 2023. It is now read-only.
Oscar edited this page Dec 14, 2016 · 10 revisions

The API is the same on Node and on the browser:

ssim(img1, img2, options)
  .then({ mssim, ssim_map, performance })
  .catch(error);

For CLI specific usage, check the dedicated page here.

Input

ssim.js takes 2 paths to images and a 3rd optional parameter for additional options:

Parameter Type Required Browser Node
img1 String yes URL of the first image URL, Buffer or file path to the first image
img2 String yes URL of the second image URL, Buffer or file path to the second image
options Object no See Options See Options

If you want use the options parameter you could call ssim.js with:

import ssim from 'ssim.js';

ssim('./img1.jpg', './img2.jpg', { downsample: 'fast' })

Output

The returned value is a promise that resolves with the mean ssim value (mssim), the time needed to load the images and perform the computation (performance) and the ssim window matrix (ssim_map).

ssim_map matrix is of the form:

{
  data: Number[],
  width: Number,
  height: number
}

Where:

  • width and height determine the dimensions of the matrix
  • data holds the values at each position in row-major order

More succinctly:

Parameter Type Description
mssim Number Mean SSIM, the average of all ssim_map values
ssim_map Object The ssim value at each window
performance Number The total time to compute SSIM (in milliseconds)

Example

import ssim from 'ssim.js';

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

You can edit a similar node example here.

You can view a Node and Web SSIM comparision playground here.

Options

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

Parameter Default Description
windowSize 11 window size for the SSIM map
k1 0.01 The first stability constant
k2 0.03 The second stability constant
bitDepth 8 The number of bits used to encode each pixel
downsample 'original' false / 'original' / 'fast'
ssim 'fast' 'original' / 'fast'
  • Setting k1 or k2 to 0 will use UQI (Universal Quality Index) since it's a subset of SSIM (when C1 or C2 are 0)
  • When using 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
  • There are 3 downsample options:
    • false: disables downsizing
    • 'original': (default) implements the same downsizing than the original Matlab scripts
    • fast: relies on the canvas to do the downsizing (may lead to different results)
  • There are 2 ssim options:
    • 'original': Uses a line-by-line port of the Matlab scripts and attempts to match them as closely as possible
    • 'fast': (default) Uses a mathematically equivalent approach to 'original' but it's faster. By not focusing on a line-by-line port, it uses two 1-dimensional filters instead of a 2-D gaussian which results on a 2-3x performance improvement.

To view the steps taken to validate the results, check the wiki page here.

Clone this wiki locally