colorist

Absolute luminance or bust!

View on GitHub

AVIF Enthusiasts - Please Read –

If you’re here because you’re excited to make AVIFs and you’ve heard colorist can do it:

Please use avifenc and avifdec instead.

I am also the author of those tools (and libavif), and they’re actually what you want. colorist is about hijacking ICC profiles to pack HDR images where they don’t belong, and analyzing HDR. avifenc is a full-featured AVIF-standard-compliant AVIF generator. Please use it!

You can get it here:

https://github.com/AOMediaCodec/libavif

Or if you don’t mind a slightly out-of-date version, you can get it on macOS similarly to colorist:

brew install joedrago/repo/avifenc

(That is an unofficial install, but I try to keep it reasonably up-to-date.)

Finally here is a more detailed explanation of why I’m recommending this.

Installation

macOS

brew install joedrago/repo/colorist

Note: If it doesn’t find a pre-compiled bottle, building from source takes a while (10+ minutes). I’ll try to keep bottles available for the most recent macOS releases.

Windows

Grab the latest executable from Releases and put it somewhere in your PATH.

Build from source

Building from source requires CMake, version 3.5 or higher, and NASM.

Clone or download a zip of the repo, then run CMake on the root directory and run the generated build.

To use codecs other than libaom (used with AVIF), you must enable the associated AVIF_CODEC_* CMake variable, and to build locally, you must run the appropriate .cmd file in ext/avif/ext and then additionally enable the associated AVIF_LOCAL_* CMake variable.

For a near-automated Linux or macOS build, simply run scripts/build.sh. It requires Rust, CMake, Ninja, NASM, Meson, and Git, but should build dav1d and rav1e (for libavif), link them into colorist. Read the contents of build.sh and the .cmd files inside of ext/avif/ext to see exactly what commands will be run.

On a fresh Ubuntu 19.10 install, this appears to setup a proper build for colorist:

    # All base packages needed for building on Ubuntu 19.10
    sudo apt get install build-essential curl git cmake ninja-build meson nasm

    # latest cmdline pasted from rustup.rs, as of this writing
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

    # Clone and build colorist
    git clone https://github.com/joedrago/colorist.git
    cd colorist
    bash ./scripts/build.sh

Usage

Please see the Usage documentation and the Cookbook.

Build Status

AppVeyor Build Status Travis Build Status

Overview & Explanation

Colorist is an image file and ICC profile converter, generator, and identifier. Why make such a tool when the venerable ImageMagick already exists and seems to offer every possible image processing tool you can imagine? The answer is absolute luminance.

(Also, making tools is great fun.)

Since the dawn of computer rendering, luminance (brightness) has always been relative.** Values of 0 in a pixel have always meant “emit no light / as little light as possible”, and max values in a pixel (255 in 8-bit, etc) meant “as bright as possible”. We’ve gotten by just fine for a while with this strategy, but times are changing. For example, the HDR10 standard (BT.2100) and Dolby Vision have defined a luminance range of 0-10,000 nits. We no longer can assume that the author of an image containing max-channel white pixels intended to burn your retinas out of your head. We need more information!

** Hasn’t it?

This means somewhere in the image file we must store our intended max luminance such that renderers know how much to scale it when rendering (depending on the output’s max luminance). But where to store it? It turns out there is already a place available in any image file format that can embed an ICC profile: an ICC profile’s lumi tag. The explanation in the ICC spec for the lumi tag is:

This tag contains the absolute luminance of emissive devices in candelas per square metre as described by the Y channel.

Sounds perfect, no? Unfortunately, while ICC profile viewers and editors will happily manipulate this tag and standard ICC profiles occasionally include the tag for completeness, no image manipulation tool to date actually honors the value during conversion or rendering. Until now!

The goal of this tool is to be a one-stop shop for manipulating/abusing ICC profiles and image file formats (with respect to absolute luminance). By leveraging the fantastic LittleCMS library, choosing interesting tone curves and max luminance, and injecting my own scaling and tonemapping steps into the pipeline, I hope to maintain as much of the original image’s fidelity when converting to other color profiles or file formats that can’t handle larger bit depth or are excessively lossy.

Any files created/generated via this tool will still be fully standards compliant, it will simply have a slightly more interesting color profile embedded that you can choose to parse in your own engines and scale that luminance down accordingly. If the output of this tool isn’t to your satisfaction, ImageMagick is better in pretty much every other way. I highly recommend it!

License

Released under the Boost Software License (Version 1.0).