API

Converters

cam(viewingConditions?, correlates?) -> {
    fromXyz(XYZ) -> CAM,
    toXyz(CAM) -> XYZ,
    fillOut(correlates, inputs) -> outputs
}

ucs(name?="UCS") -> {
    fromCam(CAM) -> UCS,
    toCam(UCS) -> CAM,
    distance(UCS1, UCS2) -> number
}

hq: {
    fromHue(h) -> H,
    toHue(H) -> h,
    fromNotation(N) -> H,
    toNotation(H) -> N
}

Default viewing conditions

{
    whitePoint: illuminant.D65,
    adaptingLuminance: 40,
    backgroundLuminance: 20,
    surroundType: "average",
    discounting: false
}

Gamut helpers

gamut(xyz, cam, epsilon?=1e-6) -> {
    contains(CAM) -> (boolean, RGB),
    limit(camIn, camOut, prec?=1e-3) -> CAM,
    spine(t) -> CAM
}

Misc helpers

cfs(str) -> correlates,
lerp(CAM1, CAM2, t) -> CAM

Examples

Getting back into the gamut

// The reference for understanding CIECAM02 is:
// http://www.springer.com/cda/content/document/cda_downloaddocument/9781441961891-c1.pdf

import * as ciebase from "ciebase";
import * as ciecam02 from "ciecam02";
import {merge} from "mout/object";

var {rgb, workspace, illuminant} = ciebase,
    {cfs} = ciecam02,
    xyz = ciebase.xyz(workspace.sRGB, illuminant.D65);

var viewingConditions = {
    whitePoint: illuminant.D65,
    adaptingLuminance: 40,
    backgroundLuminance: 20,
    surroundType: "average",
    discounting: false
};

// By default, 7 correlates are returned when converting from XYZ to CAM.
// For the purpose of this example, we will limit ourselves to the JCh correlates.
// (J is the lightness, C the chroma and h the hue.)
var cam = ciecam02.cam(viewingConditions, cfs("JCh")),
    gamut = ciecam02.gamut(xyz, cam),
    {min, max} = Math;

function hexToCam(hex) {
    return cam.fromXyz(xyz.fromRgb(rgb.fromHex(hex)));
}

function camToHex(CAM) {
    return rgb.toHex(xyz.toRgb(cam.toXyz(CAM)));
}

function crop (v) {
    return max(0, min(1, v));
}

var camSand = hexToCam("e0cda9"),                       // {J: 77.82, C: 16.99, h: 81.01}
    camOrange = merge(camSand, {C: 90}),                // {J: 77.82, C: 90.00, h: 81.01}
    [isInside, rgbOrange] = gamut.contains(camOrange);  // [false, [1.09, 0.73, -0.7]]

if (!isInside) {
    // The gamut.limit function interpolates between an inside and an outside point
    // and return an inside point as close as possible to the boundary.
    // (The gamut is the set of CAM values that maps to valid RGB coordinates.)
    let camOrange1 = gamut.limit(camSand, camOrange),                // {J: 77.82, C: 55.23, h: 81.01}
    // The alternative method is to simply crop the RGB coordinates
        camOrange2 = cam.fromXyz(xyz.fromRgb(rgbOrange.map(crop)));  // {J: 74.43, C: 67.60, h: 81.30}
    console.log([camOrange1, camOrange2].map(camToHex));             // #ffc447   #ffb900
} else {
    console.log(rgb.toHex(rgbOrange));
}

Gradient

var {lerp} = ciecam02,
    camStart = hexToCam("17657d"),
    camEnd = hexToCam("fee7f0");

function gradient (camStart, camEnd, steps=3) {
    var result = [];
    for (var ε = 1/(steps+1), t = 0; steps > -2; t += ε, steps -= 1) {
        let camBetween = lerp(camStart, camEnd, crop(t)),
            hex = rgb.toHex(xyz.toRgb(cam.toXyz(camBetween)).map(crop));
        result.push(hex);
    }
    return result;
}

var hexCodes = gradient(camStart, camEnd, 8);

Chroma maximization

import {map} from "mout/object";

var {hq} = ciecam02,
    ucs = ciecam02.ucs();

function ucsLimit (camIn, camOut, prec=1e-3) {
    // UCS is based on the JMh correlates
    var [ucsIn, ucsOut] = [camIn, camOut].map(v => ucs.fromCam(cam.fillOut(cfs("JMh"), v)));
    while (ucs.distance(ucsIn, ucsOut) > prec) {
        let ucsMid = lerp(ucsIn, ucsOut, 0.5),
            [isInside,] = gamut.contains(ucs.toCam(ucsMid));
        if (isInside) {
            ucsIn = ucsMid;
        } else {
            ucsOut = ucsMid;
        }
    }
    return cam.fillOut(map(camIn, v => true), ucs.toCam(ucsIn));
}

// The hue notation is a different writting of the hue quadrant,
// of the form a(p?b)? where a and b are in {R, Y, G, B} (a ≠ b)
// and p is in ]0, 100[. apb = b(100-p)a, ab = a50b.
function hue (N) {
    return hq.toHue(hq.fromNotation(N));
}

var topChroma = max(...["f00", "0f0", "00f"].map(v => hexToCam(v).C)),
    camRed = {J: 60, h: hue("R")},
    camYellow = {J: 90, h: hue("Y")},
    camGreen = {J: 90, h: hue("G")},
    camBlue = {J: 70, h: hue("B")};

var hexCodes = [camRed, camYellow, camGreen, camBlue].map(function (CAM) {
    CAM = merge(CAM, {C: topChroma+1});
    CAM = ucsLimit(gamut.spine(CAM.J/100), CAM);
    return camToHex(CAM);
});