ColorMix Library

ColorMix.js

A javascript library for mixing, blending and easily manipulating colors and color spaces [Hex, RGB, XYZ, HSL, Lab].

The mixing methods are using the Lab color space.
This color space is designed to approximate the human vision, that's why a Lab mix is closer to our vision than a RGB mix.

It means that your colors will first be converted to this schema, what can be a bit heavy / slow if you use it inside an interval as requestAnimationFrame.

Okay, and technically ?

ColorMix is a global JS singleton object, so accessible from anywhere.
It contains some direct methods to mix several colors, get and set up a custom colors gradient, and blend a reference in this gradient.
It contains also two subclasses:

ColorMix.Color() - A class to easily manipulating colors
ColorMix.ColorSpace - A singleton to easily convert colors into different color spaces.

Watch the documentation below for more informations !

Is it free ?

Sure! And open-sourced on GitHub. Feel free to star or fork. Pull-requests are welcome!

Do you find it usefull ?

Just send me your feedbacks!

And if you really like it, you can also

How to implement it ?

Include the library in your HTML page or template.

Note - It is recommended to use it with jQuery, however it is not required

<!DOCTYPE html>
<head>
	[...]
</head>
<body>
	[...]
	<script src='/path/to/your/scripts/jquery-1.9.1.min.js'></script>
	<script src='/path/to/your/scripts/colormix.js'></script>
	<script>
		// Use ColorMix here !
		var Color = new ColorMix.Color(255, 255, 255);
	</script>
</body>

You can already use it to mix some colors!

var C1 = new ColorMix.Color(41, 51, 61),
	C2 = new ColorMix.Color(125, 140, 220),
	C3 = new ColorMix.Color(255, 128, 0),
	mix = ColorMix.mix([C1, C2, C3], [25, 25, 50]);

console.log(C1, C2, C3, mix);
alert('Your mixed color is: rgb(' + mix.red + ', ' + mix.green + ', ' + mix.blue + ')');

Or if you want to blend a value, just set up your own gradient to the ColorMix singleton.

Note - your gradient must be an array of objects as following

// Your objects must have 2 properties:
- Reference [integer], who is basically the "value" of the gradient step
- Color [object], who is just an object with red, green and blue properties [integer values; 0-255]
Example:
var gradient = [{
	reference: (Ref),
	color: {
		red: (R),
		green: (G),
		blue: (B)
	}
}];

Note - your gradient should be sorted by the reference property of its objects, from smallest to biggest

// Set an array of objects
ColorMix.setGradient([
	{ reference: 0, color: { red: 0, green: 0, blue: 255 } },
	{ reference: 25, color: { red: 64, green: 0, blue: 191 } },
	{ reference: 50, color: { red: 128, green: 0, blue: 128 } },
	{ reference: 75, color: { red: 191, green: 0, blue: 64 } },
	{ reference: 100, color: { red: 255, green: 0, blue: 0 } }
]);

Then blend the value in your fresh gradient!

var color = ColorMix.blend(69);
console.log(color);
alert('Your blended color is: rgb(' + color.red + ', ' + color.green + ', ' + color.blue + ')');

Then apply it on DOM HTML elements!
Note - You can chain operations for a more comfortable syntax.
```
var color = ColorMix.blend(69).useAsBackground('body');
```

Documentation

ColorMix

Color(R, G, B) - Create and manipulate a Color object
Public properties
- red
  
  Description
  
  Integer - The red value of the color [0 - 255]
- green
  
  Description
  
  Integer - The green value of the color [0 - 255]
- blue
  
  Description
  
  Integer - The blue value of the color [0 - 255]
Constructor
- Color(R, G, B)
  Description
  
  Set the RGB properties from the integer values R, G and B.
  
  Arguments
  - R (Integer) - red value to set: [0 - 255]
  - G (Integer) - green value to set: [0 - 255]
  - B (Integer) - blue value to set: [0 - 255]
  Example
```
var color = new ColorMix.Color(255, 255, 255); // ColorMix.Color { red: 255, green: 255, blue: 255 }
```
  You can also choose an hex string as first parameter and ignore the other ones!.
  
  Example
```
var color = new ColorMix.Color('#FFFFFF'); // ColorMix.Color { red: 255, green: 255, blue: 255 }
```
  If you do not provide any parameter, the color will be initialized with a 0 - range for each property (equivalent to black).
  
  Chainable
Public methods
- fromHex(hexString)
  Description
  
  Set the RGB properties from an hexadecimal String.
  
  Arguments
  - hexString (String) - hexString to set: ['(#)RRGGBB', '(#)RGB']
  Example
```
var color = new ColorMix.Color().fromHex('#FFFFFF'); // ColorMix.Color { red: 255, green: 255, blue: 255 }
```
  The invalid Hex values will be replaced by 0.
  
  Chainable
