pex-color

Color utilities (css, rgb, hex, hsl, hsv, hwb, lab, xyz, okhsl, okhsv, oklab, hpluv, hsluv, lchuv, bytes) for PEX.

Installation

npm install pex-color

Usage

import color from "pex-color";

// Hexadecimal
color.toHex([1, 0, 0]);
// => "#FF0000"

color.toHex([1, 0, 0, 0.5]);
// => "#FF000080"

color.toHex([1, 0, 0, 0.5], false);
// => "#FF0000"

color.fromHex(color.create(), "#FF0000");
// => [1, 0, 0, 1]

color.fromHex(new Array(3), "#FF0000");
// => [1, 0, 0]

// CSS
color.toCSSRGB([1, 0, 0, 1]);
// => "rgba(255, 0, 0, 1)"

color.toCSSLab([1, 0, 0, 1]);
// => "lab(53.23711% 78.27048 62.14609 / 1)"

// Various color spaces
color.toOklab([1, 0, 0, 1]);
// => [0.62796, 0.22486, 0.12585, 1]

// Utils
color.utils.linearToSrgb(0.5);
// => 0.7353569830524495

API

The "color" primitive is an array of 3 (RGB) or 4 (A) values in the range 0 < x < 1.

API naming follows the following rules:

• fromType(color, ...values) = set a color primitive from Type values
• toType(color, out) = convert a color primitive to an array of Type and optionally set it to out

Modules

utils

Functions

fromBytes(color, bytes) ⇒ color

Updates a color based on byte values.

toBytes(color, out) ⇒ bytes

Get RGB[A] color components as bytes array.

create([r], [g], [b], [a]) ⇒ color

Creates a new color from linear values.

copy(color) ⇒ color

Returns a copy of a color.

set(color, color2) ⇒ color

Sets a color to another color.

fromValues(color, r, g, b, [a]) ⇒ color

Updates a color based on r, g, b, [a] values.

toCSSRGB(color, [precision]) ⇒ css

Returns a rgb CSS string representation of a given color.

toCSSHSL(color, [precision]) ⇒ css

Returns a hsl CSS string representation of a given color.

toCSSLab(color, [precision]) ⇒ css

Returns a lab CSS string representation of a given color.

toCSSLCH(color, [precision]) ⇒ css

Returns a lch CSS string representation of a given color.

toCSSHWB(color, [precision]) ⇒ css

Returns a hwb CSS string representation of a given color.

fromHex(color, hex) ⇒ color

Updates a color based on a hexadecimal string.

toHex(color, alpha) ⇒ hex

Returns a hexadecimal string representation of a given color.

fromHPLuv(color, h, s, l, [a]) ⇒ color

Updates a color based on HPLuv values and alpha.

toHPLuv(color, out) ⇒ hpluv

Returns a HPLuv representation of a given color.

fromHSL(color, h, s, l, [a]) ⇒ color

Updates a color based on HSL values and alpha.

toHSL(color, out) ⇒ hsl

Returns a HSL representation of a given color.

fromHSLuv(color, h, s, l, [a]) ⇒ color

Updates a color based on HSLuv values and alpha.

toHSLuv(color, out) ⇒ hsluv

Returns a HSLuv representation of a given color.

fromHSV(color, h, s, v, [a]) ⇒ color

Updates a color based on HSV values and alpha.

toHSV(color, out) ⇒ hsv

Returns a HSV representation of a given color.

fromHWB(color, h, w, b, [a]) ⇒ color

Updates a color based on HWB values and alpha.

toHWB(color, out) ⇒ hwb

Returns a HWB representation of a given color.

fromLab(color, l, a, b, α, illuminant) ⇒ color

Updates a color based on Lab values and alpha.

toLab(color, out, illuminant) ⇒ lab

Returns a Lab representation of a given color.

fromLCHuv(color, l, c, h, [a]) ⇒ color

Updates a color based on LCHuv values and alpha.

toLCHuv(color, out) ⇒ lchuv

