Libdither

Overview

Libdither is a library for black-and-white and color image dithering, written in C (ANSI C99 standard). Libdither has no external dependencies and should compile easily on most current systems (e.g. Windows, Linux, MacOS). All you need is a C compiler.

This version of libdither is a Release Candidate: it has been tested and is working, but minor code cleanup is still required.

The black-and-white only libdither version can now be found in the libdither_mono branch.

Features

• Color ditherers: error diffusion, ordered dithering
• Mono ditherers: grid dithering, ordered dithering, error diffusion, variable error diffusion (Ostromoukhov, Zhou Fang), pattern dithering, Direct Binary Search (DBS), dot diffusion, Kacker and Allebach dithering, Riemersma dithering, thresholding
• Support for color comparison modes: LAB76, LAB94, LAB2000, sRGB, linear, HSV, luminance, Tetrapal
• Support for color reduction: Median-Cut, Wu, KD-Tree
• Support for images with transparent background
• Libdither works in linear color space
• Dither matrices and inputs can be easily extended without having to change the dither code itself
• no external dependencies on other libraries
• works with C and C++ projects
• supports Windows, Linux, MacOS (universal binary support Intel / Apple silicon), and possible others

License Changes and 3rd-Party Code

Libdither MIT licensed, but the following code parts have their own permissive license:

• kdtree license: requires inclusion of license terms in source and binary distributions (more)
• uthash license: requires inclusion of license terms in source distributions (more)

Examples Color

Palettes:

Original	EGA palette (16 colors) error diffusion	C64 palette (16 colors) error diffusion
Pico8 palette (16 colors) error diffusion	EGA palette (16 colors) ordered dithering	C64 palette (16 colors) ordered dithering

Note: Palettes with a good range of hues and brightness, which matches the source image work best. If the overall palette is too dark, or too bright, the image, too, will be darker or brighte.

Color Quantization:

Median-Cut: 16 colors error diffusion	Wu: 16 colors error diffusion	KD-Tree: 16 colors error diffusion

Note: Median-Cut and Wu are fairly fast, compared to KD-Tree. However, KD-Tree often gives the best results.

Color Reduction:

Original	Median-Cut: 2 colors error diffusion	Median-Cut: 4 colors error diffusion
Median-Cut: 8 colors error diffusion	Median-Cut: 16 colors error diffusion	Median-Cut: 32 colors error diffusion

Note: With a palette that matches the original palette well, 32 colors are often sufficient.

Color Matching / Color Distance function:

LAB '76: 16 colors error diffusion	LAB '04: 16 colors error diffusion	LAB 2000: 16 colors error diffusion
sRGB: 16 colors error diffusion	sRGB CCIR: 16 colors error diffusion	linear: 16 colors error diffusion
linear: 16 colors error diffusion	linear CCIR: 16 colors error diffusion	HSV: 16 colors error diffusion
luminance: 4 colors error diffusion	LAB 2000: 4 colors error diffusion	HSV: 4 colors error diffusion

Notes:

• Different color distance measuring methods are supported for finding the closest color in the target palette.
• sRGB distance is a good, universally applicable choice.
• LAB2000 distance is the most accurate method. It works best with well balanced palettes, where it can pick up even subtle nuances, but it is slow.
• Luminance distance works best for gradients.
• CCIR distance methods take human perceptions into account and add a slight saturation boost.
• Tetrapal: works best for ordered dithering and pre-composed palettes (i.e. non quantified), such as EGA, C64, MS Paint palettes.
• Other distance methods may work better than others in certain cases - make sure to try them.

Examples Mono

