Skip to content

Latest commit

 

History

History
297 lines (234 loc) · 10.7 KB

README.md

File metadata and controls

297 lines (234 loc) · 10.7 KB

IQ.ts

Complete Image Quantization Library in TypeScript (MIT License)

Build Status demo github npm version API Documentation NPM License

quantization

Table of Contents

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

    • iq.js - UMD build (import * as iq from "image-q")

  3. Import

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

  4. Color Distance

    • Euclidean - 1/1/1/1 coefficients (originally used in Xiaolin Wu's Quantizer WuQuant)
    • EuclideanRgbQuantWOAlpha - BT.709 sRGB coefficients (originally used in RgbQuant)
    • EuclideanRgbQuantWithAlpha BT.709 sRGB coefficients + alpha support
    • Manhattan - 1/1/1/1 coefficients (originally used in NeuQuant)
    • ManhattanSRGB - BT.709 sRGB coefficients
    • ManhattanNommyde - see ibezkrovnyi/image-quantization#4 (comment)
    • 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

  5. Palette Quantizers

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

  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

ES6 module
import * as iq from "image-q"
CommonJS
var iq = require("image-q");
As a global variable (Browser)
<script src="<path-to image-q/dist/iq.js>" type="text/javascript" charset="utf-8"></script>

Usage

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 inherited from `iq.distance.AbstractDistanceCalculator`)
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

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

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

License

MIT