@4bitlabs/dct

Image structural similarity (SSIM) in ESM for browser/server with some performance improvements.

Adapted from darosh/image-ssim-js with some performance optimizations and usability changes.

Also see:

• https://github.com/ibezkrovnyi/image-quantization/blob/9f62/src/quality/ssim.ts
• https://github.com/rhys-e/structural-similarity
• http://en.wikipedia.org/wiki/Structural_similarity

Changes from the original

This implementation largely follows the original implementation, and does verify that it returns the same values for the same comparisons as the original. However, there are some significant changes to be aware of:

• Support for ImageData directly from HTML Canvas, without type-casting or reboxing.

  import { compare } from '@4bitlabs/ssim';
    
  const current = ctx.getImageData(0, 0, width, height)  
  const result = compare(source, current);

• options are now provided as an optional object, rather than positional arguments.

  compare(source, current, { luminance: false, windowSize: 16 })

• Added options to support to use float64 precision, instead of float32.

  compare(source, current, { precision: 'f64' })

• Dropped channels support, only supports 4-channel RGBA-formatted bytes. If you need this, use the reference implementation.

• Dropped bitsPerComponent support, only supports 8-bit components. If you need this, use the reference implementation.

Performance

The performance of compare() is ~2x better than the reference implementation for most use-cases. Mostly from avoiding Float32Array allocations and garbage collection inside hot-loops. Some of the function/callback mechanisms has been flattened—sacrificing some readability—to also reduce function overhead.

 ✓ src/image-ssim.bench.ts 12028ms
     name             hz     min     max    mean     p75     p99    p995    p999     rme  samples
   · baseline     538.35  1.6835  6.0620  1.8575  1.9394  2.5029  2.7712  5.3191  ±0.49%     2692
   · optimized  1,072.57  0.9002  1.9459  0.9323  0.9306  1.2270  1.2750  1.4360  ±0.19%     5363

 BENCH  Summary

  optimized - src/image-ssim.bench.ts
    1.99x faster than baseline

Run npm run bench to measure for yourself.

Comparing multiple candiates to a single source

If you are comparing multiple candidate ImageData against one source ImageData, you can use compareWith(). This amortizes the cost of analysis of the source image, for faster comparisons against multiple candidate images.

import { compareWith } from '@4bitlabs/ssim';

const compareWithSource = compareWith(sourceImage);

const r1 = compareWithSource(candidate1);
const r2 = compareWithSource(candidate2);

// faster than:
// const r1 = compare(sourceImage, candidate1);
// const r2 = compare(sourceImage, candidate2);

console.log(result1.ssim > result2.ssim ? 'Candidate 1 is closer' : 'Candidate 2 is closer')

This is ~1.5x faster than compare() directly, and ~3x faster than the reference implementation.

License

This package is licensed under the MIT license; the same license as the original library. Source copyright notices have been left intact. See the reference implementation for licensing details.