color

Enum strings of types expected

There are 6 types of formats supported:

• HEX - 6 character hexadecimal colors as RRGGBB, like red for #ff0000
  • alternatively - 3 character hexadecimal colors #RGB are supported: like red for #F00
• HEXA - 8 character hexadecimal colors as RRGGBBAA, like red for #ff000080 with semi-transparency
  • alternatively - 4 character hexadecimal colors #RGBA are supported: #F008
• RGB - color with format rgb(RR,GG,BB) - like red for rgb(255,0,0)
• RGBA - RGB format with alpha: rgba(RR,GG,BB,AA) - like red for rgba(255,0,0,0.5) for semi-transparency
• ARRAY - 3 to 4 length array, with format: [r,g,b] or [r,g,b,a] - like red for [255,0,0] or [255,0,0,0.5] for semi-transparency
• OBJECT - objects with properties: r, g, b and optionally: a (the object is not modified and only those properties are checked)

For example:

baseColor = '#b1d1f3';

utils.color.convert(baseColor, utils.color.FORMATS.HEX); // '#b1d1f3'
utils.color.convert(baseColor, utils.color.FORMATS.HEXA); // #b1d1f3ff
utils.color.convert(baseColor, utils.color.FORMATS.RGB); // rgb( 177, 209, 243)
utils.color.convert(baseColor, utils.color.FORMATS.RGBA); // rgba(177, 209, 243, 1)
utils.color.convert(baseColor, utils.color.FORMATS.ARRAY); // [ 177, 209, 243, 1 ]
utils.color.convert(baseColor, utils.color.FORMATS.OBJECT); // { r: 177, g: 209, b: 243, a: 1 }

Different types of interpolation strategies:

• linear - linear interpolation between one value to another (straight line)
• easeInOut - slows in to the change and slows out near the end
• easeIn - slow then fast
• easeOut - fast then slow

Default format used when converting to types (allowing the conversion type to be optional)

baseColor = '#b1d1f3';
utils.color.defaultFormat = utils.color.FORMATS.RGBA;

utils.color.convert(baseColor); // rgba(177, 209, 243, 1)

Default interpolation strategy used when interpolating from one color to another.

(Defaults to linear)

For example, you can specify how you would like to interpolate and even which format you'd like to receive the results in.

//-- same as utils.color.INTERPOLATION_STRATEGIES.linear;
linear = (a, b, pct) => a + (b - a) * pct;
format = utils.color.FORMATS.ARRAY;
utils.color.interpolate(red, green, 0, linear, format); // [255, 0, 0, 1]

or instead, you can set this property and set the default

// or set the default
utils.color.interpolationStrategy = linear;
utils.color.defaultFormat = utils.color.FORMATS.ARRAY;

//-- note that the interpolation strategy or format isn't passed
utils.color.interpolate(red, green, 0.5); // [127.5, 127.5, 0, 1]

Parses a color of format rgba(r, g, b, a)

For example: rgba(255, 0, 0, 1) for a solid red, or rgba(255, 0, 0, 0.5) for a semi-transparent red

red = `rgba(255, 0, 0, 1)`;
transparentRed = `rgba(255, 0, 0, 0.5)`;
green = `rgb(0, 255, 0, 1)`;

//-- does not use the optionalAlpha, because the alpha was passed in the string
utils.color.parse(red, 0.9); // [255, 0, 0, 1];
utils.color.parse(transparentRed); // [255, 0, 0, 0.5];
utils.color.parse(green); // [0, 255, 0, 1];

Converts any of of the formats available, and converts it to any other format.

This is by far the most versatile.

red = '#FF000080';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

utils.color.convert(red, color.FORMATS.OBJECT); // { r: 255, g: 0, b: 0, a: 0.5 }
utils.color.convert(green, color.FORMATS.ARRAY); // [0, 255, 0, 0.5]
utils.color.convert(blue, color.FORMATS.HEXA); // `#0000FFFF`

NOTE: you can also set the default format on the color utility, so you don't have to specify the format each time.

red = '#FF000080';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

//-- converts to hex because color.defaultFormat is set to hex by default
utils.color.convert(red); // #FF000080

