Color.js provides an API to do simple color management in javascript. Color objects provide methods to do a number of common, useful operations independent of the underlying color model they need.

This API is designed to be useful, clean but operates at the expense of performance. If you need fast color management a) you are probably using the wrong language and b) use a library that requires you to explicit conversions and clones.

You can find the latest version at my github.

Using the library

Once you have included the library in your page, you can access the public namespace net.brehaut (reverse DNS scheme). The only export from color.js is the Color factory function. You may wish to import this into your local scope, eg:

var Color = net.brehaut.Color;

Color will create a new object for you from an object or string. Note that this is a factory function, not a constructor. eg:

var Green = Color("#00FF00");
var Red = Color({hue: 0, saturation: 1, value: 1});

Each method on color either returns a new color (or set of colors) or returns a value. You can chain manipulation methods together as much as you need. Eg

var C1 = Red.shiftHue(45).darkenByRatio(0.5).desaturateByAmount(0.1);

A common use case for this code is to set page elements colors to calculated values, the method toCSS provides a string for you to use. eg:

document.getElementById('myElement').style.backgroundColor = C1.toCSS();

Using a tool like firebug you can experiment with this library on this page.

Methods

There are three sorts of operations available on color objects; accessor methods (eg getHue/setHue), methods that manipulate the color and return a new object (eh shiftHue) or methods that return arrays of colors (eg, splitComplementaryScheme), and methods that do conversion and construction (eg toCSS).

All values are a float from 0 to 1, with the exception of hue which is a degree (from 0 to 360).

Accessor Methods

These methods are automatically generated by the API and are used to access the properties of the object. It is advisable to use these methods than try to access the property directly as the API makes no guarantees about the specific model members available.

• getRed() : Number
• setRed( newRed ) : Color
• getGreen(): Number
• setGreen( newGreen ) : Color
• getBlue() : Number
• setBlue( newBlue ): Color
• getHue() : Number (degrees)
• setHue( newHue ) : color
• getSaturation() : Number
• setSaturation( newSaturation ) : Color
• getValue() : Number
• setValue( newValue ) : Color
• getLuminance() : Number --- returns a number between 0 and 1 that represents how bright this color appears on a conventional monitor.

Color Methods

The following methods all return a new color.

• shiftHue( degrees ) : Color
• darkenByAmount( amount ) : Color
• darkenByRatio( ratio ) : Color
• lightenByAmount( amount ) : Color
• lightenByRatio( amount ) : Color
• desaturateByAmount( amount ) : Color
• desaturateByRatio( ratio ) : Color
• saturateByAmount( amount ) : Color
• saturateByRatio( ratio ) : Color
• blend( color , alpha ) : Color --- returns a new color that is self blended with alpha of color. eg black.blend ( white , 0 ) is black, black.blend ( white , 0.5 ) is grey and black.blend ( white , 1 ) is white.

The following methods return a list of colors

• schemeFromDegrees( listOfdegrees ) : List of Colors
• complementaryScheme( ) : List of Colors
• splitComplementaryScheme( ) : List of Colors
• splitComplementaryCWScheme( ) : List of Colors
• splitComplementaryCCWScheme( ) : List of Colors
• triadicScheme( ) : List of Colors
• clashScheme( ) : List of Colors
• tetradicScheme( ) : List of Colors
• fourToneCWScheme( ) : List of Colors
• fourToneCCWScheme( ) : List of Colors
• fiveToneAScheme( ) : List of Colors
• fiveToneBScheme( ) : List of Colors
• fiveToneCScheme( ) : List of Colors
• fiveToneDScheme( ) : List of Colors
• fiveToneEScheme( ) : List of Colors
• sixToneCWScheme( ) : List of Colors
• sixToneCCWScheme( ) : List of Colors
• neutralScheme( ) : List of Colors
• analogousScheme( ) : List of Colors

Conversion and Construction

• fromObject( o ) : Color --- o is an object with values from a color model or a css hexdecimal string.
• toCSS([bytesPerChannel]) : String --- css hexdecimal representation. bytesPerChannel defaults to 2
• toString() : String --- returns CSS representation
• toHSV() : Color
• toRGB() : Color

Library design notes

This library has been designed for correctness and ease of use in mind. With regard to ease of use, Color objects allow you to chain operations by returning a new object each time. These operations involve common modification to the values in the object by a value or by a ratio where suitable, and automatically convert to the appropriate color model as required.

The models chosen have been picked with regard to what makes most sense to a web developer, and ease of implementation, hence RGB and HSV.

With regard to programmatic style, Douglas Crockfords 'just the good parts' approach has been followed with the use of prototypal inheritance.

Changes

January 14, 2008

Version 0.3 released

• JSLint is now happy with it.
• Approx 25% faster by caching factory constructor functions — effectively unrolls object

January 13, 2008

Version 0.2 released

• Code tided up, now with comments
• Docs written
• Small edges cases implemented, eg, a black Color is returned if invalid arguments are passed
• CSS named colors are supported