Skip to content

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

License

Notifications You must be signed in to change notification settings

pex-gl/pex-color

Repository files navigation

pex-color

npm version stability-stable npm minzipped size dependencies types Conventional Commits styled with prettier linted with eslint license

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

Installation

npm install pex-color

Usage

import * as 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.toCSSP3([1, 0, 0, 1]);
// => "color(display-p3 0.91748 0.20028 0.13856)"

color.toCSSP3([1, 0, 0, 0.5]);
// => "color(display-p3 0.91748 0.20028 0.13856 / 0.5)"

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

// Utils
color.utils.linearToSrgb(0.5);
// => 0.7353569830524495
color.utils.D50;
// => [0.9642956764295677, 1, 0.8251046025104602]

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

pex-color
utils

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 perceptual Lightness, a* red/green, b* blue/yellow.

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;

lch : Array.<number>

CIELCh Luminance Chroma Hue. Cylindrical form of Lab.

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

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;

oklch : Array.<number>

Cylindrical form using D65 standard illuminant.

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

p3 : Array.<number>

r, g, b values (DCI-P3 color gamut, D65 whitepoint, sRGB gamma curve).

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

xyz : Array.<number>

CIE XYZ.

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

pex-color

pex-color.fromBytes(color, bytes) ⇒ color

Updates a color based on byte values.

Kind: static method of pex-color

Param Type
color color
bytes bytes

pex-color.toBytes(color, out) ⇒ bytes

Get RGB[A] color components as bytes array.

Kind: static method of pex-color

Param Type
color color
out Array

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

Creates a new color from linear values.

Kind: static method of pex-color

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

pex-color.copy(color) ⇒ color

Returns a copy of a color.

Kind: static method of pex-color

Param Type
color color

pex-color.set(color, color2) ⇒ color

Sets a color to another color.

Kind: static method of pex-color

Param Type
color color
color2 color

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

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

Kind: static method of pex-color

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

pex-color.toCSSRGB(color, [precision]) ⇒ css

Returns a rgb CSS string representation of a given color.

Kind: static method of pex-color See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color

Param Type Default
color color
[precision] number 5

pex-color.toCSSRGBLinear(color, [precision]) ⇒ css

Returns a linear rgb CSS string representation of a given color.

Kind: static method of pex-color See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color

Param Type Default
color color
[precision] number 5

pex-color.toCSSRGBLinear(color, [precision]) ⇒ css

Returns a P3 rgb CSS string representation of a given color.

Kind: static method of pex-color See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color

Param Type Default
color color
[precision] number 5

pex-color.toCSSHSL(color, [precision]) ⇒ css

Returns a hsl CSS string representation of a given color.

Kind: static method of pex-color See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl

Param Type Default
color color
[precision] number 5

pex-color.toCSSHWB(color, [precision]) ⇒ css

Returns a hwb CSS string representation of a given color.

Kind: static method of pex-color See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hwb

Param Type Default
color color
[precision] number 5

pex-color.toCSSLab(color, [precision]) ⇒ css

Returns a lab CSS string representation of a given color.

Kind: static method of pex-color See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lab

Param Type Default
color color
[precision] number 5

pex-color.toCSSLab(color, [precision]) ⇒ css

Returns a lab CSS string representation of a given color.

Kind: static method of pex-color

Param Type Default
color color
[precision] number 5

pex-color.toCSSLCH(color, [precision]) ⇒ css

Returns a lch CSS string representation of a given color.

Kind: static method of pex-color See: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lch

Param Type Default
color color
[precision] number 5

pex-color.toCSSOkLab(color, [precision]) ⇒ css

Returns a lab CSS string representation of a given color.

Kind: static method of pex-color

Param Type Default
color color
[precision] number 5

pex-color.toCSSOklch(color, [precision]) ⇒ css

Returns a lch CSS string representation of a given color.

Kind: static method of pex-color

Param Type Default
color color
[precision] number 5

pex-color.toCSSXYZD50(color, [precision]) ⇒ css

Returns a xyz-d50 CSS string representation of a given color.

Kind: static method of pex-color

Param Type Default
color color
[precision] number 5

pex-color.toCSSXYZ(color, [precision]) ⇒ css