utils.color.defaultFormat = utils.color.FORMATS.ARRAY
utils.color.convert(green); // [0, 255, 0, 0.5]
utils.color.convert(blue); // [0, 0, 255, 1]

Generates a sequential array of colors interpolating fromColor to toColor,

black = `#000000`;
white = `#FFFFFF`;

categoricalColors = utils.color.generateSequence(black, white, 5);
// [' #000000' ,' #404040' ,' #808080' ,' #bfbfbf' ,' #ffffff' ]

Interpolates from one color to another color, by a percentage (from 0-1)

red = `#FF0000`;
green = `#00FF00`;

utils.color.interpolate(red, green, 0); // `#FF0000`
utils.color.interpolate(red, green, 0.5); // `#808000`
utils.color.interpolate(red, green, 1); // `#00FF00`

You can also specify how you would like to interpolate and even which format you'd like to receive the results in.

//-- same as utils.color.INTERPOLATION_STRATEGIES.linear;
linear = (a, b, pct) => a + (b - a) * pct;
format = utils.color.FORMATS.ARRAY;

utils.color.interpolate(red, green, 0, linear, format); // [255, 0, 0, 1]

// or set the default
utils.color.interpolationStrategy = linear;
utils.color.defaultFormat = utils.color.FORMATS.ARRAY;

utils.color.interpolate(red, green, 0.5); // [127.5, 127.5, 0, 1]

Curried function for color interpolation, so only the percent between [0-1] inclusive is needed.

Meaning that you can do something like this:

black = `#000000`;
white = `#FFFFFF`;

colorFn = utils.color.interpolator(black, white);

colorFn(0);   // '#000000';
colorFn(0.5); // '#808080';
colorFn(1);   // '#FFFFFF;

Instead of something like this with the interpolate function

utils.color.interpolate(black, white, 0); // `#000000`
utils.color.interpolate(black, white, 0.5); // `#808080`
utils.color.interpolate(black, white, 1); // `#FFFFFF`

Pareses any of the types of available formats, and returns an array.

There are 6 types of formats supported:

• Hex - 6-8 character hexadecimal colors as RRGGBB or RRGGBBAA, like red for #ff0000 or #ff000080 for semi-transparency
• Hex3 - 3-4 character hexadecimal colors: RGB or RGBA, like red for #F00 or #F008 for semi-transparency
• RGB - color with format rgb(RR,GG,BB) - like red for rgb(255,0,0)
• RGBA - RGB format with alpha: rgba(RR,GG,BB,AA) - like red for rgba(255,0,0,0.5) for semi-transparency
• ARRAY - 3 to 4 length array, with format: [r,g,b] or [r,g,b,a] - like red for [255,0,0] or [255,0,0,0.5] for semi-transparency
• OBJECT - objects with properties: r, g, b and optionally: a (the object is not modified and only those properties are checked)

by passing a value of any of those types, they will be recognized and parsed accordingly.

The result array format is an array 3 or 4 length array of numbers, in format of [Red:Number[0-255], Green:Number[0-255], Blue:Number[0-255], Alpha:Number[0-1]]

red = '#FF000088';
green = { r: 0, g: 255, b: 0};
blue = 'rgb(0, 0, 255, 1)';

utils.color.parse(red); // [255, 0, 0, 128]
utils.color.parse(green); // [0, 255, 0, 1]
utils.color.parse(blue); // [0, 0, 255, 1]

Parses a 3 or 4 length array of numbers, in format of [Red:Number[0-255], Green:Number[0-255], Blue:Number[0-255], Alpha:Number[0-1]]

For example: [255, 0, 0] for Red, or [255, 0, 0, 0.5] for a semi-transparent red

red = [255, 0, 0];
transparentRed = [255, 0, 0, 0];
green = [0, 255, 0];

utils.color.parseColorArray(red, 0.5); // [255, 0, 0, 0.5];
utils.color.parseColorArray(transparentRed); // [255, 0, 0, 0];
utils.color.parseColorArray(green); // [0, 255, 0, 1];

Captures properties: r:Number[0-255], g:Number[0-255], b:Number[0-255], a:Number[0-1] from an object.

