IQ.ts

Complete Image Quantization Library in TypeScript(MIT License)

Table of Contents

• Introduction
• Capability
• Usage
• Todo
• 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

Capability

1. Platforms supported

   • browser (Chrome 7.0+, FireFox 4.0+, IE 10+, Opera 11.6+, Safari 5.1+)
   • node.js (Node.js 0.9.0+)

2. Builds

   • dist/browser-iq.js - JavaScript build for browser (global var IQ)
   • dist/node-iq.js - JavaScript build for Node.js (module.exports = IQ)
   • src/iq.ts - TypeScript module (use /// <reference path="path-to-library/src/iq.ts" />)

3. Import

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

4. Color Distance

   • Euclidean - originally used in Xiaolin Wu's Quantizer WuQuant
   • EuclideanRgbQuantWOAlpha (sRGB coefficients/without alpha support) - originally used in RgbQuant
   • EuclideanRgbQuantWithAlpha (sRGB coefficients)
   • Manhattan - originally used in NeuQuant
   • ManhattanSRGB (sRGB coefficients)
   • CIEDE2000_Original - full CIEDE2000 implementation (very very very slow)
   • CIEDE2000 - part of formula was stripped as it meaningless for JavaScript floating-point precision/RGB 8bit per channel converted to Lab (very very slow)
   • CIE94 - full CIE94 implementation
   • CMETRIC
   • PNGQUANT - used in pngQuant tool

5. Palette Quantizers

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

6. 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

7. Output

   • Uint32Array
   • Uint8Array

Include IQ Library into your project

TypeScript + Node.js/Browser project

/// <reference path='<path-to-iq>/src/iq.ts' />

JavaScript + Node.js project

variq=require("<path-to-iq>/dist/node-iq.js");

JavaScript + Browser project

<scriptsrc="<path-to-iq>/dist/browser-iq.js" type="text/javascript" charset="utf-8"></script>

Usage

Load Image (simple example)

varimg=document.createElement("img");img.onload=function(){// image is loaded, here should be all code utilizing image
...
}img.src="http://pixabay.com/static/uploads/photo/2012/04/11/11/32/letter-a-27580_640.png"

Generate Palette

// desired colors numbervartargetColors=256;// create pointContainer and fill it with imagevarpointContainer=IQ.Utils.PointContainer.fromHTMLImageElement(img);// create chosen distance calculator (see classes implementing `IQ.Distance.IDistanceCalculator`)vardistanceCalculator=newIQ.Distance.Euclidean();// create chosen palette quantizer (see classes implementing `IQ.Palette.IPaletteQuantizer`) varpaletteQuantizer=newIQ.Palette.RgbQuant(distanceCalculator,targetColors);// feed out pointContainer filled with image to paletteQuantizerpaletteQuantizer.sample(pointContainer);
... (youmaysamplemorethanoneimagetocreatemutualpalette)// take generated palettevarpalette=paletteQuantizer.quantize();

Apply Palette to Image (Image Dithering)

// create image quantizer (see classes implementing `IQ.Image.IImageDitherer`)varimageDitherer=newIQ.Image.NearestColor(distanceCalculator);// apply palette to imagevarresultPointContainer=imageQuantizer.quantize(pointContainer,palette);

You may work with resultPointContainer directly or you may convert it to Uint8Array/Uint32Array

varuint8array=resultPointContainer.toUint8Array();

TODO

1. notification about progress
2. riemersma dithering
3. ordered dithering

Changelog

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 CodeC#
  9. MedianCut (mwcz)GPLv3

• Image Quantization Algorithms

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

• Color Distance Formulas

  1. Euclidean Distance
  2. Manhattan Distance
  3. CIE94 Distance
     • Source Code (Iulius Curt)
  4. CIEDE2000
     • Math and Test Data Table (PDF)
     • Source Code (Greg Fiumara)C
  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. CMETRICDRAFT!

• 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)JavaLicense: 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

License

MIT