image-q

Complete Image Quantization Library in TypeScript (MIT License)

Table of Contents

• API Documentation and Usage
• Introduction
• Features
• Todo
• Breaking changes
• Changelog
• Credits
• References
• License

Introduction

Image Color Number Reduction with alpha support using RGBQuant/NeuQuant/Xiaolin Wu's algorithms and Euclidean/Manhattan/CIEDE2000 color distance formulas in TypeScript

Features

1. Platforms supported

   • Browser (Chrome 7.0+, FireFox 4.0+, IE 10+, Opera 11.6+, Safari 5.1+)
   • Node.js 6.0+

2. API

   • Basic API: sync and promise-based async
   • Advanced API: sync and generator-based

3. Builds

   • dist/cjs/image-q.js - CommonJS
   • dist/esm/image-q.js - ESM (ESNext)
   • dist/cjs/image-q.js - UMD

4. Import

   • HTMLImageElement
   • HTMLCanvasElement
   • NodeCanvas
   • ImageData
   • Array
   • CanvasPixelArray
   • Uint8Array
   • Uint32Array

5. Color Distance

   • Euclidean - 1/1/1/1 coefficients (originally used in Xiaolin Wu's Quantizer WuQuant)
   • EuclideanBT709NoAlpha - BT.709 sRGB coefficients (originally used in RGBQuant)
   • EuclideanBT709 BT.709 sRGB coefficients + alpha support
   • Manhattan - 1/1/1/1 coefficients (originally used in NeuQuant)
   • ManhattanBT709 - BT.709 sRGB coefficients
   • ManhattanNommyde - see https://github.com/igor-bezkrovny/image-quantization/issues/4#issuecomment-234527620
   • CIEDE2000 - CIEDE2000 (very slow)
   • CIE94Textiles - CIE94 implementation for textiles
   • CIE94GraphicArts - CIE94 implementation for graphic arts
   • CMetric - see http://www.compuphase.com/cmetric.htm
   • PNGQuant - used in pngQuant tool

6. Palette Quantizers

   • NeuQuant (original code ported, integer calculations)
   • NeuQuantFloat (floating-point calculations)
   • RGBQuant
   • WuQuant

7. Image Quantizers

   • NearestColor
   • ErrorDiffusionArray - two modes of error propagation are supported: xnview and gimp
     1. FloydSteinberg
     2. FalseFloydSteinberg
     3. Stucki
     4. Atkinson
     5. Jarvis
     6. Burkes
     7. Sierra
     8. TwoSierra
     9. SierraLite
   • ErrorDiffusionRiemersma - Hilbert space-filling curve is used

8. Output

   • Uint32Array
   • Uint8Array

Include image-q library into your project

ES6 module

// will import ESM (ESNext) or UMD version depending on your bundler/node
import * as iq from 'image-q';

CommonJS

var iq = require('image-q');

As a global variable (Browser)

<script
  src="<path-to image-q/dist/umd/image-q.js>"
  type="text/javascript"
  charset="utf-8"
></script>

How to use

Please refer to API Documentation and Usage

Breaking changes

2.1.1

+ PaletteQuantizer#quantize => PaletteQuantizer#quantizeSync
+ ImageQuantizer#quantize => ImageQuantizer#quantizeSync

2.0.1 - 2.0.4 (2018-02-22)

+ EuclideanRgbQuantWOAlpha => EuclideanBT709NoAlpha
+ EuclideanRgbQuantWithAlpha => EuclideanBT709
	+ ManhattanSRGB => ManhattanBT709
	+ IImageDitherer => AbstractImageQuantizer
	+ IPaletteQuantizer => AbstractPaletteQuantizer
	+ PointContainer.fromNodeCanvas => PointContainer.fromHTMLCanvasElement
	+ PointContainer.fromArray => PointContainer.fromUint8Array
+ PointContainer.fromBuffer (Node.js, new)
	+ CMETRIC => CMetric
	+ PNGQUANT => PNGQuant
	+ SSIM Class => ssim function

TODO

1. ~~notification about progress~~
2. ~~riemersma dithering~~
3. ordered dithering <-- is there anyone who needs it?
4. readme update, more examples
5. demo update (latest image-q npm version should be used in demo)

Changelog

4.0.0

+ Test cases for different types of imports and requres added

4.0.0-alpha

+ Try to solve exported bundle types problem. 'umd' bundle removed.

3.0.8

+ Test case for issue #95 added

3.0.7

+ Fixes #96: Fix minimumColorDistanceToDither (PR #97 by @pixelplanetdev)

3.0.6

+ Fixes #95: "Always empty result in certain webpack / babel configs" (PR #98)

3.0.4

+ Fixes issue "Module not found: Can't resolve 'core-js/fn/set-immediate' in ..."

3.0.0

+ pnpm monorepo, esbuild for faster builds, typescript upgraded

2.1.1

+ Basic (Simple) API implemented
+ see breaking changes

2.0.5 (2018-02-23)

+ @types/node moved to 'dependencies'

2.0.4 (2018-02-23)

+ documentation added
+ some refactorings/renames, see breaking changes

2.0.3 (2018-02-22)

+ circular dependency removed

2.0.2 (2018-02-22)

+ readme updated

2.0.1 (2018-02-22)

+ progress tracking api (using es6 generators) added
+ strinct lint rules (+code cleanup/renames)
+ rollup (3 different versions - umd, cjs, esm + source maps + d.ts)
+ latest TypeScript
+ jest
+ snapshot tests
+ coverage (+coveralls)
+ greenkeeper

1.1.1 (2016-08-28)

+ CIEDE2000 - incorrect calculation fixed
+ CIEDE2000 - alpha channel now has only 25% impact on color distance instead of 66%
+ CIE94 - added 2 types (textiles and graphics art) according to spec
+ CIE94 - alpha support added
+ rgb2xyz, lab2xyz, xyz2rgb, xyz2lab - gamma correction
+ lab2xyz, xyz2lab - refY should be 100 (1.00000) instead of 10 (0.10000)
+ manhattan with new (Nommyde) coefficients added
+ mocha tests added
+ webpack integration
+ image-q is now UMD module
+ travis-ci integration
+ typescript 2.0
+ indentation with 4 spaces

0.1.4 (2015-06-24)

+ Refactoring
+ Riemersma dithering added (Hilbert Curve)
+ Readme.md updated
+ build.cmd updated

0.1.3 (2015-06-16)

+ NeuQuant is fixed (again) according to original Anthony Dekker source code (all values should be integer)
+ Error Diffusion Dithering is now calculates error like XNVIEW
+ Refactoring

0.1.2 (2015-06-16)

+ Documentation generation fixed
+ File name case problem fixed

0.1.1 (2015-06-16)

+ Auto-generated documentation added
+ Refactoring

0.1.0 (2015-06-16)

+ Code cleanup, removed unnecessary files

0.0.5 (2015-06-16)

+ PNGQuant color distance added, need to check its quality
+ CIEDE2000 and CIE94 fixed for use in NeuQuant
+ NeuQuant is fixed according to original Anthony Dekker source code (all values should be integer)
+ Code refactoring and cleanup
* We have some slowdown because of red/green/blue/alpha normalization according to white point per each calculateRaw/calculateNormalized call

0.0.4 (2015-06-15)

+ CIEDE2000 color distance equation optimized (original CIEDE2000 equation is available as class `CIEDE2000_Original`)

0.0.3b (2015-06-11)

+ CMetric color distance fixed

0.0.3a (2015-06-11)

+ Cleanup
+ Draft of CMetric color distance added

0.0.2 (2015-06-10)

+ rgb2xyz & xyz2lab fixed. CIEDE2000 works much better now.
+ CIE94 distance formula added. More investigation is needed.

0.0.1

+ Initial

Credits

Thanks to Leon Sorokin for information share and his original RGBQuant!

References

• Palette Quantization Algorithms

  1. RGBQuant (Leon Sorokin) JavaScript
  2. NeuQuant (Johan Nordberg) TypeScript
  3. NeuQuant (Tim Oxley) JavaScript
  4. NeuQuant (Devon Govett) JavaScript
  5. NeuQuant32 (Stuart Coyle) C
  6. Xiaolin Wu (Xiaolin Wu) C
  7. Xiaolin Wu (Smart-K8) C#
  8. Xiaolin Wu w/ Alpha (Matt Wrock) How to add Alpha, Source Code C#
  9. MedianCut (mwcz) GPLv3

• Image Quantization Algorithms

  1. All (ImageMagik doc)
  2. Error Diffusion dithering (Tanner Helland)
  3. Riemersma dithering TODO: Check License
  4. Ordered dithering (Joel Yliluoma)

• Color Distance Formulas

  Calculator + Info

  1. Euclidean Distance
  2. Manhattan Distance
  3. CIE94 Distance
     • Source Code (Iulius Curt)
  4. CIEDE2000
     • Math and Test Data Table (PDF)
     • Info
     • Source Code (Greg Fiumara) C
     • Source Code (THEjoezack) C#
     • Online Calculator
  5. Euclidean Distance w/o Alpha (RGBQuant)
  6. Euclidean Distance w/o sRGB coefficients (Xiaolin Wu Quant)
  7. Manhattan Distance w/o sRGB coefficients (NeuQuant)
  8. CMetric DRAFT!

• Color conversion formulas

  1. Pseudo-code

Be sure to fix rgb2xyz/xyz2lab. Issue is with strange part of code: r = r > 0.04045 ? .... Check http://en.wikipedia.org/wiki/Lab_color_space

• Image Quality Assessment

  1. SSIM info
  2. SSIM (Rhys-e) Java License: MIT
  3. PSNR ? TBD
  4. MSE ? TBD

• Other

  1. HUSL (Boronine) - info
  2. HUSL (Boronine) - code
  3. Color Image Quantization for Frame Buffer Display
  4. K-Means
  5. Efficient Color Quantization by Hierarchical Clustering Algorithms
  6. http://www.codeproject.com/Articles/66341/A-Simple-Yet-Quite-Powerful-Palette-Quantizer-in-C

License

MIT