Returns a LCHuv representation of a given color.

fromLinear(color, r, g, b, [a]) ⇒ color

Updates a color based on linear values.

toLinear(color, out) ⇒ linear

Returns a linear color representation of a given color.

fromOkhsl(color, h, s, l, [α]) ⇒ color

Updates a color based on Okhsl values and alpha.

toOkhsl(color, out) ⇒ okhsl

Returns an Okhsl representation of a given color.

fromOkhsv(color, h, s, v, [α]) ⇒ color

Updates a color based on Okhsv values and alpha.

toOkhsv(color, out) ⇒ okhsv

Returns an Okhsv representation of a given color.

fromOklab(color, L, a, b, [α]) ⇒ color

Updates a color based on Oklab values and alpha.

toOklab(color, out) ⇒ oklab

Returns an Oklab representation of a given color.

fromXYZ(color, x, y, z, a) ⇒ color

Updates a color based on XYZ values and alpha.

toXYZ(color, out) ⇒ xyz

Returns a XYZ representation of a given color.

Typedefs

bytes : Array.<number>

An array of 3 (RGB) or 4 (A) values in bytes.

All components in the range 0 <= x <= 255

color : Array.<number>

An array of 3 (RGB) or 4 (A) values.

All components in the range 0 <= x <= 1

css : string

CSS string representation.

hex : string

hexadecimal string (RGB[A] or RRGGBB[AA]).

hpluv : Array.<number>

CIELUV hue, saturation, lightness.

All components in the range 0 <= x <= 1.

hsl : Array.<number>

hue, saturation, lightness.

All components in the range 0 <= x <= 1

hsluv : Array.<number>

CIELUV hue, saturation, lightness.

All components in the range 0 <= x <= 1

hsv : Array.<number>

hue, saturation, value.

All components in the range 0 <= x <= 1

hwb : Array.<number>

hue, whiteness, blackness.

All components in the range 0 <= x <= 1

lab : Array.<number>

CIELAB with D65 standard illuminant as default.

Components range (D65): 0 <= l <= 1; -0.86183 <= a <= 0.98234; -1.0786 <= b <= 0.94478;

Components range (D50): 0 <= l <= 1; -0.79287 <= a <= 0.9355; -1.12029 <= b <= 0.93388;

lchuv : Array.<number>

CIELChuv Luminance Chroma Hue.

All components in the range 0 <= x <= 1

linear : Array.<number>

r g b linear values.

All components in the range 0 <= x <= 1

okhsl : Array.<number>

All components in the range 0 <= x <= 1

okhsv : Array.<number>

All components in the range 0 <= x <= 1

oklab : Array.<number>

Cartesian form using D65 standard illuminant.

Components range: 0 <= l <= 1; -0.233 <= a <= 0.276; -0.311 <= b <= 0.198;

xyz : Array.<number>

CIE XYZ using D65 standard illuminant.

Components range: 0 <= x <= 0.95; 0 <= y <= 1; 0 <= z <= 1.08;

utils

• utils
  • .linearToSrgb ⇒ number
  • .srgbToLinear ⇒ number

utils.linearToSrgb ⇒ number

Convert component from linear value

Kind: static constant of utils

Param	Type
c	number

utils.srgbToLinear ⇒ number

Convert component to linear value

Kind: static constant of utils

Param	Type
c	number

fromBytes(color, bytes) ⇒ color

Updates a color based on byte values.

Kind: global function

Param	Type
color	color
bytes	bytes

toBytes(color, out) ⇒ bytes

Get RGB[A] color components as bytes array.

Kind: global function

Param	Type
color	color
out	Array

create([r], [g], [b], [a]) ⇒ color

Creates a new color from linear values.

Kind: global function

Param	Type	Default
[r]	number	0
[g]	number	0
[b]	number	0
[a]	number

copy(color) ⇒ color

Returns a copy of a color.

Kind: global function

Param	Type
color	color

set(color, color2) ⇒ color

Sets a color to another color.

Kind: global function

Param	Type
color	color
color2	color

