Libdither
A C library for color and black-and-white image dithering
Install / Use
/learn @robertkist/LibditherREADME
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.
<b>This version of libdither is a Release Candidate</b>: 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:
<table> <tr> <td><b>Original</b></td> <td><b>EGA palette (16 colors)<br>error diffusion</b></td> <td><b>C64 palette (16 colors)<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/bike_small.png" width=233 height=255></td> <td><img src="extra/examples/errordiff_dither_EGA.png" width=233 height=255></td> <td><img src="extra/examples/errordiff_dither_C64.png" width=233 height=255></td> </tr><tr> <td><b>Pico8 palette (16 colors)<br>error diffusion</b></td> <td><b>EGA palette (16 colors)<br>ordered dithering</b></td> <td><b>C64 palette (16 colors)<br>ordered dithering</b></td> </tr><tr> <td><img src="extra/examples/errordiff_dither_Pico8.png" width=233 height=255></td> <td><img src="extra/examples/ordered_void-dispersed-dots_dither_EGA.png" width=233 height=255></td> <td><img src="extra/examples/ordered_void-dispersed-dots_dither_C64.png" width=233 height=255></td> </tr> </table>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:
<table> <tr> <td><b>Median-Cut: 16 colors<br>error diffusion</b></td> <td><b>Wu: 16 colors<br>error diffusion</b></td> <td><b>KD-Tree: 16 colors<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/errordiff_dither_mediancut.png" width=233 height=255></td> <td><img src="extra/examples/errordiff_dither_wu.png" width=233 height=255></td> <td><img src="extra/examples/errordiff_dither_kd.png" width=233 height=255></td> </tr> </table>Note: Median-Cut and Wu are fairly fast, compared to KD-Tree. However, KD-Tree often gives the best results.
Color Reduction:
<table> <tr> <td><b>Original</b></td> <td><b>Median-Cut: 2 colors<br>error diffusion</b></td> <td><b>Median-Cut: 4 colors<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/david.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_2.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_4.png" width=220 height=262></td> </tr><tr> <td><b>Median-Cut: 8 colors<br>error diffusion</b></td> <td><b>Median-Cut: 16 colors<br>error diffusion</b></td> <td><b>Median-Cut: 32 colors<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/errordiff_dither_8.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_16.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_32.png" width=220 height=262></td> </tr> </table>Note: With a palette that matches the original palette well, 32 colors are often sufficient.
Color Matching / Color Distance function:
<table> <tr> <td><b>LAB '76: 16 colors<br>error diffusion</b></td> <td><b>LAB '04: 16 colors<br>error diffusion</b></td> <td><b>LAB 2000: 16 colors<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/errordiff_dither_lab76.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_lab94.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_lab2000.png" width=220 height=262></td> </tr><tr> <td><b>sRGB: 16 colors<br>error diffusion</b></td> <td><b>sRGB CCIR: 16 colors<br>error diffusion</b></td> <td><b>linear: 16 colors<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/errordiff_dither_srgb.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_srgb_ccir.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_linear.png" width=220 height=262></td> </tr><tr> <td><b>linear: 16 colors<br>error diffusion</b></td> <td><b>linear CCIR: 16 colors<br>error diffusion</b></td> <td><b>HSV: 16 colors<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/errordiff_dither_linear.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_tetrapal.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_hsv.png" width=220 height=262></td> </tr><tr> <td><b>luminance: 4 colors<br>error diffusion</b></td> <td><b>LAB 2000: 4 colors<br>error diffusion</b></td> <td><b>HSV: 4 colors<br>error diffusion</b></td> </tr><tr> <td><img src="extra/examples/errordiff_dither_gb_luminance.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_gb_lab2000.png" width=220 height=262></td> <td><img src="extra/examples/errordiff_dither_gb_hsv.png" width=220 height=262></td> </tr> </table>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.
