JSPM

Note that this package is still in ealy version 0.x.x so you should expect some changes that break backward compatibility.

Change history

• 0.4.0 ColorUtil.any conversion functions. Hue range changed to 0-1. Convert function can convert single color. RgbString spaces allowed. HslString conversion functions. RgbString regexp fixed. Rounding removed when converting to Rgb object.
• 0.3.0 Rgb -> Hsv -> Rgb, fix rgb.toHsl conversion negative hue value
• 0.2.0 Rgb -> Hsl -> Rgb, backward compatibility broken (e.g. ColorUtil.obj -> ColorUtil.rgb)
• 0.1.2 Rgb color conversion functions, gradient and gradient matrix

ColorUtil

Color conversion functions and gradient functions.

Kind: global class

• ColorUtil
  • .rgb
    • .test(color) ⇒ boolean
    • .toInt(rgb) ⇒ number
    • .toHex(rgb) ⇒ string
    • .toRgbString(rgb) ⇒ string
    • .toUint32(rgb) ⇒ number
    • .toInt32(rgb) ⇒ number
    • .toHsl(rgb) ⇒ object
    • .toHsv(rgb) ⇒ object
  • .int
    • .test(color) ⇒ boolean
    • .toRgb(int, [a]) ⇒ object
    • .toHex(int) ⇒ string
    • .toRgbString(int, [a]) ⇒ string
  • .hex
    • .test(color) ⇒ boolean
    • .toRgb(hex, [a]) ⇒ object
    • .toInt(hex) ⇒ number
    • .toRgbString(hex, [a]) ⇒ string
  • .rgbString
    • .test(color) ⇒ boolean
    • .toRgb(rgba) ⇒ object
    • .toInt(rgba) ⇒ number
    • .toHex(rgba) ⇒ string
  • .hsl
    • .test(color) ⇒ boolean
    • .toRgb(hsl) ⇒ object
    • .toHsv(hsl) ⇒ object
    • .toHslString(hsl) ⇒ string
  • .hslString
    • .test(color) ⇒ boolean
    • .toHsl(hsla) ⇒ object
  • .hsv
    • .test(color) ⇒ boolean
    • .toRgb(hsv) ⇒ object
    • .toHsl(hsl) ⇒ object
  • .any
    • .toRgb(color) ⇒ object
    • .toInt(color) ⇒ object
    • .toHex(color) ⇒ object
    • .toRgbString(color) ⇒ object
    • .toHsl(color) ⇒ object
    • .toHsv(color) ⇒ object
  • .hueColors ⇒ array
  • .getSystemEndian() ⇒ number
  • .convert(colors, ...conversionFunctions) ⇒ array
  • .convertTo2StopGradient(array, position) ⇒ object
  • .getGradientColor(colors, position, [convertToRgb], [convertFromRgb]) ⇒ *
  • .getGradientMatrixColor(matrix, x, y, [convertToRgb], [convertFromRgb]) ⇒ *

ColorUtil.rgb

Rgb conversion functions

Rgb object notation is {r:RRR, g:GGG, b:BBB, a:AAA} where each color component (red, grean, blue, alpha) range is 0-255. In some conversion functions alpha is not required. In those where it is required and not present in rgb object, a fully opaque value is used as a default.

Kind: static property of ColorUtil

• .rgb
  • .test(color) ⇒ boolean
  • .toInt(rgb) ⇒ number
  • .toHex(rgb) ⇒ string
  • .toRgbString(rgb) ⇒ string
  • .toUint32(rgb) ⇒ number
  • .toInt32(rgb) ⇒ number
  • .toHsl(rgb) ⇒ object
  • .toHsv(rgb) ⇒ object

rgb.test(color) ⇒ boolean

Test validity of a color whether it is in correct notation for this class.

Kind: static method of rgb
Returns: boolean - True if valid, False otherwise.

rgb.toInt(rgb) ⇒ number

Convert rgb object {r:RRR, g:GGG, b:BBB, a:AAA} to 24-bit number 0xRRGGBB. Alpha is ignored.

Kind: static method of rgb

Example

ColorUtil.rgb.toInt({r: 0, g: 128, b: 255});
// output: 33023

rgb.toHex(rgb) ⇒ string

Convert rgb object {r:RRR, g:GGG, b:BBB, a:AAA} to 24-bit hex string '#RRGGBB'. Alpha is ignored.

Kind: static method of rgb

Example

ColorUtil.rgb.toHex({r: 0, g: 128, b: 255});
// output: "#0080ff"

rgb.toRgbString(rgb) ⇒ string