fromValues(color, r, g, b, [a]) ⇒ color

Updates a color based on r, g, b, [a] values.

Kind: global function

Param	Type
color	color
r	number
g	number
b	number
[a]	number

toCSSRGB(color, [precision]) ⇒ css

Returns a rgb CSS string representation of a given color.

Kind: global function

Param	Type	Default
color	color
[precision]	number	5

toCSSHSL(color, [precision]) ⇒ css

Returns a hsl CSS string representation of a given color.

Kind: global function

Param	Type	Default
color	color
[precision]	number	5

toCSSLab(color, [precision]) ⇒ css

Returns a lab CSS string representation of a given color.

Kind: global function

Param	Type	Default
color	color
[precision]	number	5

toCSSLCH(color, [precision]) ⇒ css

Returns a lch CSS string representation of a given color.

Kind: global function

Param	Type	Default
color	color
[precision]	number	5

toCSSHWB(color, [precision]) ⇒ css

Returns a hwb CSS string representation of a given color.

Kind: global function

Param	Type	Default
color	color
[precision]	number	5

fromHex(color, hex) ⇒ color

Updates a color based on a hexadecimal string.

Kind: global function

Param	Type	Description
color	color
hex	hex	Leading '#' is optional.

toHex(color, alpha) ⇒ hex

Returns a hexadecimal string representation of a given color.

Kind: global function

Param	Type	Description
color	color
alpha	boolean	Handle alpha

fromHPLuv(color, h, s, l, [a]) ⇒ color

Updates a color based on HPLuv values and alpha.

Kind: global function

Param	Type
color	color
h	number
s	number
l	number
[a]	number

toHPLuv(color, out) ⇒ hpluv

Returns a HPLuv representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromHSL(color, h, s, l, [a]) ⇒ color

Updates a color based on HSL values and alpha.

Kind: global function

Param	Type
color	color
h	number
s	number
l	number
[a]	number

toHSL(color, out) ⇒ hsl

Returns a HSL representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromHSLuv(color, h, s, l, [a]) ⇒ color

Updates a color based on HSLuv values and alpha.

Kind: global function

Param	Type
color	color
h	number
s	number
l	number
[a]	number

toHSLuv(color, out) ⇒ hsluv

Returns a HSLuv representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromHSV(color, h, s, v, [a]) ⇒ color

Updates a color based on HSV values and alpha.

Kind: global function

Param	Type
color	color
h	number
s	number
v	number
[a]	number

toHSV(color, out) ⇒ hsv

Returns a HSV representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromHWB(color, h, w, b, [a]) ⇒ color

Updates a color based on HWB values and alpha.

Kind: global function

Param	Type
color	color
h	number
w	number
b	number
[a]	number

toHWB(color, out) ⇒ hwb

Returns a HWB representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromLab(color, l, a, b, α, illuminant) ⇒ color

Updates a color based on Lab values and alpha.

Kind: global function

Param	Type
color	color
l	number
a	number
b	number
α	number
illuminant	Array

toLab(color, out, illuminant) ⇒ lab

Returns a Lab representation of a given color.

Kind: global function

Param	Type
color	color
out	Array
illuminant	Array

fromLCHuv(color, l, c, h, [a]) ⇒ color

Updates a color based on LCHuv values and alpha.

Kind: global function

Param	Type
color	color
l	number
c	number
h	number
[a]	number

toLCHuv(color, out) ⇒ lchuv

Returns a LCHuv representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromLinear(color, r, g, b, [a]) ⇒ color

Updates a color based on linear values.

Kind: global function

Param	Type
color	color
r	number
g	number
b	number
[a]	number

toLinear(color, out) ⇒ linear

Returns a linear color representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromOkhsl(color, h, s, l, [α]) ⇒ color

Updates a color based on Okhsl values and alpha.

Kind: global function

Param	Type
color	color
h	number
s	number
l	number
[α]	number

toOkhsl(color, out) ⇒ okhsl

