Usage

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

const { mssim, ssim_map, performance } = ssim(imgBuffer1, imgBuffer2, options)

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
imgBuffer1	String	yes	Buffer of the first image
imgBuffer2	String	yes	Buffer of the second image
options	Object	no	See Options

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

import ssim from 'ssim.js';

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

Output

The returned value is an object that contains the mean ssim value (mssim), the time needed to 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';

try {
  const out = ssim('./img1.jpg', './img2.jpg')
  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 comparison 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	'weber'	'original' / 'fast' / 'bezkrovny' / 'weber'

• 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 3 ssim options:
  • 'original': Uses a line-by-line port of the Matlab scripts and attempts to match them as closely as possible
  • 'fast': Uses a mathematically equivalent approach to 'original' but it's computationally faster.
  • 'bezkrovny': Uses a faster approach that similarly correlates with SSIM but doesn't match the original results exactly.
  • 'weber': (default) Is the fastest approach. Similar to Bezkrovny's, the results are close to but don't match the original SSIM results.