Convert rgb object {r:RRR, g:GGG, b:BBB, a:AAA} to rgb functional notation string 'rgba(RRR,GGG,BBB,A)'. Alpha is converted from range 0-255 to 0-1. Default alpha value is 1.

Kind: static method of rgb

Example

ColorUtil.rgb.toRgbString({r: 0, g: 128, b: 255});
// output: "rgba(0,128,255,1)"
ColorUtil.rgb.toRgbString({r: 0, g: 128, b: 255, a: 85});
// output: "rgba(0,128,255,0.3333333333333333)"

rgb.toUint32(rgb) ⇒ number

Convert rgb object {r:RRR, g:GGG, b:BBB, a:AAA} to 32-bit number 0xAABBGGRR in little-endian, 0xRRGGBBAA in big-endian. Default alpha value is 255. Resulting value is positive

Kind: static method of rgb

Example

ColorUtil.rgb.toUint32({r: 0, g: 128, b: 255, a: 255});
// output: 4294934528
ColorUtil.rgb.toUint32({r: 0, g: 128, b: 255, a: 85});
// output: 1442807808

rgb.toInt32(rgb) ⇒ number

Convert rgb object {r:RRR, g:GGG, b:BBB, a:AAA} to 32-bit number 0xAABBGGRR in little-endian, 0xRRGGBBAA in big-endian. Default alpha value is 255. Resulting value can be negative

Kind: static method of rgb

Example

ColorUtil.rgb.toInt32({r: 0, g: 128, b: 255, a: 255});
// output: -32768
ColorUtil.rgb.toInt32({r: 0, g: 128, b: 255, a: 85});
// output: 1442807808

rgb.toHsl(rgb) ⇒ object

Convert rgb object {r:RRR, g:GGG, b:BBB, a:AAA} to hsl object {h:H, s:S, l:L, a:A} where h, s, l, a (saturation, luminosity, alpha) are in range 0-1.

Kind: static method of rgb

Example

ColorUtil.rgb.toHsl({r: 255, g: 0, b: 0, a: 255});
// output: {h: 0, s: 1, l: 0.5, a: 1}

rgb.toHsv(rgb) ⇒ object

Convert rgb object {r:RRR, g:GGG, b:BBB, a:AAA} to hsv object {h:H, s:S, v:V, a:A} where h, s, v, a (hue, saturation, value, alpha) are in range 0-1.

Kind: static method of rgb

Example

ColorUtil.rgb.toHsv({r: 255, g: 0, b: 0, a: 255});
// output: {h: 0, s: 1, v: 1, a: 1}

ColorUtil.int

Integer conversion functions.

Int notation is 24-bit number represnting the RGB values 0xRRGGBB.

Kind: static property of ColorUtil

• .int
  • .test(color) ⇒ boolean
  • .toRgb(int, [a]) ⇒ object
  • .toHex(int) ⇒ string
  • .toRgbString(int, [a]) ⇒ string

int.test(color) ⇒ boolean

Test validity of a color whether it is in correct notation for this class.

Kind: static method of int
Returns: boolean - True if valid, False otherwise.

int.toRgb(int, [a]) ⇒ object

24-bit number 0xRRGGBB to rgb {r:RRR, g:GGG, b:BBB, a:AAA}

Kind: static method of int

Example

ColorUtil.int.toRgb(0xFF0000);
// output: {r: 255, g: 0, b: 0, a: 255}

ColorUtil.int.toRgb(0xFF0000, 128);
// output: {r: 255, g: 0, b: 0, a: 128}

int.toHex(int) ⇒ string

24-bit number 0xRRGGBB to 24-bit hex string '#RRGGBB'.

Kind: static method of int

Example

ColorUtil.int.toHex(0x00FF00);
// output: "#00ff00"

int.toRgbString(int, [a]) ⇒ string

24-bit number 0xRRGGBB to rgb functional notation string 'rgba(RRR,GGG,BBB,A)'

Kind: static method of int

Example

ColorUtil.int.toRgbString(0x00FF00);
// output: "rgba(0,255,0,1)"

ColorUtil.int.toRgbString(0x00FF00, 0.5);
// output: "rgba(0,255,0,0.5)"

ColorUtil.hex

Hexadecimal conversion functions

Hex notation is 24-bit hex string represnting the RGB values '#RRGGBB'.

Kind: static property of ColorUtil

• .hex
  • .test(color) ⇒ boolean
  • .toRgb(hex, [a]) ⇒ object
  • .toInt(hex) ⇒ number
  • .toRgbString(hex, [a]) ⇒ string

