Colors
The NodeBox Colors library offers a set of tools to work with color more conveniently. You can use the library to create colors by name (like red or ivory), from pixels in an image, group them into lists of which you can then collectively manipulate hue, brightness and saturation, create lists of harmonious colors based on color theory rules (like complementary or analogous), create lists of gradient colors, work with drop shadows and gradient fills for paths, define powerful indefinite color ranges (like bright red or purplishgreenish), aggregate color information from Yahoo!, and more!
There's a lot of stuff to explain but luckily most principles in the Colors library are easy.
Some central themes are:
- Colors: enhanced color objects with many predefined instances.
- Color lists: sets of colors which can be manipulated as a whole.
- Rules: color theory rules that generate lists of colors.
- Color ranges: variable sets of colors whose HSB values are constrained between a minimum and a maximum value.
- Color themes: groups of ranges.
- Depth: lighting, shadows and gradients.
My personal favorites are shades and shadows and gradient fills.
Download
 | colors.zip (1.95MB) Last updated for NodeBox 1.9.4.9 Licensed under GPL Authors: Tom De Smedt, Frederik De Bleser |
Documentation
- How to get the library up and running
- Colors
- Color lists
- Color lists from harmony rules (complementary, analogous, ...)
- Color lists from gradients
- Color ranges
- Predefines color ranges: shades (dark, bright, cool, ...)
- Grouping ranges into themes
- Aggregating colors from the web
- Using a shader for lighting effects
- Using dropshadows and gradient fills
How to get the library up and running
Put the colors library folder in the same folder as your script so NodeBox can find the library. You can also put it in ~/Library/Application Support/NodeBox/.
colors = ximport("colors")Outside of NodeBox you can also just do import colors. Color lists from image pixels then work with PIL.
Colors
The Colors library has a number of commands that create a new color you can use with fill() or stroke().
rgb(r, g, b, a=None, range=1.0, name="")
hsb(h, s, b, a=None, range=1.0, name="")
cmyk(c, m, y, k, range=1.0, name="")
lab(l, a, b, range=1.0, name="")
hex(str, name="")
With the range parameter you can define how you want to supply the channel values. For example, if you want to define r, g and b between 0 and 255 instead of between 0.0 and 1.0, set range to 255.
The optional name parameter lets you define a name for the color. Otherwise, a name will be guessed using the clr.nearest_hue() method (see below).
The hex() command creates a color from a hexadecimal string (e.g. "#30343D").
named_color(str)
The named_color() command creates a color from a name like "olive" or "maroon" or "antiquewhite". A list of all the named colors the command will recognize is here. The really great thing is that each of these named colors is also a command in the Colors library. So the two colors in the example below are exactly the same:
clr1 = colors.named_color("olive") clr2 = colors.olive()
Color properties
Each of the above commands returns a Color object. It has all the standard properties a color created with the NodeBox color() command also has. You can use these to find out the color's R, B and B values, or its C, M, Y and K values, or its H, S and B values:
- clr.r: the red value in RGB.
- clr.g: the green value in RGB.
- clr.b: the blue value in RGB.
- clr.a: the alpha value (opacity).
- clr.c: the cyan value in CMYK.
- clr.m: the magenta value in CMYK.
- clr.y: the yellow value in CMYK.
- clr.k: the black value in CMYK.
- clr.hue: the hue of the color in HSB.
- clr.saturation: the saturation (grayness) of the color in HSB.
- clr.brightness: the brightness of the color in HSB.
The Color object in the Colors Library has some additional properties:
- clr.name: the name of this color.
- clr.is_black: will be True when the color's R, G and B values are 0.
- clr.is_white: will be True when the color's R, G and B values are 1.
- clr.is_gray: will be True when the color's R, G and B values are the same.
- clr.is_transparent: will be True when the color is completely transparent.
- clr.complement: the complementary color (i.e. 180 degrees across the color wheel) of this color.
Color methods
Each color has a range of methods to manipulate it. Each of these returns a copy of the color.
clr.copy()
clr.darken(step=0.1)
clr.lighten(step=0.1)
clr.desaturate(step=0.1)
clr.saturate(step=0.1)
clr.adjust_contrast(step=0.1)
clr.adjust_rgb(r=0.0, g=0.0, b=0.0, a=0.0)
clr.adjust_hsb(h=0.0, s=0.0, b=0.0, a=0.0)
What is interesting about these methods is that you can also apply them to color lists. This way you can quickly manipulate sets of colors without having to change each color individually.
The clr.blend() command returns a mixture from this color and another color:
clr.blend(clr, factor=0.5)
The clr.rotate() command returns a color that is angle degrees across the color wheel. So when angle is 180, this returns the complementary color.
clr.rotate(angle=180)
The clr.analog() command returns hues that are next to this one on the color wheel, separated by angle. The additional d parameter will slightly vary the color's brightness and saturation for more variation.
clr.analog(angle=20, d=0.5)
Another interesting method is clr.nearest_hue(). This returns the name of the name of a well-known hue this color resembles most (red, orange, yellow, lime, green, teal, cyan, azure, blue, violet, purple or pink). When the primary parameter is True, the name returned is limited to primary hues: red, orange, yellow, green, blue, purple, pink.
clr.nearest_hue(primary=False)
To get the distance between two colors as a number there's the clr.distance() method. It returns a number between 0.0 and 1.0 representing the distance as if colors were arranged on a sphere (e.g. a disc of hues with the less saturated colors in the centre, darker discs in the sphere are at the bottom).
clr.distance(clr)
The clr.swatch() command draws a rectangle to the canvas filled with the color. The rectangle is located at x and y and has width w and height h.
clr.swatch(x, y, w=35, h=35, roundness=0)
Color lists
The functionality of the Colors library becomes more interesting when we get down to working with lists of colors. You can store different colors in a list and then manipulate the entire collection. For example, make all of the colors darker, retrieve the lightest color, or even create a list from pixels in an image for example.
list(clr1, clr2, clr3, ..., name="", tags=[])
list([clr1, clr2, clr3, ...], name="", tags=[])
list(imagepath, n=10)
list(word)
list(Web.KulerTheme)
Lists can be created from a number of indivdual colors, another list of colors, the pathname of an image from which to grab pixel values (you need to have the Core Image library installed), a word, or a kuler theme from the web.kuler.search() command in the NodeBox Web library.
Optionally you can supply a name and a list of tags for the list.
Accessing each individual color in the list works the same as with any other list:
sea = colors.list("sea.jpg", n=20) x = 0 for clr in sea: rect(x, 0, 20, 20, fill=clr) x += 20
You can also use the choice() command to get a random colors from the list.
Color list properties
Each of the above commands returns a ColorList object with a number of properties:
- list.name: the name of the set of colors.
- list.tags: a list of associations.
- list.darkest: the darkest color in the list (useful as a background or a text color for example).
- list.lightest: the lightest color in the list.
- list.average: the average (mean) color of all the colors in the list.
- list.complement: the complementary color list.
Color list methods
Some methods to manipulate the list. All of these will return a copy of the list.
list.reverse()
list.sort(reversed=True)
list.repeat(self, n=2, oscillate=False, callback=None)
The list.reverse() method returns a copy with all the colors in reversed order.
The list.sort() method returns a copy with the colors sorted from dark to light.
The list.repeat() method returns a repetition of the list: if the list contains a red, green and a yellow color, list.repeat() will contain red, green, yellow, red, green, yellow. When oscillate is True it will contain red, green, yellow, yellow, green, red. This is useful for lists of gradient colors.
list.swarm(x, y, r=100)
The list.swarm() method draws a small visualization of all the colors in the list.
 | sea = colors.list("sea.jpg", n=20) |