- getRed()
  Description
  
  Getter - returns the red value of the color
  
  Example
```
var red = new ColorMix.Color(255, 255, 255).getRed();
```
- setRed(R)
  Description
  
  Setter - set the red value for a color, and returns the color instance.
  
  Arguments
  - R (Integer) - red value to set: [0 - 255]
  Example
```
var red = new ColorMix.Color(255, 255, 255).setRed(0);
```
  Chainable
- getGreen()
  Description
  
  Getter - returns the green value of the color
  
  Example
```
var green = new ColorMix.Color(255, 255, 255).getGreen();
```
- setGreen(G)
  Description
  
  Setter - set the green value for a color, and returns the color instance.
  
  Arguments
  - G (Integer) - green value to set: [0 - 255]
  Example
```
var green = new ColorMix.Color(255, 255, 255).setGreen(0);
```
  Chainable
- getBlue()
  Description
  
  Getter - returns the blue value of the color
```
var blue = new ColorMix.Color(255, 255, 255).getBlue();
```
- setBlue(B)
  Description
  
  Setter - set the blue value for a color, and returns the color instance.
  
  Arguments
  - B (Integer) - blue value to set: [0 - 255]
  Example
```
var blue = new ColorMix.Color(255, 255, 255).setBlue(0);
```
  Chainable
- toString(mode)
  Description
  
  Format the color for a given mode. Returns a string representation of the color.
  
  Arguments
  - mode (String) - format mode: ['hex', 'rgb', 'rgba', 'hsl', 'hsla']
  Example
```
var colorName = new ColorMix.Color(255, 255, 255).toString('rgb'); // colorName = rgb(255, 255, 255);
```
- useAsBackground(selector)
  Description
  
  Set this color as CSS background-color for a given selector. Returns the colors instance.
  
  Arguments
  - selector (String) - element selector: ['#(id)', '.(class)', '(tag)']
  Example
```
var colorName = new ColorMix.Color(255, 255, 255).useAsBackground('body'); // <body>.style.backgroundColor = rgb(255, 255, 255);
```
  Without jQuery, it may not works for some complex selectors like tag#id or tag.class.
  
  Chainable
- useAsColor(selector)
  Description
  
  Set this color as CSS color for a given selector. Returns the colors instance.
  
  Arguments
  - selector (String) - element selector: ['#(id)', '.(class)', '(tag)']
  Example
```
var colorName = new ColorMix.Color(255, 255, 255).useAsColor('body'); // <body>.style.color = rgb(255, 255, 255);
```
  Without jQuery, it may not works for some complex selectors like tag#id or tag.class.
  
  Chainable
ColorSpace - Convert colors from a color space to another one
Public methods
- RGB(R, G, B)
  Description
  
  Create and returns an RGB-color object
  
  Arguments
  - R (Integer) - red value to set: [0 - 255]
  - G (Integer) - green value to set: [0 - 255]
  - B (Integer) - blue value to set: [0 - 255]
  Example
```
var RGB = new ColorMix.ColorSpace.RGB(255, 255, 255); // { red: 255, green: 255, blue: 255 }
```
  The invalid values will be replaced by 0.
- XYZ(X, Y, Z)
  Description
  
  Create and returns an XYZ-color object
  
  Arguments
  - X (Float) - X value to set
  - Y (Float) - Y value to set
  - Z (Float) - Z value to set
  Example
```
var XYZ = new ColorMix.ColorSpace.XYZ(0, 0, 0); // { x: 0, y: 0, z: 0 }
```
  The invalid values will be replaced by 0.
- HSL(H, S, L)
  Description
  
  Create and returns an HSL-color object
  
  Arguments
  - H (Integer) - H value to set: [0 - 360]
  - S (Integer) - S value to set: [0 - 100]
  - L (Integer) - L value to set: [0 - 100]
  Example
```
var HSL = new ColorMix.ColorSpace.HSL(360, 100, 100); // { hue: 360, sat: 100, lig: 100 }
```
  The invalid values will be replaced by 0.
- Lab(L, a, b)
  Description
  
  Create and returns an Lab-color object
  
  Arguments
  - L (Float) - L value to set: [0 - 100]
  - a (Float) - a value to set
  - b (Float) - b value to set
  Example
```
var Lab = new ColorMix.ColorSpace.Lab(100, 0, 0); // { L: 100, a: 0, b: 0 }
```
  The invalid values will be replaced by 0.0.
- RGBtoXYZ(R, G, B)
  Description
  
  Convert a RGB color to a XYZ one and returns a XYZ-color object.
  
  Arguments
  - R (Integer) - R value to convert: [0 - 255]
  - G (Integer) - G value to convert: [0 - 255]
  - B (Integer) - B value to convert: [0 - 255]
  Example
```
var XYZ = new ColorMix.ColorSpace.RGBtoXYZ(255, 255, 255); // { x: 95, y: 100, z: 108 }
```
  The invalid values will be replaced by 0.0.
