Culori

⚠ Until v1.0.0 the API is a work-in-progress and will be changing quite a bit.

Culori is a general-purpose color library for JavaScript. It incorporates, and extends, ideas from Mike Bostock's D3.js and Gregor Aisch's chroma.js.

Color Spaces. Culori supports all the formats defined in the CSS Colors Level 4: Named colors, Hex colors (3 to 8 digits), RGB, HSL, HWB, Lab and LCh, and Grays. Additionally, the Linear RGB, HSV (also known as HSB), HSI, and Cubehelix color spaces are supported.

Color Differences. Culori can compute color differences with either a simple Euclidean distance or the CIELAB Delta E* metric as formulated by CIE76, CIE94, CIEDE2000 and CMC l:c (1984). They're also available as a D3 plugin. It can also find the closest N colors from a set of colors based on any of these differences.

Foreword

If you're thinking Do we really need another JavaScript color library?, I hear you. Reader, for the most part, we don't. Mike Bostock's d3-color, and Gregor Aisch's chroma.js are two robust libraries that provide most of what you need for working with colors on the web¹. I'll admit Culori² is foremost a reflection of my own curiousity in understanding color spaces at a deeper level. But it also ended up a fairly fast, and fairly comprehensive, toolkit for manipulating colors — and with an implementation that has certain advantages.

The alpha channel which governs a color's opacity is treated differently than in other libaries, in that we don't equate an undefined alpha with an alpha of 1. The hex string #ff0000 should eventually be interpreted as a fully-opaque red color, but at the color-manipulation level we want to draw the distinction between #ff0000 and #ff0000ff, which has an explicit alpha channel.

When developing the API, I tried to balance brevity, convenience and flexibility. It ended up a more-or-less functional API, i.e. a collection of functions you can pipe data through. It's not as readable as a fluent API where you chain methods, but it's much more flexible, I think.

¹ Other popular libraries you may want to look at are TinyColor by Brian Grinstead, color by Heather Arthur, color.js by Andrew Brehaut et al, and chromatist by Jacob Rus.

² from the Romanian word for ‘colors’.

Getting Started

Installation

If you're using NPM, you can install culori by running:

npm install culori

You can either require or import culori in your project:

// either
var culori = require('culori');

// or
import { rgb } from 'culori';

To import culori as a <script> tag to use in a web page, load it from unpkg:

• https://unpkg.com/culori@0.4.0/build/culori.js
• https://unpkg.com/culori@0.4.0/build/culori.min.js

If you prefer not to use a Content Delivery Network such as unpkg, just save the one of the JS files linked above to your project.

Trying it online

You can use npm.runkit.com/culori as a playground to test various methods in from the API without installing culori in your project.

API Reference

• Color representation
• A note on the API
• Basics methods
• Interpolation
• Difference

Color representation

Culori does not have a Color class. Instead, it uses plain objects to represent colors:

// A color in the RGB space
{
  mode: 'rgb',
  r: 0.1,
  g: 0.2,
  b: 1,
  alpha: 1
}

The object needs to have a mode property that identifies the color space, and values for each channel in that particular color space. See the Color Spaces section for the channels expected of each color space. Optionally, the alpha property is used for the color's alpha channel.

A note on the API

TODO explain Functional style and its benefits.

Basic methods

# culori.parse(string) → color or undefined <>

Parses a string and returns the corresponding color. The color will be in the matching color space, e.g. RGB for hex strings, HSL for hsl(…, …, …) strings, et cetera. If no built-in parsers can match the string, the function will return undefined.

// named colors
culori.parse('red'); // ⇒ { r: 1, g: 0, b: 0, mode: 'rgb' }

// hex strings
culori.parse('#ff0000'); // ⇒ { r: 1, g: 0, b: 0, mode: 'rgb' }

// HSL color
culori.parse('hsl(60 50% 10% / 100%)'); // ⇒ { h: 60, s: 0.5, b: 0.1, alpha: 1, mode: 'hsl' }

// Lab color
culori.parse('lab(100 -50 50)'); // ⇒ { l: 100, a: -50, b: 50, mode: 'lab' }

# culori.converter(mode = "rgb") → function (color or String) <>

Returns a function that can then convert any color to the mode color space:

var rgb = culori.converter('rgb');

rgb('#f0f0f0'); // ⇒ { "mode": "rgb", "r": 0.4980392156862745, "g": 0.4980392156862745, "b": 0.4980392156862745 }

Converters accept either strings (which will be parsed with culori.parse) or color objects. If the mode key is absent from the color, it's assumed to be in the converter's color space.

The available modes (color spaces) are listed below. Each color space has a convenience method for converting to that color space.

# culori.formatter(format = 'rgb') → function (color) <>

Returns a formatter function that can transform colors to useful string representations.

let hex = culori.formatter('hex');

hex('red'); // ⇒ "#ff0000"

Available formats:

# culori.displayable(color or String) <>

For some color spaces — particularly Lab and LCh — not all colors that can be expressed can be displayed on-screen. This function lets you check whether a particular color fits inside the sRGB gamut, i.e. that its r, g, and b channels are in the interval [0, 1].

culori.displayable('red'); // ⇒ true
culori.displayable('rgb(300 255 255)'); // ⇒ false

