dbohdan/hicolor

🎨 Convert images to 15/16-bit RGB color with dithering

HiColor

(The image above has 15-bit color.)

HiColor is a program for converting images to 15- and 16-bit RGB color, the color depth of old display modes known as “high color”. I wrote it because I wanted to create images with the characteristic high-color look.

Contents

• Description
• Known bugs and limitations
• Usage
• Building
• Alternatives
• License

Description

HiColor reduces images to two-byte 15- or 16-bit color. In 15-bit mode images have 5 bits for each of red, green, and blue, with the last bit reserved. In 16-bit mode green, the color the human eye is generally most sensitive to, is given 6 bits.

HiColor implements its own simple file format and converts between this format and PNG. It can also convert standard PNG to standard PNG with only high-color color values. (This simulates a roundtrip through HiColor without creating a temporary file.) HiColor files have either the extension .hic or .hi5 for 15-bit and .hi6 for 16-bit respectively.

By default, HiColor applies the Bayer ordered dithering algorithm to reduce the quantization error (the difference between the original and the high-color pixel). Historical software and hardware used it for dithering in high-color modes. HiColor can also use “a dither” instead. Dithering can be selected or disabled with command-line flags.

Quantized images compress better than their originals, so HiColor can be a less-lossy alternative to the 256-color pngquant. Quantizing a PNG file to PNG preserves transparency (but does not quantize the alpha channel). Conversion to and from the HiColor format does not preserve transparency.

The program is written in C with minimal dependencies and builds as a static binary by default. It is known to work on Linux (aarch64, i386, riscv64, x86_64), FreeBSD, NetBSD, OpenBSD, and Windows 98 Second Edition, 2000 Service Pack 4, XP, 7, and 10.

Known bugs and limitations

PNG file size

PNG files produced by HiColor are not optimized. Run them through OptiPNG or Oxipng to significantly reduce their size.

Generation loss

With Bayer dithering or no dithering, there is no generation loss after the initial quantization. Applying “a dither” repeatedly to the same image will result in generation loss. In tests the loss converges to zero after 32 or 64 generations (in 15-bit and 16-bit mode respectively).

HiColor 0.1.0–0.2.1 suffered from generation loss with Bayer dithering due to an implementation error. The error was fixed in version 0.3.0.

Usage

HiColor has a Git-style CLI.

The actions encode and decode convert images between PNG and HiColor's own image format. quantize round-trips an image through the converter and outputs a standard 32-bit PNG. Use it to create high-color images readable by other programs. info displays information about a HiColor file: version (5 for 15-bit or 6 for 16), width, and height.

HiColor 0.5.0
Create 15/16-bit color RGB images.

usage:
  hicolor (encode|quantize) [-5|-6] [-a|-b|-n] [--] <src> [<dest>]
  hicolor decode <src> [<dest>]
  hicolor info <file>
  hicolor (version|help|-h|--help)

commands:
  encode           convert PNG to HiColor
  decode           convert HiColor to PNG
  quantize         quantize PNG to PNG
  info             print HiColor image version and resolution
  version          print program version
  help             print this help message

options:
  -5, --15-bit     15-bit color
  -6, --16-bit     16-bit color
  -a, --a-dither   dither image with "a dither"
  -b, --bayer      dither image with Bayer algorithm (default)
  -n, --no-dither  do not dither image

Building

Debian/Ubuntu

sudo apt install -y build-essential graphicsmagick tclsh
gmake test

Cross-compiling for Windows

The following commands build a 32-bit executable for Windows.

sudo apt install -y build-essential gcc-mingw-w64-i686
gmake hicolor.exe
# Wine, Tcl, and GraphicsMagick are needed only for testing.
sudo apt install -y graphicsmagick tclsh wine
gmake test-wine

Alternatives

I wrote HiColor because nothing seemed to support high color. I was wrong about that. Actually, FFmpeg, GIMP, and ImageMagick can reduce images to 15- and 16-bit color. What differentiates HiColor is being a small dedicated tool and embeddable C library and having its own file format.

License

MIT.

cute_png is copyright (c) 2019, 2021-2023 Randy Gaul and is licensed under the zlib license.

Photos from Unsplash

“plane in flight” (bordeaux-15bit.png) by olaf wisser.

“houses beside trees” (tests/photo.png) by Orlova Maria.

License

Unsplash grants you an irrevocable, nonexclusive, worldwide copyright license to download, copy, modify, distribute, perform, and use photos from Unsplash for free, including for commercial purposes, without permission from or attributing the photographer or Unsplash. This license does not include the right to compile photos from Unsplash to replicate a similar or competing service.

hicolor's Issues

Simply don't work

I click on the program and there is a command line that briefly shows up before closing. Alright, I figure I then have to run it through CMD itself.

So I type cd:\Users\Me into CMD (which is where I put the executable and the image, and then enter hicolor-v0.3.1-win32.exe hicolor quantize -5 example.png

But then it says "invalid command" and simply tells me:
hicolor (encode|decode|quantize) [options] src [dest]
hicolor info file
hicolor version
hicolor help

I don't know what I'm being asked to do. Even hicolor help produces "invalid command"

Lack of PNG format verification

As the cute_png.h library is used to load and parse PNG files, the returned image is not verified. This could cause the program's functionality to be disrupted.

An example I encountered was when the PNG headers stored excessive values for the image's height and width (despite the fact that the pixels are not stored in the data section of the format). This causes the malloc from the function cp_to_rgb to return NULL and, as a result of the pointer dereferencing below, the program will generate a SIGSERV and stop working.

alpha.png not found

When trying to build with "make test" i get the following:

./tests/hicolor.test


==== data-integrity-2.1 alpha roundtrip FAILED
==== Contents of test case:

    hicolor quant alpha.png alpha-q.png
    exec gm compare -metric rmse alpha.png alpha-q.png

---- Test generated error; Return code was: 1
---- Return code should have been one of: 0 2
---- errorInfo: source image "alpha.png" doesn't exist
    while executing
"exec {*}$::hicolorCommand {*}$args"
    (procedure "hicolor" line 2)
    invoked from within
"hicolor quant alpha.png alpha-q.png"
    ("uplevel" body line 2)
    invoked from within
"uplevel 1 $script"
---- errorCode: CHILDSTATUS 2909 1
==== data-integrity-2.1 FAILED

hicolor.test:   Total   24      Passed  23      Skipped 0       Failed  1
make: *** [Makefile:26: test] Error 1

Software can't even open

It doesn't open on my PC at all. All it does is have a command prompt window pop up for a split second.

Also, the linux version isn't even a program, it's a blank file. Not even a binary.

I've tried it in other operating systems yet it still doesn't work.