Usage

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.