hex.test(color) ⇒ boolean

Test validity of a color whether it is in correct notation for this class.

Kind: static method of hex
Returns: boolean - True if valid, False otherwise.

hex.toRgb(hex, [a]) ⇒ object

24-bit hex string '#RRGGBB' to rgb object {r:RRR, g:GGG, b:BBB, a:AAA}

Kind: static method of hex

Example

ColorUtil.hex.toRgb('#00FF00');
// output: {r: 0, g: 255, b: 0, a: 255}
ColorUtil.hex.toRgb('#00FF00', 127);
// output: {r: 0, g: 255, b: 0, a: 127}

hex.toInt(hex) ⇒ number

24-bit hex string '#RRGGBB' to 24-bit integer 0xRRGGBB

Kind: static method of hex

Example

ColorUtil.hex.toInt('#00FF00');
// output: 65280

hex.toRgbString(hex, [a]) ⇒ string

24-bit hex string '#RRGGBB' to rgb functional notation string 'rgba(RRR,GGG,BBB,A)'

Kind: static method of hex

Example

ColorUtil.hex.toRgbString('#00FF00')
// output: "rgba(0,255,0,1)"

ColorUtil.hex.toRgbString('#00FF00', 0.5)
// output: "rgba(0,255,0,0.5)"

ColorUtil.rgbString

RgbString conversion functions

RgbString notation is 'rgba(RRR,GGG,BBB[,A])'

Kind: static property of ColorUtil

• .rgbString
  • .test(color) ⇒ boolean
  • .toRgb(rgba) ⇒ object
  • .toInt(rgba) ⇒ number
  • .toHex(rgba) ⇒ string

rgbString.test(color) ⇒ boolean

Test validity of a color whether it is in correct notation for this class.

Kind: static method of rgbString
Returns: boolean - True if valid, False otherwise.

rgbString.toRgb(rgba) ⇒ object

Rgb functional notation string 'rgba(RRR,GGG,BBB[,A])' to rgb object {r:RRR, g:GGG, b:BBB, a:AAA}

Kind: static method of rgbString

Example

ColorUtil.rgbString.toRgb('rgba(0,255,0,0.5)')
// output: {r: 0, g: 255, b: 0, a: 127}

rgbString.toInt(rgba) ⇒ number

Rgba functional notation string 'rgba(RRR,GGG,BBB[,A])' to 24-bit integer 0xRRGGBB. Alpha is ignored.

Kind: static method of rgbString

Example

ColorUtil.rgbString.toInt('rgba(0,255,0,0.5)')
// output: 65280

rgbString.toHex(rgba) ⇒ string

Rgba functional notation string 'rgba(RRR,GGG,BBB[,A])' to hexadecimal string '#RRGGBB'. Alpha is ignored.

Kind: static method of rgbString

Example

ColorUtil.rgbString.toHex('rgba(0,255,0,0.5)')
// output: "#00ff00"

ColorUtil.hsl

Hsl conversion functions

Hsl notation is {h:H, s:S, l:L, a:A} where each component (hue, saturation, luminosity, alpha) is in range 0-1.

Kind: static property of ColorUtil

• .hsl
  • .test(color) ⇒ boolean
  • .toRgb(hsl) ⇒ object
  • .toHsv(hsl) ⇒ object
  • .toHslString(hsl) ⇒ string

hsl.test(color) ⇒ boolean

Test validity of a color whether it is in correct notation for this class.

Kind: static method of hsl
Returns: boolean - True if valid, False otherwise.

hsl.toRgb(hsl) ⇒ object

Hsl object {h:H, s:S, l:L, a:A} to rgb object {r:RRR, g:GGG, b:BBB, a:AAA}

Kind: static method of hsl

Example

ColorUtil.hsl.toRgb({h: 1/6, s: 0.5, l: 0.5});
// output: {r: 191, g: 191, b: 64, a: 255}

ColorUtil.hsl.toRgb({h: 1/6, s: 0.5, l: 0.5, a: 0.5});
// output: {r: 191, g: 191, b: 64, a: 128}

hsl.toHsv(hsl) ⇒ object

Hsl object {h:H, s:S, l:L, a:A} to hsv object {h:H, s:S, v:V, a:A}

Kind: static method of hsl

Example

ColorUtil.hsl.toHsv({h: 1/6, s: 0.5, l: 0.5});
// output: {h: 0.16666666666666666, s: 0.6666666666666666, v: 0.75, a: 1}

hsl.toHslString(hsl) ⇒ string