Returns an Okhsl representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromOkhsv(color, h, s, v, [α]) ⇒ color

Updates a color based on Okhsv values and alpha.

Kind: global function

Param	Type
color	color
h	number
s	number
v	number
[α]	number

toOkhsv(color, out) ⇒ okhsv

Returns an Okhsv representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromOklab(color, L, a, b, [α]) ⇒ color

Updates a color based on Oklab values and alpha.

Kind: global function

Param	Type
color	color
L	number
a	number
b	number
[α]	number

toOklab(color, out) ⇒ oklab

Returns an Oklab representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

fromXYZ(color, x, y, z, a) ⇒ color

Updates a color based on XYZ values and alpha.

Kind: global function

Param	Type
color	color
x	number
y	number
z	number
a	number

toXYZ(color, out) ⇒ xyz

Returns a XYZ representation of a given color.

Kind: global function

Param	Type
color	color
out	Array

bytes : Array.<number>

An array of 3 (RGB) or 4 (A) values in bytes.

All components in the range 0 <= x <= 255

Kind: global typedef

color : Array.<number>

An array of 3 (RGB) or 4 (A) values.

All components in the range 0 <= x <= 1

Kind: global typedef

css : string

CSS string representation.

Kind: global typedef See: https://www.w3.org/TR/css-color-4/

hex : string

hexadecimal string (RGB[A] or RRGGBB[AA]).

Kind: global typedef

hpluv : Array.<number>

CIELUV hue, saturation, lightness.

All components in the range 0 <= x <= 1.

Kind: global typedef

hsl : Array.<number>

hue, saturation, lightness.

All components in the range 0 <= x <= 1

Kind: global typedef See: https://en.wikipedia.org/wiki/HSL_and_HSV

hsluv : Array.<number>

CIELUV hue, saturation, lightness.

All components in the range 0 <= x <= 1

Kind: global typedef See: https://www.hsluv.org/

hsv : Array.<number>

hue, saturation, value.

All components in the range 0 <= x <= 1

Kind: global typedef See: https://en.wikipedia.org/wiki/HSL_and_HSV

hwb : Array.<number>

hue, whiteness, blackness.

All components in the range 0 <= x <= 1

Kind: global typedef See: https://en.wikipedia.org/wiki/HWB_color_model

lab : Array.<number>

CIELAB with D65 standard illuminant as default.

Components range (D65): 0 <= l <= 1; -0.86183 <= a <= 0.98234; -1.0786 <= b <= 0.94478;

Components range (D50): 0 <= l <= 1; -0.79287 <= a <= 0.9355; -1.12029 <= b <= 0.93388;

Kind: global typedef See: https://en.wikipedia.org/wiki/CIELAB_color_space

lchuv : Array.<number>

CIELChuv Luminance Chroma Hue.

All components in the range 0 <= x <= 1

Kind: global typedef See: https://en.wikipedia.org/wiki/CIELUV

linear : Array.<number>

r g b linear values.

All components in the range 0 <= x <= 1

Kind: global typedef See: https://en.wikipedia.org/wiki/SRGB

okhsl : Array.<number>

All components in the range 0 <= x <= 1

Kind: global typedef See: https://bottosson.github.io/posts/colorpicker/#hsv-2

okhsv : Array.<number>

All components in the range 0 <= x <= 1

Kind: global typedef See: https://bottosson.github.io/posts/colorpicker/#hsv-2

oklab : Array.<number>

Cartesian form using D65 standard illuminant.

Components range: 0 <= l <= 1; -0.233 <= a <= 0.276; -0.311 <= b <= 0.198;

Kind: global typedef See: https://bottosson.github.io/posts/oklab/#converting-from-linear-srgb-to-oklab

xyz : Array.<number>

CIE XYZ using D65 standard illuminant.

Components range: 0 <= x <= 0.95; 0 <= y <= 1; 0 <= z <= 1.08;

Kind: global typedef See: https://en.wikipedia.org/wiki/CIE_1931_color_space

License

MIT. See license file.