Only those properties are checked and the object is not modified

For example: { r: 255, g: 0, b: 0} for Red or { r: 255, g: 0, b: 0, a: 0.5 } for a semi-transparent red

red = { r: 255, g: 0, b: 0 };
green = { r: 0, g: 255, b: 0, a: 1};
transparentBlue: { r: 0, g: 0, b: 255, a: 0};

utils.color.parseColorObject(red, 0.5); // [255, 0, 0, 0.5];
utils.color.parseColorObject(red); // [255, 0, 0, 1];
utils.color.parseColorObject(green); // [0, 255, 0, 1];
utils.color.parseColorObject(transparentBlue); // [0, 0, 255, 0];

Parses a 6 or 8 character Hexadecimal color.

For example: #FF0000 for Red or #FF000080 for semi-transparent red.

red = `#FF0000`;
transparentRed = `#FF0000FF`;
green = `#00FF00`;

utils.color.parseHex(red, 0.5); // [255, 0, 0, 0.5];
utils.color.parseHex(transparenRed); // [255, 0, 0, 1];
utils.color.parseHex(green); // [0, 255, 0, 1];

Parses a 3-4 character Hexadecimal color.

For example: #F00 for Red or #F008 for semi-transparent red.

red = `#F00`;
transparentRed = `#F00F`;
green = `#0F0`;

utils.color.parseHex(red, 0.5); // [255, 0, 0, 0.5];
utils.color.parseHex(transparenRed); // [255, 0, 0, 1];
utils.color.parseHex(green); // [0, 255, 0, 1];

Parses a color of format rgb(r, g, b)

For example: rgb(255, 0, 0) for Red

red = `rgb(255, 0, 0, 1)`;
green = `rgb(0, 255, 0)`;

utils.color.parse(red, 0.9); // [255, 0, 0, 0.9];
utils.color.parse(green); // [0, 255, 0, 1];

Converts any of of the formats available, and converts it into a - array of format [r:Number[0-255], g: Number[0-255], b: Number[0-255], a: Number[0-1]]

red = '#FF000080';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

utils.color.toColorArray(red); // [255, 0, 0, 0.5]
utils.color.toColorArray(green); // [0, 255, 0, 0.5]
utils.color.toColorArray(blue); // [0, 0, 255, 1]

Converts any of of the formats available, and converts it into an object with the following properties:

Object { r: Number[0-255], g: Number[0-255], b: Number[0-255], a: Number[0-1]] }

red = '#FF000080';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

utils.color.toColorObject(red); // { r: 255, g: 0, b: 0, a: 0.5 }
utils.color.toColorObject(green); // { r: 0, g: 255, b: 0, a: 0.5 }
utils.color.toColorObject(blue); // { r: 0, g: 0, b: 255, a: 1 }

Converts any of of the formats available, and converts it into a 6 character hexadecimal string (no alpha)

red = '#FF000088';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

utils.color.toHex(red); // `#FF0000`
utils.color.toHex(green); // `#00FF00`
utils.color.toHex(blue); // `#0000FF`

Converts any of of the formats available, and converts it into a 8 character hexadecimal string with alpha

red = '#FF000088';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

utils.color.toHexA(red); // `#FF000088`
utils.color.toHexA(green); // `#00FF0080`
utils.color.toHexA(blue); // `#0000FFFF`

Converts any of of the formats available, and converts it into a an rgb string (no alpha)

red = '#FF000088';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

utils.color.toHex(red); // `rgb(255, 0, 0)`
utils.color.toHex(green); // `rgb(0, 255, 0)`
utils.color.toHex(blue); // `rgb(0, 0, 255)`

Converts any of of the formats available, and converts it into a an rgba string (includes alpha)

red = '#FF000080';
green = { r: 0, g: 255, b: 0, a: 0.5};
blue = 'rgb(0, 0, 255, 1)';

utils.color.toRGBA(red); // `rgba(255, 0, 0, 0.5)`
utils.color.toRGBA(green); // `rgba(0, 255, 0, 0.5)`
utils.color.toRGBA(blue); // `rgba(0, 0, 255, 1)`