Convert hsl object {h:H, s:S, l:L, a:A} to hsl functional notation string 'hsla(HHH,SSS%,LLL%[,A])'. Default alpha value is 1.

Kind: static method of hsl

Example

ColorUtil.hsl.toHslString({h:2/6, s:0.5, l:0.5});
// output: "hsla(120,50%,50%,1)"

ColorUtil.hsl.toHslString({h:2/6, s:0.5, l:0.5, a:0.5});
// output: "hsla(120,50%,50%,0.5)"

ColorUtil.hslString

HslString conversion functions

Hsl functional notation is 'hsla(HHH,SSS%,LLL%[,A])'

Kind: static property of ColorUtil

• .hslString
  • .test(color) ⇒ boolean
  • .toHsl(hsla) ⇒ object

hslString.test(color) ⇒ boolean

Test validity of a color whether it is in correct notation for this class.

Kind: static method of hslString
Returns: boolean - True if valid, False otherwise.

hslString.toHsl(hsla) ⇒ object

Hsl functional notation string 'hsla(HHH,SSS%,LLL%[,A])' to hsl object {h:H, s:S, l:L, a:A}

Kind: static method of hslString

Example

ColorUtil.hslString.toHsl('hsla(180, 50%, 60%, 0.5)');
// output: {h: 0.5, s: 0.5, l: 0.6, a: 0.5}

ColorUtil.hsv

Hsv conversion functions

Hsv notation is {h:H, s:S, v:V, a:A} where each component (hue, saturation, value, alpha) are in range 0-1.

Kind: static property of ColorUtil

• .hsv
  • .test(color) ⇒ boolean
  • .toRgb(hsv) ⇒ object
  • .toHsl(hsl) ⇒ object

hsv.test(color) ⇒ boolean

Test validity of a color whether it is in correct notation for this class.

Kind: static method of hsv
Returns: boolean - True if valid, False otherwise.

hsv.toRgb(hsv) ⇒ object

Hsv object {h:H, s:S, v:V, a:A} to rgb object {r:RRR, g:GGG, b:BBB, a:AAA}

Kind: static method of hsv

Example

ColorUtil.hsv.toRgb({h: 0, s: 1, v: 1});
// output: {r: 255, g: 0, b: 0, a: 255}
ColorUtil.hsv.toRgb({h: 0, s: 1, v: 1, a: 0.5});
// output: {r: 255, g: 0, b: 0, a: 128}

hsv.toHsl(hsl) ⇒ object

Hsv object {h:H, s:S, v:V, a:A} to hsl object {h:H, s:S, l:L, a:A}

Kind: static method of hsv

Example

ColorUtil.hsv.toHsl({h: 1/6, s: 0.5, v: 0.5});
// output: {h: 0.16666666666666666, s: 0.3333333333333333, l: 0.375, a: 1}

ColorUtil.any

Any conversion functions.

Converts supported color notations to any notation.

TODO: toUint32, toInt32

Kind: static property of ColorUtil

• .any
  • .toRgb(color) ⇒ object
  • .toInt(color) ⇒ object
  • .toHex(color) ⇒ object
  • .toRgbString(color) ⇒ object
  • .toHsl(color) ⇒ object
  • .toHsv(color) ⇒ object

any.toRgb(color) ⇒ object

Convert any color to rgb object notation {r:RRR, g:GGG, b:BBB, a:AAA}

Kind: static method of any

Example

ColorUtil.any.toRgb(0xFF0000);
// output: {r: 255, g: 0, b: 0, a: 255}

ColorUtil.any.toRgb({h: 1/6, s: 0.5, l: 0.5});
// output: {r: 191, g: 191, b: 64, a: 255}

any.toInt(color) ⇒ object

Convert any color to number notation 0xRRGGBB

Kind: static method of any

Example

ColorUtil.any.toInt('hsl(180, 50%, 60%)')
// output: 6737100

any.toHex(color) ⇒ object

Convert any color to hex notation '#RRGGBB'

Kind: static method of any

Example

ColorUtil.any.toHex('hsl(180, 50%, 60%)')
// output: "#66cccc"

any.toRgbString(color) ⇒ object

Convert any color to rgb functional notation 'rgba(RRR,GGG,BBB,A)'

Kind: static method of any

Example

ColorUtil.any.toRgbString('hsl(180, 50%, 60%)')
// output: "rgba(102,204,204,1)"

any.toHsl(color) ⇒ object

Convert any color to hsl object notation {h:H, s:S, v:V, a:A}

Kind: static method of any

Example