Original	Grid dither	Xot error diffusion
Diagonal error diffusion	Floyd Steinberg error diffusion	ShiauFan 3 error diffusion
ShiauFan 2 error diffusion	ShiauFan 1 error diffusion	Stucki error diffusion
1D error diffusion	2D error diffusion	Fake Floyd Steinberg error diffusion
Jarvis-Judice-Ninke error diffusion	Atkinson error diffusion	Burkes error diffusion
Sierra 3 error diffusion	Sierra 2-row error diffusion	Sierra Lite error diffusion
Steve Pigeon error diffusion	Robert Kist error diffusion	Stevenson Arce error diffusion
Blue Noise dithering	Bayer 2x2 ordered dithering	Bayer 3x3 ordered dithering
Bayer 4x4 ordered dithering	Bayer 8x8 ordered dithering	Bayer 16x16 ordered dithering
Bayer 32x32 ordered dithering	Dispersed Dots v1 ordered dithering	Dispersed Dots v2 ordered dithering
Ulichney Void Dispersed Dots ordered dithering	Non-Rectangular v1 ordered dithering	Non-Rectangular v2 ordered dithering
Non-Rectangular v3 ordered dithering	Non-Rectangular v4 ordered dithering	Ulichney Bayer 5x5 ordered dithering
Ulichney ordered dithering	Clustered Dot v1 ordered dithering	Clustered Dot v2 ordered dithering
Clustered Dot v3 ordered dithering	Clustered Dot v4 ordered dithering	Clustered Dot v5 ordered dithering
Clustered Dot v6 ordered dithering	Clustered Dot v7 ordered dithering	Clustered Dot v8 ordered dithering
Clustered Dot v9 ordered dithering	Clustered Dot v10 ordered dithering	Clustered Dot v11 ordered dithering
Central White-Point ordered dithering	Balanced Central White-Point ordered dithering	Diagonal ordered dithering
Ulichney Clustered Dot ordered dithering	ImageMagick 5x5 Circle ordered dithering	ImageMagick 6x6 Circle ordered dithering
ImageMagick 7x7 Circle ordered dithering	ImageMagick 4x4 45-degree ordered dithering	ImageMagick 6x6 45-degree ordered dithering
ImageMagick 8x8 45-degree ordered dithering	ImageMagick 4x4 ordered dithering	ImageMagick 6x6 ordered dithering
ImageMagick 8x8 ordered dithering	Variable 2x2 ordered dithering	Variable 4x4 ordered dithering
Interleaved Gradient ordered dithering	Ostromoukhov variable error diffusion	Zhou Fang variable error diffusion
Thresholding	DBS v1 dithering	DBS v2 dithering
DBS v3 dithering	DBS v4 dithering	DBS v5 dithering
DBS v6 dithering	DBS v7 dithering	Kacker and Allebach dithering
Modified Riemersma (Hilbert Curve 1) dithering	Modified Riemersma (Hilbert Curve 2) dithering	Modified Riemersma (Peano Curve) dithering
Modified Riemersma (Fass0 Curve) dithering	Modified Riemersma (Fass1 Curve) dithering	Modified Riemersma (Fass2 Curve) dithering
Modified Riemersma (Gosper Curve) dithering	Modified Riemersma (Fass Spiral) dithering	Riemersma (Hilbert Curve 1) dithering
Riemersma (Hilbert Curve 2) dithering	Riemersma (Peano Curve) dithering	Riemersma (Fass0 Curve) dithering
Riemersma (Fass1 Curve) dithering	Riemersma (Fass2 Curve) dithering	Riemersma (Gosper Curve) dithering
Riemersma (Fass Spiral) dithering	Pattern (2x2) dithering	Pattern (3x3 v1) dithering
Pattern (3x3 v2) dithering	Pattern (3x3 v3) dithering	Pattern (4x4) dithering
Pattern (5x2) dithering	Lippens and Philips v1 dot dithering	Lippens and Philips v2 dot dithering
Lippens and Philips v3 dot dithering	Lippens and Philips (Guo Liu 16x16) dot dithering	Lippens and Philips (Mese and Vaidyanathan 16x16) dot dithering
Lippens and Philips (Knuth) dot dithering	Knuth dot diffusion	Mini-Knuth dot diffusion
Optimized Knuth dot diffusion	Mese and Vaidyanathan 8x8 diffusion	Mese and Vaidyanathan 16x16 dot diffusion
Guo Liu 8x8 dot diffusion	Guo Liu 16x16 dot diffusion	Spiral dot diffusion
Inverted Spiral dot diffusion

Building Libdither

You need an ANSI C compiler and the make utility. Run make to display all build options. By default, libdither is built for the current architecture. Once compiled, you can find the finished library in the dist directory.

MacOS notes:

• Installing the XCode command line tools is all you need for building libdither
• You can choose if you want to build a x64, arm64 or universal library. The demo, however, only builds against the current machine's architecture.

Linux notes:

• gcc and make is all you need to build libdither. E.g. on Ubuntu you should install build-essential via apt to get these tools.

Windows notes - MinGW:

• Install make via Chocolatey package manager from chocolatey.org (https://chocolatey.org/, https://chocolatey.org/packages/make)
• Open the Makefile and ensure the path (on top of the file) points to your MingW installation directory.
• Run make libdither to build using MinGW.

Windows notes - Microsoft Visual Studio Solution:

• Open the solution file (`.sln) in Visual Studio 2022 or newer.
• There are 3 projects you can build: libdither (dynamic `.dll library) and the demo.

Windows notes - Microsoft Visual Studio (make):

• To build using make, install make via Chocolatey package manager from chocolatey.org (https://chocolatey.org/, https://chocolatey.org/packages/make)
• Run make libdither_msvc to build (make sure to run Visual Studio's vcvars64.bat first!)
• OR use the solution file (.sln) to build libdither from the Visual Studio IDE (2022 or newer).

Usage

The src/demo example shows how to load an image (we use .bmp as it's an easy format to work with), convert it to linear color space, dither it, and write it back to an output .bmp file. The demo was used to create all the dithering examples you can see below.

You can also look at libdither.h, which includes commentary on how to use libdither.

In your own code, you only need to #include "libdither.h", which includes all public functions and data structures, and link the libdither library, either statically or dynamically.