# 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](https://github.com/joedrago/colorist/releases) and put it somewhere in your PATH.

### Build from source

Building from source requires [CMake](https://cmake.org/download/), version 3.5
or higher, and [NASM](https://nasm.us/).

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:

```bash
    # 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](./docs/Usage.md) documentation and the
[Cookbook](./docs/Cookbook.md).

---

# Build Status

[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/joedrago/colorist?branch=master&svg=true)](https://ci.appveyor.com/project/joedrago/colorist) [![Travis Build Status](https://travis-ci.com/joedrago/colorist.svg?branch=master)](https://travis-ci.com/joedrago/colorist)

---

# Overview & Explanation

Colorist is an image file and ICC profile converter, generator, and identifier.
Why make such a tool when the venerable
[ImageMagick](https://www.imagemagick.org/) 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](https://en.wikipedia.org/wiki/Rec._2100)) and [Dolby
Vision](https://en.wikipedia.org/wiki/Dolby_Laboratories#Video_processing)
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!

<sup><sub>\*\* *Hasn't it?*</sub></sup>

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](http://www.littlecms.com/) 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).