Skip to content

Latest commit

 

History

History
368 lines (351 loc) · 22.9 KB

README.md

File metadata and controls

368 lines (351 loc) · 22.9 KB

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