Libdither

Overview

Libdither is a library for black-and-white image dithering, written in C (ANSI C99 standard). Libdither has no external dependencies and should compile easily on most current systems.

Dithering algorithms:

• Grid dithering
• Ordered dithering, incl. Blue Noise dithering
• Error diffusion dithering
• Variable error diffusion (Ostromoukhov, Zhou Fang)
• Pattern dithering
• Direct Binary Search (DBS) dithering
• Dot diffusion
• Kacker and Allebach dithering
• Riemersma dithering
• Thresholding

Other features:

• Libdither works in linear color space and takes image gamma into account
• Dither matrices and inputs can be easily extended without having to change the dither code itself
• no external dependencies on other libraries
• tested on Windows (MingW w64 11.2.0, MSVC 2019), Linux (gcc 11.2.0) and macOS (clang 13.1.6)
• works with C and C++ projects
• fairly portable code (most prototyping was done in Python)
• universal binary support (intel and Apple silicon) for macOS

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:

• You can build both MingW and MSVC targets from the Makefile (sorry, no .sln)
• For MingW, open the Makefile and ensure the path (on top of the file) points to your MingW installation directory
• Install make via Chocolatey package manager from chocolatey.org (https://chocolatey.org/, https://chocolatey.org/packages/make)

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.

Examples

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