# culori.clamp(method = 'rgb') → function (color) <>

Returns a function which you can then use to retreive a representation of any color that's displayable on the screen, i.e. fits within the sRGB gamut. There are two available methods:

• method = 'rgb' clamps the r, g, b channel values of the color's RGB representation to the interval [0, 1];
• method = 'lch' converts the color to the LCh space and finds the largest Chroma channel value that's displayable for the given Lightness and Hue; if not even the achromatic version (Chroma = 0) of the LCh color is displayable, it falls back to the rgb method.

culori.clamp('lch')('lch(50 120 5)'); // ⇒ { mode: 'lch', l: 50, c: 77.48291015625, h: 5 }

# culori.round(n = 8) <>

A (rather miscellaneous) utility that returns a function with which to round numbers to at most n digits of precision.

let approximate = culori.round(4);

approximate(0.38393993); // => 0.3839

Interpolation

# culori.interpolate(colors, mode = "rgb") <>

Returns an interpolator between an array of colors in the mode color space.

# culori.samples(n = 2, γ = 1) <>

Returns an array of n equally-spaced samples from the [0, 1] range, with 0 and 1 at the ends. The function also accepts a γ (gamma) parameter which will map each value t to t^γ.

culori.samples(3); // => [0, 0.5, 1]
culori.samples(5); // => [0, 0.25, 0.5, 0.75, 1]

The samples are useful for culori.interpolate() to generate color scales:

let grays = culori.interpolate(['#fff', '#000']);
samples(5).map(grays);

Interpolation functions

# culori.interpolateFunctionLinear <>

# culori.interpolateFunctionSpline <>

# culori.interpolateFunctionMonotone <>

# culori.interpolateFunctionCosine <>

Interpolation modes

# culori.interpolateNumber <>

# culori.interpolateHue <>

# culori.interpolateAlpha <>

Difference

These methods are concerned to finding the distance between two colors based on various formulas. Each of these formulas will return a function (colorA, colorB) that lets you measure the distance between two colors. Also available as a separate d3 plugin.

# culori.differenceEuclidean(mode = 'rgb') <>

Returns a Euclidean distance function in a certain color space.

# culori.differenceCie76() <>

Computes the CIE76 ΔE*_ab color difference between the colors a and b. The computation is done in the Lab color space and it is analogous to culori.differenceEuclidean('lab').

# culori.differenceCie94(kL = 1, K1 = 0.045, K2 = 0.015) <>

Computes the CIE94 ΔE*₉₄ color difference between the colors a and b. The computation is done in the Lab color space.

# culori.differenceCiede2000(Kl = 1, Kc = 1, Kh = 1) <>

Computes the CIEDE2000 ΔE*₀₀ color difference between the colors a and b as implemented by G. Sharma. The computation is done in the Lab color space.

Returns a CIEDE2000 Delta E* function.

# culori.differenceCmc() <>

Computes the CMC l:c (1984) ΔE*_CMC color difference between the colors a and b. The computation is done in the Lab color space.

Note: ΔE*_CMC is not considered a metric since it's not symmetrical, i.e. the distance from a to b is not always equal to the distance from b to a. Therefore it cannot be reliably used with culori.nearest().

# culori.differenceDin99o() <>

Computes the DIN99o ΔE*_99o color difference between the colors a and b. The computation is done in the DIN99o color space.

Nearest color(s)

# culori.nearest(colors, metric = differenceEuclidean(), accessor = identity) → function(color, n = 1, τ = Infinity) <>

For a given metric color difference formula, and an array of colors, returns a function with which you can find n colors nearest to color, with a maximum distance of τ.

Pass n = Infinity to get all colors in the array with a maximum distance of τ.

Color Spaces

TODO

HSL

The figure above shows a slice of the HSL color space for a particular hue:

HSV

The figure above shows a slice of the HSV color space for a particular hue:

HSI

The figure above shows a slice of the HSI color space for a particular hue:

Culori Recipes

Relative luminance of a color

The relative luminance of a color is defined as:

L = 0.2126 * R + 0.7152 * G + 0.0722 * B

Where R, G, and B are the components from the LRGB color space.

To compute it in Culori:

function luminance(color) {
  let c = culori.lrgb(color);
  return 0.2126 * c.r + 0.7152 * c.g + 0.0722 * c.b;
}

Note: The WCAG defines the luminance using a deprecated value for converting sRGB to LRGB. If you'd like a strict implementation, you'll need to write your own sRGB → LRGB conversion.

Contrast ratio

Using the luminance() function above, the contrast() ratio is simply the ratio between the luminances of two colors, with the values shifted by 0.05 to avoid division by zero when comparing against black.

function contrast(colorA, colorB) {
  let L1 = luminance(colorA);
  let L2 = luminance(colorB);
  return (L1 + 0.05) / (L2 + 0.05);
}

Extending Culori

TODO

See also

These libraries extend Culori:

• culori-scales — color scales (ColorBrewer, matplotlib, etc.)
• culori-names — more color names

Further reading

• HSL and HSV on Wikipedia
• CSS Color Module Level 4
• CSSOM standard serialization

Colophon

• Author Dan Burzo
• License MIT
• Inspired by d3-color, d3-interpolate, chroma.js
• Dependencies none
• Bundled with rollup, buble
• Tested with tape