Returns a xyz (xyz-d65) CSS string representation of a given color.

Kind: static method of pex-color

Param Type Default
color color
[precision] number 5

pex-color.fromHex(color, hex) ⇒ color

Updates a color based on a hexadecimal string.

Kind: static method of pex-color

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

pex-color.toHex(color, alpha) ⇒ hex

Returns a hexadecimal string representation of a given color.

Kind: static method of pex-color

Param Type Description
color color
alpha boolean Handle alpha

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

Updates a color based on HPLuv values and alpha.

Kind: static method of pex-color

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

pex-color.toHPLuv(color, out) ⇒ hpluv

Returns a HPLuv representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on HSL values and alpha.

Kind: static method of pex-color

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

pex-color.toHSL(color, out) ⇒ hsl

Returns a HSL representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on HSLuv values and alpha.

Kind: static method of pex-color

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

pex-color.toHSLuv(color, out) ⇒ hsluv

Returns a HSLuv representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on HSV values and alpha.

Kind: static method of pex-color

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

pex-color.toHSV(color, out) ⇒ hsv

Returns a HSV representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on HWB values and alpha.

Kind: static method of pex-color

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

pex-color.toHWB(color, out) ⇒ hwb

Returns a HWB representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

pex-color.fromLabD50(color, l, a, b, α) ⇒ color

Updates a color based on Lab values and alpha using D50 standard illuminant.

Kind: static method of pex-color

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

pex-color.toLabD50(color, out) ⇒ lab

Returns a Lab representation of a given color using D50 standard illuminant.

Kind: static method of pex-color

Param Type
color color
out Array

pex-color.fromLabD65(color, l, a, b, α) ⇒ color

Updates a color based on Lab values and alpha using D65 standard illuminant.

Kind: static method of pex-color

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

pex-color.toLabD65(color, out) ⇒ lab

Returns a Lab representation of a given color using D65 standard illuminant.

Kind: static method of pex-color

Param Type
color color
out Array

pex-color.fromLCH(color, l, c, h, [a]) ⇒ color

Updates a color based on LCH values and alpha.

Kind: static method of pex-color

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

pex-color.toLCH(color, out) ⇒ lch

Returns a LCH representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on LCHuv values and alpha.

Kind: static method of pex-color

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

pex-color.toLCHuv(color, out) ⇒ lchuv

Returns a LCHuv representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on linear values.

Kind: static method of pex-color

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

pex-color.toLinear(color, out) ⇒ linear

Returns a linear color representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on Okhsl values and alpha.

Kind: static method of pex-color

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

pex-color.toOkhsl(color, out) ⇒ okhsl

Returns an Okhsl representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on Okhsv values and alpha.

Kind: static method of pex-color

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

pex-color.toOkhsv(color, out) ⇒ okhsv

Returns an Okhsv representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

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

Updates a color based on Oklab values and alpha.

Kind: static method of pex-color

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

pex-color.toOklab(color, out) ⇒ oklab

Returns an Oklab representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

pex-color.fromOklch(color, l, c, h, [a]) ⇒ color

Updates a color based on Oklch values and alpha.

Kind: static method of pex-color

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

pex-color.toOklch(color, out) ⇒ oklch

Returns an Oklch representation of a given color.

Kind: static method of pex-color

Param Type
color color
out Array

pex-color.fromP3(color, r, g, b, a) ⇒ color

Updates a color based on P3 values and alpha using D65 standard illuminant.

Kind: static method of pex-color

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

pex-color.toP3(color, out) ⇒ p3

Returns a P3 representation of a given color using D65 standard illuminant.

Kind: static method of pex-color

Param Type
color color
out Array

pex-color.fromXYZD50(color, x, y, z, a) ⇒ color

Updates a color based on XYZ values and alpha using D50 standard illuminant.

Kind: static method of pex-color

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

pex-color.toXYZD50(color, out) ⇒ xyz

Returns a XYZ representation of a given color using D50 standard illuminant.

Kind: static method of pex-color

Param Type
color color
out Array

pex-color.fromXYZD65(color, x, y, z, a) ⇒ color

Updates a color based on XYZ values and alpha using D65 standard illuminant.

Kind: static method of pex-color

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

