colorquant

README

Colorquant

Colorquant is an image / color quantization library written in Go. It can be considered as a replacement for the quantization and dithering part of the draw method from the core image library for various reasons (see below).

The purpose

The purpose of color quantization is to reduce the color palette of an image to a fraction of it's initial colors (usually 256), but to preserve it's representative colors and to elliminate visual artifacts at the same time. Even with the best set of 256 colors, there are many images that look bad. They have visible contouring in regions where the color changes slowly.

To create a smoother transition between colors and to wash out the edges various dithering methods can be plugged in.

Implementation

The implementation is mainly based on the article from Leptonica.

The reason why I opted for a custom quantization and dithering algorithm are twofold:

• First, even the core draw method does provide an error quantization algorithm, it does not implement the support for quantization level (to how many colors we wish to reduce the original image).
• Second, the dithering method is based exclusively on Floyd-Steinberg dithering method, but there are other dithering algorithm, which can be used (ex. Burkes, Stucki, Atkinson, Sierra etc.).

Installation

go get -u github.com/esimov/colorquant

Running

The library provides a CLI method to generate the quantified images. Type go run cli.go --help to get the supported commands.

Usage of commands:
  -compression int
    	JPEG compression. (default 100)
  -ditherer string
    	Dithering method. (default "FloydSteinberg")
  -no-dither
    	Use image quantizer without dithering.
  -output string
    	Output directory. (default "output")
  -palette int
    	The number of palette colors. (default 256)
  -type string
    	Image type. Possible options .jpg, .png (default "jpg")

The generated images will be exported into the output folder. By default the Floyd-Steinberg dithering method is applied, but if you whish to not use any dithering algorithm use the --no-dither flag.

Usage

➤ Without dither

This is main method to generate a non-dithered quantified image:

colorquant.NoDither.Quantize(src, dst, numColors, false, true)

where the last paremeter means either to use the library quantization algorithm (if the parameter is true), otherwise use the quantization level provided by the paletted image (if the paramater is false).

➤ With dither

The same, but this time using a dithering method:

ditherer.Quantize(src, dst, numColors, true, true)

where ditherer is struct with the form of:

"FloydSteinberg" : colorquant.Dither{
	[][]float32{
		[]float32{ 0.0, 0.0, 0.0, 7.0 / 48.0, 5.0 / 48.0 },
		[]float32{ 3.0 / 48.0, 5.0 / 48.0, 7.0 / 48.0, 5.0 / 48.0, 3.0 / 48.0 },
		[]float32{ 1.0 / 48.0, 3.0 / 48.0, 5.0 / 48.0, 3.0 / 48.0, 1.0 / 48.0 },
	},
},

Examples

All the examples below are generated using Floyd-Steinberg dithering method with the following command line as an example:

go run cli.go ../input/treefrog.jpg -compression 100 -ditherer FloydSteinberg -palette 128

Number of colors	Without dither	With Dither
128
256
512
1024

License

This software is distributed under the MIT license found in the LICENSE file.

Documentation

Index

• type Dither
  • func (dither Dither) Empty() bool
  • func (dither Dither) Quantize(src image.Image, dst draw.Image, nq int, useDither bool, useQuantizer bool) image.Image
• type Quant
  • func (q *Quant) Median(c *cluster) uint32
  • func (qz *Quant) Paletted() image.PalettedImage
  • func (q Quant) Quantize(img image.Image, nq int) image.Image
  • func (q *Quant) Split(s, c *cluster, m uint32)
• type Quantizer

Types

type Dither

type Dither struct {
	Filter [][]float32
}

Struct containing a two dimensional slice for storing different dithering methods.

func (Dither) Empty

func (dither Dither) Empty() bool

Check if dither struct is empty. If empty this means we are not using any dithering method.

func (Dither) Quantize

func (dither Dither) Quantize(src image.Image, dst draw.Image, nq int, useDither bool, useQuantizer bool) image.Image

The Quantize method takes as parameter the original image and returns the processed image with dithering.

type Quant

type Quant struct {
	// contains filtered or unexported fields
}

A workspace with members that can be accessed by methods.

func (*Quant) Median

func (q *Quant) Median(c *cluster) uint32

func (*Quant) Paletted

func (qz *Quant) Paletted() image.PalettedImage

func (Quant) Quantize

func (q Quant) Quantize(img image.Image, nq int) image.Image

Image quantization method. Returns a paletted image. We need to use type assertion to match the interface returning type.

func (*Quant) Split

func (q *Quant) Split(s, c *cluster, m uint32)

type Quantizer

type Quantizer interface {
	Quantize(image.Image, draw.Image, int, bool, bool) image.Image
}

Interface which implements the Quantize method.

var NoDither Quantizer = Dither{}

Used to call the default quantize method without applying dithering.