ColorUtil.any.toHsl('hsl(180, 50%, 60%)')
// output: {h: 0.5, s: 0.5, l: 0.6, a: 1}

any.toHsv(color) ⇒ object

Convert any color to hsv object notation {h:H, s:S, v:V, a:A}

Kind: static method of any

Example

ColorUtil.any.toHsl('hsl(180, 50%, 60%)')
// output: {h: 0.5, s: 0.5, l: 0.6, a: 1}

ColorUtil.hueColors ⇒ array

Kind: static property of ColorUtil
Returns: array - Array of hue colors

ColorUtil.getSystemEndian() ⇒ number

Get the endian used by the system.

https://developer.mozilla.org/en-US/docs/Glossary/Endianness

Kind: static method of ColorUtil
Returns: number - 0=little-endian, 1=big-endian, 2=unknown-endian

ColorUtil.convert(colors, ...conversionFunctions) ⇒ array

Run conversion functions for single color, array of colors or matrix of colors.

Kind: static method of ColorUtil

Example

ColorUtil.convert(0xFF0000, ColorUtil.int.toHex);
// output: "#ff0000"

ColorUtil.convert([0xFF0000, 0x00FF00], ColorUtil.int.toHex);
// output: ["#ff0000", "#00ff00"]

ColorUtil.convert([[0xFF0000, 0x00FF00], 0x0000FF], ColorUtil.int.toHex);
// output: [['#ff0000', '#00ff00'], '#0000ff']

ColorUtil.convert([[0xFF0000, 0x00FF00], 0x0000FF], ColorUtil.int.toHex, ColorUtil.hex.toRgbString);
// output: [['rgba(255,0,0,1)', 'rgba(0,255,0,1)'], 'rgba(0,0,255,1)']

ColorUtil.convertTo2StopGradient(array, position) ⇒ object

Calculate two items from a gradient array and a relative position of the gradient between those two items in an evenly distributed gradient. The resulting values can be used calculate the final color.

Kind: static method of ColorUtil
Returns: object - Relative position between two items and two items from gradient array which are the closest to the point indicated by position argument

Example

// The example position 0.25 is in the middle of the first and
// second colors so new 2 point gradient array contains only those
// first and second colors. The given absolute position 0.25 is relatively
// 0.5 between those two values.
ColorUtil.convertTo2StopGradient([0xFF0000, 0x00FF00, 0x0000FF], 0.25);
// output: {array: [0xFF0000, 0x00FF00], position: 0.5}

ColorUtil.getGradientColor(colors, position, [convertToRgb], [convertFromRgb]) ⇒ *

Get color from gradient.

Gradient calculation is done in rgb object notation so convertToRgb must convert to rgb object and convertFromRgb must convert from rgb object type. In case colors are preformatted to rgb object, convertToRgb conversion is not needed. Similarly if rgb object notation is the desired output then convertFromRgb is not needed. In this case set null in place for the conversion function.

Kind: static method of ColorUtil
Returns: * - Return value depend on the what has been set to convertFromRgb.

Example

let gradient = [0xFF0000, 0x00FF00, 0x0000FF];
ColorUtil.getGradientColor(gradient, 0.5, ColorUtil.int.toRgb, ColorUtil.rgb.toHex);
// output: "#00ff00"

gradient = ColorUtil.convert(gradient, ColorUtil.int.toRgb)
ColorUtil.getGradientColor(gradient, 0.5, null, ColorUtil.rgb.toHex);
// output: "#00ff00"

ColorUtil.getGradientMatrixColor(matrix, x, y, [convertToRgb], [convertFromRgb]) ⇒ *

Get color from gradient matrix. Gradient matrix is like normal gradient but it is two dimensional.

Gradient calculation is done in rgb object notation so convertToRgb must convert to rgb object and convertFromRgb must convert from rgb object type. In case colors are preformatted to rgb object, convertToRgb conversion is not needed. Similarly if rgb object notation is the desired output then convertFromRgb is not needed. In this case set null in place for the conversion function.

Kind: static method of ColorUtil

Example

let matrix = [[0xFF0000, 0x00FF00], [0x0000FF]];
ColorUtil.getGradientMatrixColor(matrix, 0.5, 0.5, ColorUtil.int.toRgb, ColorUtil.rgb.toHex);
// output: "#3f3f7f"

matrix = ColorUtil.convert(matrix, ColorUtil.int.toRgb)
ColorUtil.getGradientMatrixColor(matrix, 0.5, 0.5, null, ColorUtil.rgb.toHex);
// output: "#3f3f7f"