ciecam02-ts

This library provides tools to work with the CIECAM02 color space.

It is a TypeScript port of @baskerville/ciecam02 with slight modifications (removed dependency, cleaned up code) and TypeScript declarations.

This hybrid package provides both CommonJS and ES module.

Install

``sh
// If you use yarn
yarn add ciecam02-ts

// If you use npm
npm install ciecam02-ts
`

Usage

$3

#### Converters

`ts
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

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

#### Gamut helpers

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

#### Misc helpers

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

$3

See also this source file.

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

import * as ciebase from "ciebase-ts";
import { Vector3D } from "ciebase-ts";
import * as ciecam02 from "../lib";
import { IJchProps, IViewingConditions } from "../lib";

const { illuminant, rgb, workspace } = ciebase;
const { cfs, lerp, hq } = ciecam02;

const { min, max } = Math;

//
// Shared settings for the examples
//

const xyz = ciebase.xyz(workspace.sRGB, illuminant.D65);

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

// 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.)
const cam = ciecam02.cam(viewingConditions, cfs("JCh"));
const gamut = ciecam02.gamut(xyz, cam);

const ucs = ciecam02.ucs();

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

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

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

//
// Example 1
//

const example1 = () => {
const camSand = hexToCam("e0cda9");
// {J: 77.82, C: 16.99, h: 81.01}
const camOrange = { ...camSand, C: 90 };
// {J: 77.82, C: 90.00, h: 81.01}
const [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.)
const camOrange1 = gamut.limit(camSand, camOrange);
// {J: 77.82, C: 55.23, h: 81.01}
// The alternative method is to simply crop the RGB coordinates
const camOrange2 = cam.fromXyz(xyz.fromRgb(rgbOrange.map(crop) as Vector3D));
// {J: 74.43, C: 67.60, h: 81.30}

// tslint:disable-next-line:no-console
console.log([camOrange1, camOrange2].map(camToHex)); // #ffc447 #ffb900
} else {
// tslint:disable-next-line:no-console
console.log(rgb.toHex(rgbOrange));
}
};

//
// Example 2
//

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

const hexCodes = gradient(
// camStart
hexToCam("17657d"),
// camEnd
hexToCam("fee7f0"),
// steps
8,
);

// tslint:disable-next-line:no-console
console.log(hexCodes);
};

//
// Example 3
//

const objectMap = (
obj: { [key: string]: T },
fn: (key: string, value: T, index: number, o: { [key: string]: T }) => R,
) => {
const r: { [key: string]: R } = {};
Object.keys(obj).forEach((key, index) => {
r[key] = fn(key, obj[key], index, obj);
});
return r;
};

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

// 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: string) {
return hq.toHue(hq.fromNotation(N));
}

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

const hexCodes = [camRed, camYellow, camGreen, camBlue].map((CAM) => {
CAM = ucsLimit(gamut.spine(CAM.J / 100) as any, CAM);
return camToHex(CAM);
});

// tslint:disable-next-line:no-console
console.log(hexCodes);
};

//
// Main
//

const main = () => {
// tslint:disable-next-line:no-console
console.log("Example 1");
example1();
// tslint:disable-next-line:no-console
console.log("Example 2");
example2();
// tslint:disable-next-line:no-console
console.log("Example 3");
example3();
// tslint:disable-next-line:no-console
console.log("Done");
};

main();
``

License: MIT

See the LICENSE file.