/imgclr

Colourise images to fit a certain palette.

Primary LanguageCGNU General Public License v3.0GPL-3.0

imgclr

imgclr modifies images to fit a given colour palette.

Banner image

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)
Original image Processed image (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
Original image Processed image (not dithered) Processed image (dithered)

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
Original image Processed image (not dithered)

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. Floyd-Steinberg

  • Atkinson (--dither atkinson)

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

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

    • Optimised for quality; relatively slow. Jarvis-Judice-Ninke

  • Burkes (--dither burkes)

    • A faster approximation of the previous algorithm. Burkes

  • Sierra Lite (--dither sierra-lite)

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

  • Dithering disabled (--dither none) Dithering disabled

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)
Original image Processed image Processed image with inversion

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:

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