map the user interface for the h, s, v values to a color that I can then convert to any other format
for a color in any format the user can input (these will usually be the CSS Colors Level 4), obtain the representation in HSV space, so the interface can be updated accordingly

Of particular interest is deciding when to apply the alpha channel to the interface (i.e. to an opacity slider). If the interface contains color swatches, I should decide whether to use the alpha channel or not:

if the user inputs #ffffff I might only use the h, s and v value;
if the user inputs #ffffff00 I might also want to apply the a: 0 value.

Create color schemes based on a base color.

Obtain color scales to use in data visualization.

Supported formats

The library supports all the color formats defined in the CSS Colors Level 4:

✓ Named colors
✓ Hex colors (with 3, 4, 6, or 8 digits)
✓ RGB and RGBA
✓ HSL and HSLA
HWB
LAB and LCH

Additionally, it supports:

✓ HSV (also called HSB)
✓ HSI
(Hopefully) CubeHelix

The implementations I've already finished ar denoted by checkmarks (✓).

API Introduction

API Reference

§ culori( Specifier or Color ) <>

Just a convenience for culori.rgb().

culori('tomato');
culori('rgb(255, 0, 0)');
culori({ r: 0.5, g: 0.1, b: 0.2 });

§ culori.parse( Specifier ) → Color <>

Accepts a color in any CSS Colors Level 4 format and returns the corresponding RGB or HSL object.

If you'd like to always get a RGB representation regardless of the CSS format, use culori() instead.

Note: If the color does not specify an explicit alpha value, the a property of the RGB object is marked as undefined. Other color libraries will put a default a: 1 for these colors, but I found this assumption to be limiting. As such, we leave it to the user to place a: 1 instead of undefined when appropriate for their needs.

The individual parsers are exposed in the culori.parse namespace:

culori.parse.number( Specifier ) <>
culori.parse.named( Specifier ) <>
culori.parse.hex( Specifier ) <>
culori.parse.rgb( Specifier ) <>
culori.parse.hsl( Specifier ) <>

§ culori.convert( Specifier or Color ) <>

§ culori.css( Color, format ) <>

Converts a Color to a CSS representation. Accepted values for the format:

Format	Example
`rgb` (default)
`hex`
`hsl` (coming soon)

HSL

§ culori.hsl( Specifier or HSL or RGB or Object) → HSL <>

Accepts a color in any CSS Colors Level 4 format and returns the corresponding HSL object.

When passed a culori object:

if it's a HSL object, it just returns it back
it it's a RGB object, it converts it to a HSL object.

When passed a plain object, it assumes it's a normalized HSL object.

HSV

§ culori.hsv( Specifier or HSL or RGB or Object) → HSV <>

Accepts a color in any CSS Colors Level 4 format and returns the corresponding HSV object.

When passed a culori object:

if it's a HSV object, it just returns it back
it it's a RGB object, it converts it to a HSV object.

When passed a plain object, it assumes it's a normalized HSV object.

HSI

§ culori.hsi( Specifier or HSI or RGB or Object) → HSI <>

Accepts a color in any CSS Colors Level 4 format and returns the corresponding HSI object.

When passed a culori object:

if it's a HSI object, it just returns it back
it it's a RGB object, it converts it to a HSI object.

When passed a plain object, it assumes it's a normalized HSI object.

Color sets

§ culori.named <>

Contains the set of CSS Named Colors.

§ culori.brewer

ColorBrewer (coming soon).

Utilities

§ culori.round( value | object [, precision = 4 ] ) <>

Rounds the value, or each property in an object, to a certain number of decimal places. This is useful in a couple of situations:

When creating the CSS representation of the value;
To deal with floating-point errors that occur when converting between color formats.

§ culori.prepare( Specifier or Color ) <>

Definitions

Specifier. is a color in any parsable format. It is normally a string, but numbers (e.g. 0xFFF) are also accepted.

RGB is any plain object containing the r, g, b, and optionally a, properties with all values normalized to the interval [0..1].

HSL is any plain object containing the h, s, l, and optionally a, properties with the values for s, l, and a, normalized to the interval [0..1].

HSV is any plain object containing the h, s, v, and optionally a, properties with the values for s, v, and a, normalized to the interval [0..1].

HSI is any plain object containing the h, s, i, and optionally a, properties with the values for s, i, and a, normalized to the interval [0..1].

Prior art

This library is indebted to these projects:

Benchmarks

colori stacks well against its peers: benchmarks.

culori