Overview↑

Colors library provides methods to do color computation in HSL color space and for finding "harmonious" color palettes.

Installation↑

Colors consists of a single file (colors.lua) of slightly more than 100 lines, plus a test script (test.lua).
Just put colors.lua somewhere in your Lua path.

Here is a list of recent releases:

You can also install it using LuaRocks with

luarocks install colors

or:

luarocks --from=http://sputnik.freewisdom.org/rocks/earth install colors

Using Colors↑

Colors are typically encoded in software by their coordinates in the RGB (Red-Green-Blue) color space. Unfortunately, the RGB color space is very unintuitive and additionally certain principles of color harmony do not express themselves easily in RGB. The HSL (Hue-Saturation-Lightness) color space solves both of those problems. This library allows you to work with colors in the HSL space, calculate harmonious patterns and then convert the result to RGB. (See worqx.com for some background on color harmony.)

The HSL Color Space

Colors are encoded in HSL by three values: Hue, Saturation and Lightness.

Lightness is just the opposite of darkness of the color. White has lightness 1, black has lightness 0. Other colors are inbetween: Saturation is the intensity of color, which shows how far the color is from gray. Here are the shades of red for different saturation and lightness:

 
Lightness
   0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
Saturation 0.0                      
0.1                      
0.2                      
0.3                      
0.4                      
0.5                      
0.6                      
0.7                      
0.8                      
0.9                      
1.0                      

Hue is the "color" of color: what makes "green" different from "red". Hue can also be expressed as a number between 0 and 1, though this library uses the values from 0 to 360 instead. Unlike lightness and saturdation, hue loops: the hue of 360 is actually the same color as hue of 0 (red).

Saturation
   1.0 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0.0
Hue 0                      
10                      
20                      
30                      
40                      
50                      
60                      
70                      
80                      
90                      
100                      
110                      
120                      
130                      
140                      
150                      
160                      
170                      
180                      
190                      
200                      
210                      
220                      
230                      
240                      
250                      
260                      
270                      
280                      
290                      
300                      
310                      
320                      
330                      
340                      
350                      
360                      

HSL Calculations with Colors

Creating a color in HSL space and converting it to RGB

> require("colors")
> c = colors.new(130, .8, 0.3) -- green, pretty saturated, somewhat dark
> =tostring(c)
#0f8923
 

You can also create this color from it's RGB code:

> require("colors")
> c = colors.new("#0f8923") -- green, pretty saturated, somewhat dark
> =tostring(c)
#0f8923

The color converts to its RGB representation when forced into a string:

> =c -- convert implicitly
#0f8923
 

Accessing the HSL components:

> print(c.H, c.S, c.L)
130     0.8     0.3

Changing saturation:

> =c:desaturate_by(.5) -- set saturation to saturation*.5
#2d6b38
 
> =c:desaturate_to(.5) -- set saturation to .5
#267233
 

Changing lightness:

> =c:lighten_by(.5) -- set lightness to lightness*.5
#14b72f
 
> =c:lighten_to(.5) -- set lightness to .5
#19e53b
 

Changing hue:

> =c:hue_offset(180) -- shift hue by 180
#890f75
 

Building Color Schemes

To build a color scheme, we usually start with a color, pick one or more matching colors, then derive shades and tints from them. You might want to read up on color combinations at worqx.com.

For a monochromatic color scheme, we'll just use the color we started with and tints and shades from it:

> tints = c:tints(5) -- make five tints
> for i,t in ipairs(tints) do print(t) end
#16c934
#3ee95a
#7ef091
#bef7c8
#ffffff
          
> shades = c:shades(5) -- make five shades
> for i,s in ipairs(shades) do print(s) end
#0c6e1c
#095215
#06370e
#031b07
#000000
         

For a complimentary scheme, we can use easily derive a complimentary color and its tints and shades:

> ctints = c:complementary():tints(5) -- make five tints of the complimentary color
> for i,t in ipairs(ctints) do print(t) end
#c916ac
#e93ecd
#f07edd
#f7beee
#ffffff
         
         

For less contrast, though, we might want to stick with neighboring colors: e.g., +/- 60 degrees of the starting color:

