HSL Color Theory Computation in Lua
Overview · Installation · Using Colors · Contact · LuaDoc · License
Colors library provides methods to do color computation in HSL color space and for finding "harmonious" color palettes.
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
luarocks --from=http://sputnik.freewisdom.org/rocks/earth install 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.)
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:
| || ||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).
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
> =c:desaturate_by(.5) -- set saturation to saturation*.5 #2d6b38
> =c:desaturate_to(.5) -- set saturation to .5 #267233
> =c:lighten_by(.5) -- set lightness to lightness*.5 #14b72f
> =c:lighten_to(.5) -- set lightness to .5 #19e53b
> =c:hue_offset(180) -- shift hue by 180 #890f75
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
For more information please contact the author, Yuri Takhteyev or write to the Sputnik Mailing List.
Comments are welcome!
Provides support for color manipulation in HSL color space. http://sputnik.freewisdom.org/lib/colors/ License: MIT/X (c) 2008 Yuri Takhteyev (email@example.com) * * rgb_to_hsl() implementation was contributed by Markus Fleck-Graffe.
|Color:complementary()||Creates a complementary color.
|Color:desaturate_by()||Creates a new color with saturation set to a old saturation times r.
|Color:desaturate_to()||Creates a new color with saturation set to a new value.
|Color:hue_offset()||Creates a new color with hue different by delta.
|Color:lighten_by()||Creates a new color with lightness set to a old lightness times r.
|Color:lighten_to()||Creates a new color with lightness set to a new value.
|Color:neighbors()||Creates two neighboring colors (by hue), offset by "angle".
|Color:shades()||Creates n shades of this color and returns them as a table
|Color:split_complementary()||Creates two new colors, offset by angle from this colors complementary.
|Color:tints()||Creates n tints of this color and returns them as a table
|Color:to_rgb()||Converts the color to an RGB string.
|Color:triadic()||Creates two new colors to make a triadic color scheme.
|Color:variations()||Creates n variations of this color using supplied function and returns them as a table.
|hsl_to_rgb()||Converts an HSL triplet to RGB (see http://homepages.cwi.nl/~steven/css/hsl.html).
|new()||Instantiates a new "color".
|rgb_to_hsl()||Converts an RGB triplet to HSL.
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.