Image Quantization Library (image-q)

## IQ.ts

Image Quantization Library in TypeScript (MIT 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

API
Online Demo
Demo Source

## Capability

title | description
--- | ---
Import | HTMLImageElement, HTMLCanvasElement, NodeCanvas, ImageData, Array, CanvasPixelArray, Uint8Array, Uint32Array
Palette | NeuQuant, RgbQuant, Xiaolin Wu's method
Image | Nearest Color, Error Diffusion Dithering
Export | 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

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

##### JavaScript + Browser project

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

## Usage Example

##### Load Image (simple example)

    var img = 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 number
    var targetColors = 256;

    // create pointContainer and fill it with image
    var pointContainer = IQ.Utils.PointContainer.fromHTMLImageElement(img);

    // create chosen distance calculator (see classes implementing `IQ.Distance.IDistanceCalculator`)
    var distanceCalculator = new IQ.Distance.Euclidean();

    // create chosen palette quantizer (see classes implementing `IQ.Palette.IPaletteQuantizer`)
    var paletteQuantizer = new IQ.Palette.RgbQuant(distanceCalculator, targetColors);

    // feed out pointContainer filled with image to paletteQuantizer
    paletteQuantizer.sample(pointContainer);

    ... (you may sample more than one image to create mutual palette)

    // take generated palette
    var palette = paletteQuantizer.quantize();

##### Apply Palette to Image (Image Dithering)

    // create image quantizer (see classes implementing `IQ.Image.IImageDitherer`)
    var imageDitherer = new IQ.Image.NearestColor(distanceCalculator);

    // apply palette to image
    var resultPointContainer = imageQuantizer.quantize(pointContainer, palette);

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

    var uint8array = 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

## License

License MIT (NeuQuant use also forces to add it's copyright notice into source code)

## 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

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

Generated using TypeDoc