@creenv/color v1.2.0

@creenv/color

The color class was designed to fasten the usage of colors and operations over colors. It is recommended to use such a class within the Creative Environement @creenv.

Why should you use Color inside @creenv

If you're not interested into the why, you can directly jump to the next question :)

The Color class extends the @creenv/vector Vector class, which means any operations over the vectors can be applied between colors. However, you may want to be carefull with the alpha channel. It is stored as a regular component, so operations could alter it's value. This is probably a design issue and will change in the future.

APRES LE CALL DE SUPER(), FAIRE .DIMENSIONS=3 ?

While using the Creative Environment and some of its modules, using the Color class will allow other components to process the data faster. For instance, if you provide a Color object to a controller of @creenv/gui GUI, it will automatically understand that this is a color provided, and will not have to execute computations to understand if weither a string #040404 is a color or not.

Moreover, it gives you the ability, for a given color, to be used in many different manners without the need of transformations. If you want to change the active color of the native canvas API, just do like so:

let color = new Color(255,55,20);
context.fillStyle = color.string;

You may think it is fastidious, but trust me, in the end it is not. How many times did I have to transform a 3d array into a css compliant string ? vice-versa ? The answer is too many times. By storing and manipulating the Colors using one and only way, and because such a way provides fast call to transform the data into other forms, you won't need to wrap your head arround stupid questions such as "shall i store my colors as a 3d array ? 4d array ? wait, I could only leave it as a string since i'm not going to make operations over it ? or maybe will I afterwards ?...

How to use

These are quick examples on how to use Color. If you need more informations full doc is below.

// instanciation 
let color = new Color(255, 0, 255); // magenta 

// some getters 
console.log(color.components); // ouput: [255, 0, 255, 1.0]
console.log(color.rgb); // output: [255, 0, 255]
console.log(color.hex); // output: #ff00ff
console.log(color.g); // ouput: 0

color.r = 0;
console.log(color.components): // output: [0, 0, 255, 1.0]

color.invert(); // color.components: [0, 255, 0]

// conversion
let color;
color = Color.fromString("#f5336f");
color = Color.fromString("rgba(245,51,111,1.0)");
color = Color.fromArray([245,51,111]);
color = Color.fromHSL(341,0.91,0.58);
color = Color.fromHSV(320,0.50,0.40);

How is the color stored

The components are stored in a 4 dimensions array r; g; b; a. Operations are only performed over this array, whose values can be retrived using such as .r, .rgb or .string.

Full doc

Following is a full list of Color available members and methods.

Inherits @creenv/vector - all Vector members and methods are accessbile

constructor (red: number, green: number: blue: number, alpha: number)

Class members

Class getters / setters

let color = new Color(255,255,255,1.0);

console.log(color.hex); // #ffffff
console.log(color.string); // rgba(255,255,255,1.0)
color.g = 0;
console.log(color.rgb); // [255,0,255]
console.log(color.hsl); // [300, 100, 0.5]

static fromHSL (h: number, s: number, l: number): Color

Returns a new Color, with rgb components, given the HSL components in arguments.

// example 
let color = Color.fromHSL(341,0.91,0.58); // arround [245, 50, 112, 1]

static fromHSV (h: number, s: number, v: number)

Returns a new Color, with rgb components, given the HSV components in arguments.

// example 
let color = Color.fromHSV(320,0.50,0.40); // arround [102, 51, 85, 1]

static fromString (colorString)

Returns a new Color from any css compliant string. W3C color specs

// example 
let color = Color.fromString("#f5336f");
let color = Color.fromString("rgb(25, 50, 30");

static fromColor (color)

Returns a new Color which components are the same as the color argument. #Duplicate of color.copy()

// example
let red = new Color(255,0,0);
let red2 = Color.fromColor(red); // [255, 0, 0, 1]

static fromArray (components)

Returns a new color, from an array of 3 or 4 components, r, g, b, ?a.

// example
let color = Color.fromArray([25, 50, 78, 0.8]);

toArray ()

Returns the components of the color as an array of 4 components, #Duplicate of color.rgba and color.components. color.components is the fastest.

toObject ()

Returns the color as a key value Object, {r: red, g: green, b: blue, a: alpha}

rounded ()

Returns a new Color which as the same components, but rounded.

// example 
let color = new Color(212.48, 78.458, 74.51, 0.78);
let c2 = color.rounded();

console.log(color.components); // expected output: [212.48, 78.458, 74.51, 0.78]
console.log(c2.components); // expected output: [212, 75, 75, 0.78]

apply (func, alpha = false)

Applies a function func to all the components of the color, except alpha if alpha argument is set to false.

@Returns this, can be used to chain operations

// example
let color = new Color(25.5, 30.75, 19.99, 0.55);
color.apply(Math.floor);

console.log(color); // expected output: [25, 30, 19, 0.55]

convert (Class, func = x => x)

Converts the Color class to any other Class which accepts 4 arguments: red, green, blue, alpha. Can be useful if a tierce library only accepts its own Classes. If specified, the function func will be applied to all the components.

// example
let color = new Color(14, 15, 150);

import Vector3 from "three"; // for the example we'll import vector3 from three js

let vect = color.convert(Vector3); // same as new Vector3(color.r, color.g, color.b);

interpolateWith (endColor, t)

Linear interpolation of all the components between this and endColor, t in range of 0;1

@Returns this, can be used to chain operations

// example 
let c1 = new Color(0,0,0);
let c2 = new Color(255,255,255);
c1.interpolateWith(c2, 0.5);

console.log(c1.components); // expected ouput: [128, 128, 128, 1]

invert ()

Inversion of all the components of the color but alpha

@Returns this, can be used to chain operations

// example 
let c1 = new Color(0,0,0);
c1.invert();
console.log(cA.components); // expected ouput: [255,255,255, 1]

grayscale ()

Applies a grayscale to the color. The result is the average of the r; g; b components.

grayscaleLuminance ()

Computes the grayscale value fo the color, using the grayscale luminance formula grayscale = (Red 0.2126 + Green 0.7152 + Blue * 0.0722)

grayscaleFastest ()

This should only be used if a fast result is desired. Set the value of the red and blue components equals to the green components. Innacurate but fast.

relativeLuminance ()

Computes the relative luminance of the color.

contrastWith (color)

Computes the contrast with color.