pex-color.toXYZD65(color, out) ⇒ xyz

Returns a XYZ representation of a given color using D65 standard illuminant.

Kind: static method of pex-color

Param Type
color color
out Array

utils

utils.D65

Illuminant D65: x,y,z tristimulus values

Kind: static constant of utils See: https://en.wikipedia.org/wiki/Standard_illuminant#White_points_of_standard_illuminants

utils.D50

Illuminant D50: x,y,z tristimulus values

Kind: static constant of utils

utils.linearToSrgb(c) ⇒ number

Convert component from linear value

Kind: static method of utils

Param Type
c number

utils.srgbToLinear(c) ⇒ number

Convert component to linear value

Kind: static method of utils

Param Type
c number

utils.linearToRgb(lr, lg, lb, out) ⇒ color

Return a RGB representation from Linear values.

Kind: static method of utils

Param Type
lr number
lg number
lb number
out Array

utils.rgbToLinear(r, g, b, out) ⇒ linear

Return a Linear representation from RGB values.

Kind: static method of utils

Param Type
r number
g number
b number
out Array

utils.xyzD65ToLinear(x, y, z, out) ⇒ linear

Return a Linear representation from XYZ values with D65 illuminant.

Kind: static method of utils

Param Type
x number
y number
z number
out Array

utils.linearToXyzD65(lr, lg, lb, out) ⇒ xyz

Return a XYZ representation with D65 illuminant from Linear values.

Kind: static method of utils

Param Type
lr number
lg number
lb number
out Array

utils.xyzD50ToLinear(x, y, z, out) ⇒ linear

Return a Linear representation from XYZ values with D50 illuminant.

Kind: static method of utils

Param Type
x number
y number
z number
out Array

utils.linearToXyzD50(lr, lg, lb, out) ⇒ xyz

Return a XYZ representation with D50 illuminant from Linear values.

Kind: static method of utils

Param Type
lr number
lg number
lb number
out Array

utils.linearP3ToXyzD65(lr, lg, lb, out) ⇒ xyz

Return a XYZ representation with D65 illuminant from Linear P3 values.

Kind: static method of utils

Param Type
lr number
lg number
lb number
out Array

utils.xyzD65ToLinearP3(x, y, z, out) ⇒ Array

Return a Linear P3 representation from XYZ values with D65 illuminant.

Kind: static method of utils Returns: Array - P3 Linear

Param Type
x number
y number
z number
out Array

utils.lchToLab(l, c, h, out) ⇒ lab

Return a Lab representation from LCH values.

Kind: static method of utils

Param Type
l number
c number
h number
out Array

utils.labToLch(l, a, b, out) ⇒ lch

Return a Lch representation from Lab values.

Kind: static method of utils

Param Type
l number
a number
b number
out Array

utils.labToXyz(l, a, b, out, illuminant) ⇒ xyz

Return a XYZ representation from Lab values with provided illuminant.

Kind: static method of utils

Param Type
l number
a number
b number
out Array
illuminant Array

utils.xyzToLab(x, y, z, out, illuminant) ⇒ lab

Return a lab representation from XYZ values with provided illuminant.

Kind: static method of utils

Param Type
x number
y number
z number
out Array
illuminant Array

utils.oklabToLinear(L, a, b, out) ⇒ linear

Return a Linear representation from Oklab values.

Kind: static method of utils

Param Type
L number
a number
b number
out Array

utils.linearToOklab(lr, lg, lb, out) ⇒ oklab

Return a Oklab representation from Linear values.

Kind: static method of utils

Param Type
lr number
lg number
lb number
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 perceptual Lightness, a* red/green, b* blue/yellow.

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

lch : Array.<number>

CIELCh Luminance Chroma Hue. Cylindrical form of Lab.

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

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

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/#hsl-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

oklch : Array.<number>

Cylindrical form using D65 standard illuminant.

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

Kind: global typedef See: https://drafts.csswg.org/css-color/#color-conversion-code

p3 : Array.<number>

r, g, b values (DCI-P3 color gamut, D65 whitepoint, sRGB gamma curve).

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

Kind: global typedef See: https://drafts.csswg.org/css-color/#color-conversion-code

xyz : Array.<number>

CIE XYZ.

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.