Color

Playground:

var myHue = color('hsl(0,100%,50%)');
var rows = 6, cols = 30, steps = cols * rows;

for (var r = 0; r < rows; ++r) {
  for (var c = 0; c < cols; ++c) {
    new Rect(c*20, r*20, 20, 20)
      // Increment hue slightly with each step:
      .addTo(stage).attr('fillColor', myHue.hue(myHue.hue() + 1/steps));
  }
}

Intro

Bonsai provides a helpful color API. With it you can parse and manipulate colors. To parse a color and get a fresh color.RGBAColor instance, simply call:

color('red');

This gives you a color.RGBAColor instance.

An RGBAColor instance allows you to set and get the r, g, b and a values of the color, in addition to h (hue), s (saturation) and l (lightness) values.

NOTE: r, g and b are 0..255, while h, s, l and a (alpha) are 0..1.

E.g.

var myColor = color('red'); // or `new color.RGBAColor(255,0,0)`
myColor.hue(0.5); // change to cyan

You can also use the more verbose set and get methods:

myColor.set('hue', 0.5);
myColor.set('green', 255);

For getting string representations of colors, RGBAColor implements three methods:

Color spawning methods

The color.RGBAColor class contains a number of color-spawning methods, i.e. methods that return various colors, mostly variations of the instance color:

var myColor = new color.RGBAColor('red');

myColor.lighter();      // -> color with lightness increased by 0.01
myColor.lighter(.2);    // -> color with lightness increased by 0.2
myColor.darker()        // -> color with lightness decreased by 0.01
myColor.lighter(.2);    // -> color with lightness decreased by 0.2
myColor.midpoint(x);    // -> color between `color` and `x`

Example usage of midpoint:

color('red').midpoint('white'); // -> pink
There is also a generic randomize method which accepts two arguments, a string or array specifying propert(y ies) to randomize and a range argument to specify to what degree they should be randomized. Both arguments are optional though:
myColor.randomize(); // -> default is randomizing by 'r', 'g', and 'b' (100% random color)

Examples using the available arguments:

color('red').randomize('hue'); // -> randomize by hue, leaving saturation/lightness as-is

Available properties to animate include: hue, saturation, lightness, alpha, red, green, blue (aliases work too, h, s, l, a, r, g, b…)

The range argument, if passed, will ensure the randomization occurs around the current value. So, if you wanted to randomize by hue (which can be from 0 to 1), but you only wanted a slight change from the current value, you could do this:

color('yellow').randomize('hue', 0.2);

The hue of yellow is 0.16 (or 60 degrees). Passing a range of 0.2 will ensure that the random hue produced is no smaller than 0.06 and no bigger than 0.26 (i.e. 0.1 in each direction from the original hue, a full range of 0.2).

color.parse:

Internally we are using a 32-bit number to represent colors (including alpha). The format is:

0x<rr><gg><bb><aa>

i.e. the first eight bits are red, the second eight bits are green …

The color.parse function can accept any of the following formats:

Where alpha isn’t specified, it is assumed to be 1.

So, color.parse just returns a number:

color.parse('red'); // 0xff0000ff