- RGBtoHSL(R, G, B)
  Description
  
  Convert a RGB color to a HSL one and returns a HSL-color object.
  
  Arguments
  - R (Integer) - R value to convert: [0 - 255]
  - G (Integer) - G value to convert: [0 - 255]
  - B (Integer) - B value to convert: [0 - 255]
  Example
```
var HSL = new ColorMix.ColorSpace.RGBtoHSL(255, 255, 255); // { hue: 0, sat: 0, lig: 100 }
```
  The invalid values will be replaced by 0.
- RGBtoLab(R, G, B)
  Description
  
  Convert a RGB color to a Lab one and returns a Lab-color object.
  
  Arguments
  - R (Integer) - R value to convert: [0 - 255]
  - G (Integer) - G value to convert: [0 - 255]
  - B (Integer) - B value to convert: [0 - 255]
  Example
```
var Lab = new ColorMix.ColorSpace.RGBtoLab(255, 255, 255); // { L: 100, a: 0, b: 0 }
```
  The invalid values will be replaced by 0.0.
- XYZtoRGB(X, Y, Z)
  Description
  
  Convert a XYZ color to a RGB one and returns a RGB-color object.
  
  Arguments
  - X (Float) - X value to convert
  - Y (Float) - Y value to convert
  - Z (Float) - Z value to convert
  Example
```
var RGB = new ColorMix.ColorSpace.XYZtoRGB(50, 50, 50); // { red: 204, green: 183, blue: 180 }
```
  The invalid values will be replaced by 0.
- XYZtoLab(X, Y, Z)
  Description
  
  Convert a XYZ color to a Lab one and returns a Lab-color object.
  
  Arguments
  - X (Float) - X value to convert
  - Y (Float) - Y value to convert
  - Z (Float) - Z value to convert
  Example
```
var Lab = new ColorMix.ColorSpace.XYZtoLab(50, 50, 50); // { L: 76.06926101415557, a: 6.777038667061586, b: 4.4398523641493215 }
```
  The invalid values will be replaced by 0.0.
- LabtoRGB(L, a, b)
  Description
  
  Convert a XYZ color to a Lab one and returns a Lab-color object.
  
  Arguments
  - L (Float) - L value to convert
  - a (Float) - a value to convert
  - b (Float) - b value to convert
  Example
```
var RGB = new ColorMix.ColorSpace.LabtoRGB(100, 0.00526049995830391, -0.010408184525267927); // { red: 255, green: 255, blue: 255 }
```
  The invalid values will be replaced by 0.
- LabtoXYZ(L, a, b)
  Description
  
  Convert a XYZ color to a Lab one and returns a Lab-color object.
  
  Arguments
  - L (Float) - L value to convert
  - a (Float) - a value to convert
  - b (Float) - b value to convert
  Example
```
var XYZ = new ColorMix.ColorSpace.LabtoXYZ(100, 0.00526049995830391, -0.010408184525267927); // { x: 95.05, y: 100, z: 108.89999999999996 }
```
  The invalid values will be replaced by 0.0.
mix(colors, percents)
Description

Mix an array of colors with corresponding percents

Arguments
- colors (Array) - ColorMix.Color instances to mix, at leat 1.
- percents (Array) - percents integer of each color instance. The sum must be equal to 100.
Example
```
var C1 = new ColorMix.Color(0, 152, 204),
C2 = new ColorMix.Color(0, 120, 240),
mix = ColorMix.mix([C1, C2], [50, 50]); // ColorMix.Color { red: 18, green: 136, blue: 222 } --> Average between C1 and C2 in Lab color space
```
Your parameters should be array of same size.

The sum of all the "percents" parameter items should be equal to 100.

You can of course mix several colors!

getGradient()

Description

Getter - returns the gradient of the ColorMix.

Example

var gradient = ColorMix.getGradient(); // [{ reference: (reference), color: (color) }]

setGradient(gradient)
Description

Setter - set the gradient for the ColorMix.

Arguments
- gradient (Array) - Gradient items objects. All these objects must have two properties: "reference", the integer value that will be used to blend, and "color", a simple RGB object with red, green and blue properties, that will be used for mixing.
Example
```
ColorMix.setGradient([
	{ reference: -100, color: { red: 0, green: 0, blue: 0 } },
	{ reference: 100, color: { red: 255, green: 255, blue: 255 } }
]);
```
The more detailled the gradient is, the more precise your blending will be.
blend(reference)
Description

Blend a reference with the gradient and returns the mixed color instance.

Arguments
- reference (Integer) - reference to blend.
Example
```
var blend = ColorMix.blend(50); // ColorMix.Color { red: (red), green: (green), blue: (blue) }
```
This method is directly depending of the gradient you should have set before.

If the reference is out of bounds relative to the gradient, the closest limit color of the gradient will be returned.