> n1, n2 = c:neighbors(60)  -- get neiboring colors: 60 degees up and down
> for i,t in ipairs(n1:tints()) do print(t) end
#16c98e
#3ee9b0
#7ef0ca
#bef7e4
#ffffff
> for i,t in ipairs(n2:tints()) do print(t) end
#52c916
#77e93e
#a4f07e
#d1f7be
#ffffff
         
         
         

We could alternatively generate a split complementary color scheme:

>  for i,t in ipairs(c1:tints()) do print(t) end
#8e16c9
#b03ee9
#ca7ef0
#e4bef7
#ffffff
> for i,t in ipairs(c2:tints()) do print(t) end
#c91652
#e93e77
#f07ea4
#f7bed1
#ffffff
         
         
         

Or a triadic one:

> t1, t2 = c:triadic()
> for i,t in ipairs(t1:tints()) do print(t) end
#3416c9
#5a3ee9
#917ef0
#c8bef7
#ffffff
> for i,t in ipairs(t2:tints()) do print(t) end
#c93416
#e95a3e
#f0917e
#f7c8be
#ffffff
         
         
         

Contact↑

For more information please contact the author, Yuri Takhteyev or write to the Sputnik Mailing List.

Comments are welcome!

LuaDoc↑

colors

Provides support for color manipulation in HSL color space. http://sputnik.freewisdom.org/lib/colors/ License: MIT/X (c) 2008 Yuri Takhteyev (yuri@freewisdom.org) * * rgb_to_hsl() implementation was contributed by Markus Fleck-Graffe.

Color:complementary() Creates a complementary color.
Returns: a new instance of Color
Color:desaturate_by() Creates a new color with saturation set to a old saturation times r.
r:
the multiplier for the new saturation
Returns: a new instance of Color
Color:desaturate_to() Creates a new color with saturation set to a new value.
saturation:
the new saturation value (0.0 - 1.0)
Returns: a new instance of Color
Color:hue_offset() Creates a new color with hue different by delta.
delta:
a delta for hue.
Returns: a new instance of Color.
Color:lighten_by() Creates a new color with lightness set to a old lightness times r.
r:
the multiplier for the new lightness
Returns: a new instance of Color
Color:lighten_to() Creates a new color with lightness set to a new value.
lightness:
the new lightness value (0.0 - 1.0)
Returns: a new instance of Color
Color:neighbors() Creates two neighboring colors (by hue), offset by "angle".
angle:
the difference in hue between this color and the neighbors
Returns: two new instances of Color
Color:shades() Creates n shades of this color and returns them as a table
n:
the number of shades
Returns: a table with n values containing the new colors
Color:split_complementary() Creates two new colors, offset by angle from this colors complementary.
angle:
the difference in hue between the complementary and the returned colors
Returns: two new instances of Color
Color:tints() Creates n tints of this color and returns them as a table
n:
the number of tints
Returns: a table with n values containing the new colors
Color:to_rgb() Converts the color to an RGB string.
Returns: a 6-digit RGB representation of the color prefixed with "#" (suitable for inclusion in HTML)
Color:triadic() Creates two new colors to make a triadic color scheme.
Returns: two new instances of Color
Color:variations() Creates n variations of this color using supplied function and returns them as a table.
f:
the function to create variations
n:
the number of variations
Returns: a table with n values containing the new colors
hsl_to_rgb() Converts an HSL triplet to RGB (see http://homepages.cwi.nl/~steven/css/hsl.html).
h:
hue (0-360)
s:
saturation (0.0-1.0)
L:
lightness (0.0-1.0)
Returns: an R, G, and B component of RGB
new() Instantiates a new "color".
H:
hue (0-360) _or_ an RGB string ("#930219")
S:
saturation (0.0-1.0)
L:
lightness (0.0-1.0)
Returns: an instance of Color
rgb_to_hsl() Converts an RGB triplet to HSL.
r:
red (0.0-1.0)
g:
green (0.0-1.0)
b:
blue (0.0-1.0)
Returns: corresponding H, S and L components

License↑

Copyright (c) 2007, 2008 Yuri Takhteyev

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.