Welcome! This is the documentation for GrapeFruit 0.2a1, last updated January 02, 2017.
See the Index for a list of the topics.
The Color class¶
-
class
grapefruit.
Color
¶
The grapefruit module contains only the Color
class, which exposes all
the functionnalities. It can be used to store a color value and manipulate it,
or convert it to another color system.
If you are only interested in converting you colors from one system to another,
you can store them using regular tuples instead of Color
instances.
You can then use the class static methods to perform the conversions.
Color
stores both the RGB and HSL representation of the color.
This makes possible to keep the hue intact when the color is a pure white
due to its lightness.
However, certain operations work only with the RGB values, and might then
lose the hue.
All the operations assume that you provide values in the specified ranges, no checks are made whatsoever. If you provide a value outside of the specified ranges, you’ll get some strange results...
The class instances are immutable, all the methods return a new instance
of the Color
class, and all the properties are read-only.
Note
Some operations may provide results a bit outside the specified ranges, the results are not capped. This is due to certain color systems having a widers gamut than others.
Class content¶
- Class Constants
- Conversion functions
Color.RgbToHsl()
Color.HslToRgb()
Color.RgbToHsv()
Color.HsvToRgb()
Color.RgbToYiq()
Color.YiqToRgb()
Color.RgbToYuv()
Color.YuvToRgb()
Color.RgbToXyz()
Color.XyzToRgb()
Color.XyzToLab()
Color.LabToXyz()
Color.CmykToCmy()
Color.CmyToCmyk()
Color.RgbToCmy()
Color.CmyToRgb()
Color.RgbToHtml()
Color.HtmlToRgb()
Color.RgbToPil()
Color.PilToRgb()
Color.RgbToWebSafe()
Color.RgbToGreyscale()
Color.RgbToRyb()
Color.RybToRgb()
- Instantiation functions
Color.NewFromRgb()
Color.NewFromHsl()
Color.NewFromHsv()
Color.NewFromYiq()
Color.NewFromYuv()
Color.NewFromXyz()
Color.NewFromLab()
Color.NewFromCmy()
Color.NewFromCmyk()
Color.NewFromHtml()
Color.NewFromPil()
- Properties
Color.alpha
Color.whiteRef
Color.rgb
Color.hue
Color.hsl
Color.hsv
Color.yiq
Color.yuv
Color.xyz
Color.lab
Color.cmy
Color.cmyk
Color.html
Color.pil
Color.webSafe
Color.greyscale
- Manipulation methods
Color.ColorWithAlpha()
Color.ColorWithWhiteRef()
Color.ColorWithHue()
Color.ColorWithSaturation()
Color.ColorWithLightness()
Color.DarkerColor()
Color.LighterColor()
Color.Saturate()
Color.Desaturate()
Color.WebSafeDither()
- Generation methods
Color.Gradient()
Color.ComplementaryColor()
Color.TriadicScheme()
Color.TetradicScheme()
Color.AnalogousScheme()
- Blending methods
Color.AlphaBlend()
Color.Blend()
Example usage¶
To create an instance of the grapefruit.Color from RGB values:
>>> import grapefruit >>> r, g, b = 1, 0.5, 0 >>> col = grapefruit.Color.NewFromRgb(r, g, b)To get the values of the color in another colorspace:
>>> h, s, v = col.hsv >>> l, a, b = col.labTo get the complementary of a color:
>>> compl = col.ComplementaryColor() >>> print compl.hsl (210.0, 1.0, 0.5)To directly convert RGB values to their HSL equivalent:
>>> h, s, l = Color.RgbToHsl(r, g, b)
Class Constants¶
-
Color.
WHITE_REFERENCE
¶
The reference white points of the CIE standards illuminants, calculated from the chromaticity coordinates found at: http://en.wikipedia.org/wiki/Standard_illuminant
A dictionary mapping the name of the CIE standard illuminants to their reference white points. The white points are required for the XYZ <-> L*a*b conversions.
The key names are build using the following pattern: <observer>_<illuminant>
The possible values for <observer>
are:
Value Observer std CIE 1931 2° Standard Observer sup CIE 1964 10° Supplementary Observer
The possible values for <illuminant>
are the name of the standard illuminants:
Value CCT Illuminant A 2856 K Incandescent tungsten B 4874 K Direct sunlight at noon (obsolete) C 6774 K North sky daylight (obsolete) D50 5003 K ICC Profile PCS. Horizon light. D55 5503 K Compromise between incandescent and daylight D65 6504 K Noon daylight (TV & sRGB colorspace) D75 7504 K North sky day light E ~5455 K Equal energy radiator (not a black body) F1 6430 K Daylight Fluorescent F2 4230 K Cool White Fluorescent F3 3450 K White Fluorescent F4 2940 K Warm White Fluorescent F5 6350 K Daylight Fluorescent F6 4150 K Lite White Fluorescent F7 6500 K Broadband fluorescent, D65 simulator F8 5000 K Broadband fluorescent, D50 simulator F9 4150 K Broadband fluorescent, Cool White Deluxe F10 5000 K Narrowband fluorescent, Philips TL85, Ultralume 50 F11 4000 K Narrowband fluorescent, Philips TL84, Ultralume 40 F12 3000 K Narrowband fluorescent, Philips TL83, Ultralume 30
-
Color.
NAMED_COLOR
¶
The names and RGB values of the X11 colors supported by popular browsers, with the gray/grey spelling issues, fixed so that both work (e.g light*grey* and light*gray*).
Note: For Gray, Green, Maroon and Purple, the HTML/CSS values are used instead of the X11 ones (see X11/CSS clashes)
Reference: CSS3 Color module
Conversion functions¶
The conversion functions are static methods of the Color
class that
let you convert a color stored as the list of its components rather than
as a Color
instance.
Instantiation functions¶
The instantiation functions let you create a new instance of the Color
class from the color components using the color system of your choice.
Properties¶
The properties get the value of the instance in the specified color model.
The properties returning calculated values unless marked otherwise.
Note
All the properties are read-only. You need to make a copy of the instance to modify the color value.
-
Color.
alpha
¶ The transparency of this color. 0.0 is transparent and 1.0 is fully opaque.
This value is not calculated, the stored value is returned directly.
-
Color.
rgb
¶ The RGB values of this Color.
This value is not calculated, the stored value is returned directly.
-
Color.
hsl
¶ The HSL values of this Color.
This value is not calculated, the stored value is returned directly.
-
Color.
hsv
¶ The HSV values of this Color.
-
Color.
yiq
¶ The YIQ values of this Color.
-
Color.
yuv
¶ The YUV values of this Color.
-
Color.
xyz
¶ The CIE-XYZ values of this Color.
-
Color.
lab
¶ The CIE-LAB values of this Color.
-
Color.
cmy
¶ The CMY values of this Color.
-
Color.
cmyk
¶ The CMYK values of this Color.
-
Color.
html
¶ This Color as an HTML color definition.
-
Color.
pil
¶ This Color as a PIL compatible value.
-
Color.
greyscale
¶
Manipulation methods¶
The manipulations methods let you create a new color by changing an existing color properties.
Note
The methods do not modify the current Color instance. They create a new instance or a tuple of new instances with the specified modifications.
Generation methods¶
The generation methods let you create a color scheme by using a color as the start point.
All the method, appart from Gradient and MonochromeScheme, have a ‘mode’ parameter that let you choose which color wheel should be used to generate the scheme.
- The following modes are available:
ryb: The RYB color wheel, or artistic color wheel. While scientifically incorrect, it generally produces better schemes than RGB. rgb: The standard RGB color wheel.