imgclr

imgclr modifies images to fit a given colour palette.

Dual-licensed under GPL-3.0 or MIT. To get imgclr, download the latest release or follow the compilation instructions.

Summary

imgclr:

• Quantises images, changing their palette
• Supports JPG, PNG, and other formats
• Supports dithering
• Can invert image brightness while preserving colour (converting dark images to light and vice versa)

Examples

Input	Result (dithered)

Dithering

Dithering can increase the perceived colour fidelity of a limited palette.

Input	Result (simple): each pixel either black or white	Result (dithered): each pixel either black or white

With dithering disabled, imgclr naively quantises the image. Disable dithering by passing --dither none:

imgclr input.jpg output.jpg --palette 000 fff f00 0f0 00f --dither none

Input	Result

Dithering is enabled by default (specifically, the Floyd-Steinberg algorithm). Disabling dithering or using other algorithms may yield very different results.

Dithering algorithms

• Floyd-Steinberg (--dither floyd-steinberg)

  • Floyd-Steinberg dithering is very common due to its balance of quality and speed.

• Atkinson (--dither atkinson)

  • Developed for Apple in the 90s, Atkinson dithering propagates only some of the quantisation error, resulting in a higher-constrast look.

• Jarvis-Judice-Ninke (--dither jjn)

  • Optimised for quality; relatively slow.

• Burkes (--dither burkes)

  • A faster approximation of the previous algorithm.

• Sierra Lite (--dither sierra-lite)

  • A slightly faster approximation of the Floyd-Steinberg algorithm.

• Dithering disabled (--dither none)

Inverting brightness

The --invert flag inverts luminance whilst preserving hue and saturation before quantisation. An example with the tokyonight colour scheme:

Input	Processed normally (no dithering)	Processed after luma inversion (no dithering)

Usage

imgclr <input file> <output file> <palette...> [options]

Options:
      --dither <algorithm>
        Specify dithering algorithm - one of:
            'floyd-steinberg' (default), 'none', 'atkinson', 'jjn',
            'burkes', 'sierra-lite'
      --invert
        Invert the image's luminance
      --palette <hex>...
        Specify palette - at least two (2) space-separated hex colours
  -h, --help
        Print this help and exit
      --version
        Print version information and exit

Building

Using a C99 compiler, build src/main.c, linking the math library. For example:

cc src/main.c -O3 -s -lm -o ./imgclr

Licence

imgclr is licensed under the terms of the MIT License, or alternatively under the terms of the General Public License (GPL) Version 3. You may use imgclr according to either of these licences as is most appropriate for your project on a case-by-case basis.

The terms of each licence can be found in the root directory of the imgclr source repository:

• MIT Licence: LICENSE-MIT
• GPL3 Licence: LICENSE-GPL3

SPDX-License-Identifier: MIT OR GPL-3.0-or-later