ColorTools

Project by Scott Murray

colorGrid_large

Search results for "ocean" from ColourLovers.

Introduction

ColorTools is a collection of code that makes it easier to work with colors in Processing. It may be released as open source software at some point. This page documents the progress on ColorTools so far, and notes some planned improvements.

It consists of two data classes: ColorValue and ColorPalette. ColorValue manages all the information you could possibly want about one single color, while ColorPalette handles sets of related colors and applies transformations across multiple colors.

See Questions & Answers for an example of a project that uses ColorTools to:

Documentation

ColorValue

A ColorValue object is like a simple color value in Processing, only smarter, because it keeps tracks of all of its values in different color spaces, and it also can perform various transformations on itself. Use it instead of color anytime you'll need to isolate or manipulate RGB or HSB values independently.

Stored Values

Constructor Statement

ColorValue(color _colorVal)

Example usage:

ColorValue[] black = new ColorValue(0);

Methods

getColor()
Returns the Processing color value.

setColor(newColor)
Takes any Processing color value, and overwrites the object's current color values with it.

getValuesRGB()
Returns an array of three float values, storing the red, green, and blue values, respectively. RGB values are always between 0.0 and 255.0.

getValuesHSB()
Returns an array of three float values, storing the hue, saturation, and brightness values, respectively. HSB values are always between 0.0 and 1.0.

setFromBlend(startColorValue, endColorValue, progress)
Takes two other ColorValue objects and a normalized float control value, which must be between 0.0 and 1.0. (0.0 produces a color that matches the startColorValue, 1.0 matches the endColorValue, and any value in between fades the two.) Overwrites the object's current color values with the newly calculated color.

adjustSaturation(degree)
Takes the a normalized float control value, which must be between 0.0 and 1.0. (0.0 produces a completely desaturated color, and 1.0 is completely saturated.) Overwrites the object's current color values with the newly calculated color.

calcNewBrightness(percentChange, maskValue)
Takes a percentage value — between 0.0 and 1.0 — and a mask value — between 0.0 (black) and 255.0 (white) — and calculates a new color by adjusting the current object's color values. This is useful for looping through lighter and darker adjustments of the same color until finding a useful value. Returns a Processing color value.

incrementBrightness(incValue)
Takes an increment value between -1.0 and 1.0 adjusts the current object's color brightness accordingly.

ColorPalette

A ColorPalette object stores an array of ColorValue objects, so you can keep all your smart colors together in one place. It also handles any calculations and transformations that involve multiple colors.

Stored Values & Object References

Constructor Statement

ColorPalette(PApplet _applet)

Example usage:

// This code needs to appear at the top of your sketch,
// outside of setup() and draw(), because the "this"
// below must reference the PApplet.
ColorPalette warmPalette = new ColorPalette(this);

When the ColorPalette is instantiated, it creates one initial ColorValue in its array (colorValues[0]) and sets its color to black. It ignores that initial ColorValue moving forward, and will append all new values to the array.

Methods

addNewColor(newColor)
Takes a Processing color value, creates a new ColorValue, and adds it to the palette.

newRandomColor()
Adds one new random color to the palette.

addNewRandomColors(numToAdd)
Takes a positive int value, and adds that number of random colors to the palette.

clearAllColors()
Resets all values, deletes all colors from the palette.

getNumberColorsInPalette()
Returns a positive int value with the number of colors in the palette.

getColor(id)
Returns the Processing color value for the specified color in the palette. (Note that an id of 0 will always return black — the "first" real color in the palette is 1.) If the requested id doesn't exist, black is returned.

getColorValue(id)
Same as above, but returns the ColorValue for the specified color in the palette.

getAllColors()
Not yet implemented, but will eventually be a quick way to get all colors out of the palette and into an array.

replaceColor(id, newColor)
Takes a Processing color value and overwrites the specified color in the palette with it.

addNewByTextSearch(searchTerms, maxToAdd)
Takes a String of search terms, gets the top rated colors for those terms from ColourLovers, and adds those colors to the palette. Limits the number of returned colors to int maxToAdd, though there may be fewer (or none).

sortColors()
Not yet implemented. Will eventually be used to apply different sorts to all colors in the palette (e.g. sort by hue, saturation, or brightness).

getBrightnessDifference()
Calculate the brightness difference between the first and second colors in the palette, and returns a float. Recommended use: Create a ColorPalette that stores only two colors, and dedicate that palette to these kinds of color comparisons.

calcBrightnessDiff(firstColor, secondColor)
Same as above, but takes any two Processing color values as input. (In the future, these two methods will be consolidated.)

getColorDifference()
Calculate the color difference between the first and second colors in the palette, and returns a float.(This could be rewritten later to take any two colors as input.)

calcColorDiff(firstColor, secondColor)
Same as above, but takes any two Processing color values as input. (In the future, these two methods will be consolidated.)

calcNewForegroundColor(contrastiness)
Takes a normalized float value between 0.0 and 1.0, and calculates a new color by increasing contrast between the first and second colors in the palette. (This could be rewritten later to take any two colors as input.) Returns a Processing colorvalue.

increaseContrast()
Increasese the contrast between the first and second colors in the palette. Now deprecated, and will be removed soon, in favor of calcNewForegroundColor() above.

fadeAllColors(startPalette, endPalette, progress)
Takes references to two different ColorPalette objects and a normalized float value between 0.0 and 1.0. First adjusts the current ColorPalette object so it has the same number of colors as the smaller of the two referenced palettes, and then calculates all new colors by blending each of the colors in the referenced palettes. This is a quick way to transition large numbers of colors at once.

adjustSaturation(degree)
Takes a normalized float value between 0.0 and 1.0, and adjusts the saturation levels of all color in the current palette.

Project posted May 9, 2009.