Welcome! This is the documentation for GrapeFruit 0.1a3, last updated January 28, 2022.
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 functionalities. 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 wider 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
- Properties
- Manipulation methods
- Generation methods
- Blending methods
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.
-
static
Color.
RgbToHsl
(r, g, b)¶ Convert the color from RGB coordinates to HSL.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- The color as an (h, s, l) tuple in the range: h[0…360], s[0…1], l[0…1]
>>> Color.RgbToHsl(1, 0.5, 0) (30.0, 1.0, 0.5)
-
static
Color.
HslToRgb
(h, s, l)¶ Convert the color from HSL coordinates to RGB.
- Parameters:
h: The Hue component value [0…1] s: The Saturation component value [0…1] l: The Lightness component value [0…1] - Returns:
- The color as an (r, g, b) tuple in the range: r[0…1], g[0…1], b[0…1]
>>> Color.HslToRgb(30.0, 1.0, 0.5) (1.0, 0.5, 0.0)
-
static
Color.
RgbToHsv
(r, g, b)¶ Convert the color from RGB coordinates to HSV.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- The color as an (h, s, v) tuple in the range: h[0…360], s[0…1], v[0…1]
>>> Color.RgbToHsv(1, 0.5, 0) (30.0, 1, 1)
-
static
Color.
HsvToRgb
(h, s, v)¶ Convert the color from RGB coordinates to HSV.
- Parameters:
h: The Hus component value [0…1] s: The Saturation component value [0…1] v: The Value component [0…1] - Returns:
- The color as an (r, g, b) tuple in the range: r[0…1], g[0…1], b[0…1]
>>> Color.HslToRgb(30.0, 1.0, 0.5) (1.0, 0.5, 0.0)
-
static
Color.
RgbToYiq
(r, g, b)¶ Convert the color from RGB to YIQ.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- The color as an (y, i, q) tuple in the range: y[0…1], i[0…1], q[0…1]
>>> '(%g, %g, %g)' % Color.RgbToYiq(1, 0.5, 0) '(0.592263, 0.458874, -0.0499818)'
-
static
Color.
YiqToRgb
(y, i, q)¶ Convert the color from YIQ coordinates to RGB.
- Parameters:
y: Tte Y component value [0…1] i: The I component value [0…1] q: The Q component value [0…1] - Returns:
- The color as an (r, g, b) tuple in the range: r[0…1], g[0…1], b[0…1]
>>> '(%g, %g, %g)' % Color.YiqToRgb(0.592263, 0.458874, -0.0499818) '(1, 0.5, 5.442e-007)'
-
static
Color.
RgbToYuv
(r, g, b)¶ Convert the color from RGB coordinates to YUV.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- The color as an (y, u, v) tuple in the range: y[0…1], u[-0.436…0.436], v[-0.615…0.615]
>>> '(%g, %g, %g)' % Color.RgbToYuv(1, 0.5, 0) '(0.5925, -0.29156, 0.357505)'
-
static
Color.
YuvToRgb
(y, u, v)¶ Convert the color from YUV coordinates to RGB.
- Parameters:
y: The Y component value [0…1] u: The U component value [-0.436…0.436] v: The V component value [-0.615…0.615] - Returns:
- The color as an (r, g, b) tuple in the range: r[0…1], g[0…1], b[0…1]
>>> '(%g, %g, %g)' % Color.YuvToRgb(0.5925, -0.2916, 0.3575) '(0.999989, 0.500015, -6.3276e-005)'
-
static
Color.
RgbToXyz
(r, g, b)¶ Convert the color from sRGB to CIE XYZ.
The methods assumes that the RGB coordinates are given in the sRGB colorspace (D65).
Note
Compensation for the sRGB gamma correction is applied before converting.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- The color as an (x, y, z) tuple in the range: x[0…1], y[0…1], z[0…1]
>>> '(%g, %g, %g)' % Color.RgbToXyz(1, 0.5, 0) '(0.488941, 0.365682, 0.0448137)'
-
static
Color.
XyzToRgb
(x, y, z)¶ Convert the color from CIE XYZ coordinates to sRGB.
Note
Compensation for sRGB gamma correction is applied before converting.
- Parameters:
x: The X component value [0…1] y: The Y component value [0…1] z: The Z component value [0…1] - Returns:
- The color as an (r, g, b) tuple in the range: r[0…1], g[0…1], b[0…1]
>>> '(%g, %g, %g)' % Color.XyzToRgb(0.488941, 0.365682, 0.0448137) '(1, 0.5, 6.81883e-008)'
-
static
Color.
XyzToLab
(x, y, z, wref=(0.95043, 1.0, 1.0889))¶ Convert the color from CIE XYZ to CIE L*a*b*.
- Parameters:
x: The X component value [0…1] y: The Y component value [0…1] z: The Z component value [0…1] wref: The whitepoint reference, default is 2° D65. - Returns:
- The color as an (L, a, b) tuple in the range: L[0…100], a[-1…1], b[-1…1]
>>> '(%g, %g, %g)' % Color.XyzToLab(0.488941, 0.365682, 0.0448137) '(66.9518, 0.43084, 0.739692)'
>>> '(%g, %g, %g)' % Color.XyzToLab(0.488941, 0.365682, 0.0448137, Color.WHITE_REFERENCE['std_D50']) '(66.9518, 0.411663, 0.67282)'
-
static
Color.
LabToXyz
(l, a, b, wref=(0.95043, 1.0, 1.0889))¶ Convert the color from CIE L*a*b* to CIE 1931 XYZ.
- Parameters:
l: The L component [0…100] a: The a component [-1…1] b: The a component [-1…1] wref: The whitepoint reference, default is 2° D65. - Returns:
- The color as an (x, y, z) tuple in the range: x[0…q], y[0…1], z[0…1]
>>> '(%g, %g, %g)' % Color.LabToXyz(66.9518, 0.43084, 0.739692) '(0.488941, 0.365682, 0.0448137)'
>>> '(%g, %g, %g)' % Color.LabToXyz(66.9518, 0.411663, 0.67282, Color.WHITE_REFERENCE['std_D50']) '(0.488941, 0.365682, 0.0448138)'
-
static
Color.
CmykToCmy
(c, m, y, k)¶ Convert the color from CMYK coordinates to CMY.
- Parameters:
c: The Cyan component value [0…1] m: The Magenta component value [0…1] y: The Yellow component value [0…1] k: The Black component value [0…1] - Returns:
- The color as an (c, m, y) tuple in the range: c[0…1], m[0…1], y[0…1]
>>> '(%g, %g, %g)' % Color.CmykToCmy(1, 0.32, 0, 0.5) '(1, 0.66, 0.5)'
-
static
Color.
CmyToCmyk
(c, m, y)¶ Convert the color from CMY coordinates to CMYK.
- Parameters:
c: The Cyan component value [0…1] m: The Magenta component value [0…1] y: The Yellow component value [0…1] - Returns:
- The color as an (c, m, y, k) tuple in the range: c[0…1], m[0…1], y[0…1], k[0…1]
>>> '(%g, %g, %g, %g)' % Color.CmyToCmyk(1, 0.66, 0.5) '(1, 0.32, 0, 0.5)'
-
static
Color.
RgbToCmy
(r, g, b)¶ Convert the color from RGB coordinates to CMY.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- The color as an (c, m, y) tuple in the range: c[0…1], m[0…1], y[0…1]
>>> Color.RgbToCmy(1, 0.5, 0) (0, 0.5, 1)
-
static
Color.
CmyToRgb
(c, m, y)¶ Convert the color from CMY coordinates to RGB.
- Parameters:
c: The Cyan component value [0…1] m: The Magenta component value [0…1] y: The Yellow component value [0…1] - Returns:
- The color as an (r, g, b) tuple in the range: r[0…1], g[0…1], b[0…1]
>>> Color.CmyToRgb(0, 0.5, 1) (1, 0.5, 0)
-
static
Color.
RgbToHtml
(r, g, b)¶ Convert the color from (r, g, b) to #RRGGBB.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- A CSS string representation of this color (#RRGGBB).
>>> Color.RgbToHtml(1, 0.5, 0) '#ff8000'
-
static
Color.
HtmlToRgb
(html)¶ Convert the HTML color to (r, g, b).
- Parameters:
html: the HTML definition of the color (#RRGGBB or #RGB or a color name). - Returns:
- The color as an (r, g, b) tuple in the range: r[0…1], g[0…1], b[0…1]
- Throws:
ValueError: If html is neither a known color name or a hexadecimal RGB representation.
>>> '(%g, %g, %g)' % Color.HtmlToRgb('#ff8000') '(1, 0.501961, 0)' >>> '(%g, %g, %g)' % Color.HtmlToRgb('ff8000') '(1, 0.501961, 0)' >>> '(%g, %g, %g)' % Color.HtmlToRgb('#f60') '(1, 0.4, 0)' >>> '(%g, %g, %g)' % Color.HtmlToRgb('f60') '(1, 0.4, 0)' >>> '(%g, %g, %g)' % Color.HtmlToRgb('lemonchiffon') '(1, 0.980392, 0.803922)'
-
static
Color.
RgbToPil
(r, g, b)¶ Convert the color from RGB to a PIL-compatible integer.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- A PIL compatible integer (0xBBGGRR).
>>> '0x%06x' % Color.RgbToPil(1, 0.5, 0) '0x0080ff'
-
static
Color.
PilToRgb
(pil)¶ Convert the color from a PIL-compatible integer to RGB.
- Parameters:
- pil: a PIL compatible color representation (0xBBGGRR)
- Returns:
- The color as an (r, g, b) tuple in the range: the range: r: [0…1] g: [0…1] b: [0…1]
>>> '(%g, %g, %g)' % Color.PilToRgb(0x0080ff) '(1, 0.501961, 0)'
-
static
Color.
RgbToWebSafe
(r, g, b, alt=False)¶ Convert the color from RGB to ‘web safe’ RGB
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] alt: If True, use the alternative color instead of the nearest one. Can be used for dithering. - Returns:
- The color as an (r, g, b) tuple in the range: the range: r[0…1], g[0…1], b[0…1]
>>> '(%g, %g, %g)' % Color.RgbToWebSafe(1, 0.55, 0.0) '(1, 0.6, 0)'
-
static
Color.
RgbToGreyscale
(r, g, b)¶ Convert the color from RGB to its greyscale equivalent
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] - Returns:
- The color as an (r, g, b) tuple in the range: the range: r[0…1], g[0…1], b[0…1]
>>> '(%g, %g, %g)' % Color.RgbToGreyscale(1, 0.8, 0) '(0.6, 0.6, 0.6)'
-
static
Color.
RgbToRyb
(hue)¶ Maps a hue on the RGB color wheel to Itten’s RYB wheel.
- Parameters:
hue: The hue on the RGB color wheel [0…360] - Returns:
- An approximation of the corresponding hue on Itten’s RYB wheel.
>>> Color.RgbToRyb(15) 26
-
static
Color.
RybToRgb
(hue)¶ Maps a hue on Itten’s RYB color wheel to the standard RGB wheel.
- Parameters:
hue: The hue on Itten’s RYB color wheel [0…360] - Returns:
- An approximation of the corresponding hue on the standard RGB wheel.
>>> Color.RybToRgb(15) 8
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.
-
static
Color.
NewFromRgb
(r, g, b, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified RGB values.
- Parameters:
r: The Red component value [0…1] g: The Green component value [0…1] b: The Blue component value [0…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromRgb(1.0, 0.5, 0.0) (1.0, 0.5, 0.0, 1.0) >>> Color.NewFromRgb(1.0, 0.5, 0.0, 0.5) (1.0, 0.5, 0.0, 0.5)
-
static
Color.
NewFromHsl
(h, s, l, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified HSL values.
- Parameters:
h: The Hue component value [0…1] s: The Saturation component value [0…1] l: The Lightness component value [0…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 1, 0.5) (1.0, 0.5, 0.0, 1.0) >>> Color.NewFromHsl(30, 1, 0.5, 0.5) (1.0, 0.5, 0.0, 0.5)
-
static
Color.
NewFromHsv
(h, s, v, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified HSV values.
- Parameters:
h: The Hus component value [0…1] s: The Saturation component value [0…1] v: The Value component [0…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsv(30, 1, 1) (1.0, 0.5, 0.0, 1.0) >>> Color.NewFromHsv(30, 1, 1, 0.5) (1.0, 0.5, 0.0, 0.5)
-
static
Color.
NewFromYiq
(y, i, q, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified YIQ values.
- Parameters:
y: The Y component value [0…1] i: The I component value [0…1] q: The Q component value [0…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> str(Color.NewFromYiq(0.5922, 0.45885,-0.05)) '(0.999902, 0.499955, -6.6905e-005, 1)' >>> str(Color.NewFromYiq(0.5922, 0.45885,-0.05, 0.5)) '(0.999902, 0.499955, -6.6905e-005, 0.5)'
-
static
Color.
NewFromYuv
(y, u, v, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified YUV values.
- Parameters:
y: The Y component value [0…1] u: The U component value [-0.436…0.436] v: The V component value [-0.615…0.615] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> str(Color.NewFromYuv(0.5925, -0.2916, 0.3575)) '(0.999989, 0.500015, -6.3276e-005, 1)' >>> str(Color.NewFromYuv(0.5925, -0.2916, 0.3575, 0.5)) '(0.999989, 0.500015, -6.3276e-005, 0.5)'
-
static
Color.
NewFromXyz
(x, y, z, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified CIE-XYZ values.
- Parameters:
x: The Red component value [0…1] y: The Green component value [0…1] z: The Blue component value [0…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> str(Color.NewFromXyz(0.488941, 0.365682, 0.0448137)) '(1, 0.5, 6.81883e-008, 1)' >>> str(Color.NewFromXyz(0.488941, 0.365682, 0.0448137, 0.5)) '(1, 0.5, 6.81883e-008, 0.5)'
-
static
Color.
NewFromLab
(l, a, b, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified CIE-LAB values.
- Parameters:
l: The L component [0…100] a: The a component [-1…1] b: The a component [-1…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> str(Color.NewFromLab(66.9518, 0.43084, 0.739692)) '(1, 0.5, 1.09491e-008, 1)' >>> str(Color.NewFromLab(66.9518, 0.43084, 0.739692, wref=Color.WHITE_REFERENCE['std_D50'])) '(1.01238, 0.492011, -0.14311, 1)' >>> str(Color.NewFromLab(66.9518, 0.43084, 0.739692, 0.5)) '(1, 0.5, 1.09491e-008, 0.5)' >>> str(Color.NewFromLab(66.9518, 0.43084, 0.739692, 0.5, Color.WHITE_REFERENCE['std_D50'])) '(1.01238, 0.492011, -0.14311, 0.5)'
-
static
Color.
NewFromCmy
(c, m, y, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified CMY values.
- Parameters:
c: The Cyan component value [0…1] m: The Magenta component value [0…1] y: The Yellow component value [0…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromCmy(0, 0.5, 1) (1, 0.5, 0, 1.0) >>> Color.NewFromCmy(0, 0.5, 1, 0.5) (1, 0.5, 0, 0.5)
-
static
Color.
NewFromCmyk
(c, m, y, k, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified CMYK values.
- Parameters:
c: The Cyan component value [0…1] m: The Magenta component value [0…1] y: The Yellow component value [0…1] k: The Black component value [0…1] alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> str(Color.NewFromCmyk(1, 0.32, 0, 0.5)) '(0, 0.34, 0.5, 1)' >>> str(Color.NewFromCmyk(1, 0.32, 0, 0.5, 0.5)) '(0, 0.34, 0.5, 0.5)'
-
static
Color.
NewFromHtml
(html, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified HTML color definition.
- Parameters:
html: The HTML definition of the color (#RRGGBB or #RGB or a color name). alpha: The color transparency [0…1], default is opaque. wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> str(Color.NewFromHtml('#ff8000')) '(1, 0.501961, 0, 1)' >>> str(Color.NewFromHtml('ff8000')) '(1, 0.501961, 0, 1)' >>> str(Color.NewFromHtml('#f60')) '(1, 0.4, 0, 1)' >>> str(Color.NewFromHtml('f60')) '(1, 0.4, 0, 1)' >>> str(Color.NewFromHtml('lemonchiffon')) '(1, 0.980392, 0.803922, 1)' >>> str(Color.NewFromHtml('#ff8000', 0.5)) '(1, 0.501961, 0, 0.5)'
-
static
Color.
NewFromPil
(pil, alpha=1.0, wref=(0.95043, 1.0, 1.0889))¶ Create a new instance based on the specified PIL color.
- Parameters:
pil: A PIL compatible color representation (0xBBGGRR) alpha: The color transparency [0…1], default is opaque wref: The whitepoint reference, default is 2° D65. - Returns:
- A grapefruit.Color instance.
>>> str(Color.NewFromPil(0x0080ff)) '(1, 0.501961, 0, 1)' >>> str(Color.NewFromPil(0x0080ff, 0.5)) '(1, 0.501961, 0, 0.5)'
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.
whiteRef
¶ the white reference point of this color.
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.
hue
¶ The hue 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.
webSafe
¶ The web safe color nearest to this one (RGB).
-
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.
-
Color.
ColorWithAlpha
(alpha)¶ Create a new instance based on this one with a new alpha value.
- Parameters:
alpha: The transparency of the new color [0…1]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromRgb(1.0, 0.5, 0.0, 1.0).ColorWithAlpha(0.5) (1.0, 0.5, 0.0, 0.5)
-
Color.
ColorWithWhiteRef
(wref, labAsRef=False)¶ Create a new instance based on this one with a new white reference.
- Parameters:
wref: The whitepoint reference. labAsRef: If True, the L*a*b* values of the current instance are used as reference for the new color; otherwise, the RGB values are used as reference. - Returns:
- A grapefruit.Color instance.
>>> c = Color.NewFromRgb(1.0, 0.5, 0.0, 1.0, Color.WHITE_REFERENCE['std_D65'])
>>> c2 = c.ColorWithWhiteRef(Color.WHITE_REFERENCE['sup_D50']) >>> c2.rgb (1.0, 0.5, 0.0) >>> '(%g, %g, %g)' % c2.whiteRef '(0.96721, 1, 0.81428)'
>>> c2 = c.ColorWithWhiteRef(Color.WHITE_REFERENCE['sup_D50'], labAsRef=True) >>> '(%g, %g, %g)' % c2.rgb '(1.01463, 0.490339, -0.148131)' >>> '(%g, %g, %g)' % c2.whiteRef '(0.96721, 1, 0.81428)' >>> '(%g, %g, %g)' % c.lab '(66.9518, 0.43084, 0.739692)' >>> '(%g, %g, %g)' % c2.lab '(66.9518, 0.43084, 0.739693)'
-
Color.
ColorWithHue
(hue)¶ Create a new instance based on this one with a new hue.
- Parameters:
hue: The hue of the new color [0…360]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 1, 0.5).ColorWithHue(60) (1.0, 1.0, 0.0, 1.0) >>> Color.NewFromHsl(30, 1, 0.5).ColorWithHue(60).hsl (60, 1, 0.5)
-
Color.
ColorWithSaturation
(saturation)¶ Create a new instance based on this one with a new saturation value.
Note
The saturation is defined for the HSL mode.
- Parameters:
saturation: The saturation of the new color [0…1]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 1, 0.5).ColorWithSaturation(0.5) (0.75, 0.5, 0.25, 1.0) >>> Color.NewFromHsl(30, 1, 0.5).ColorWithSaturation(0.5).hsl (30, 0.5, 0.5)
-
Color.
ColorWithLightness
(lightness)¶ Create a new instance based on this one with a new lightness value.
- Parameters:
lightness: The lightness of the new color [0…1]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 1, 0.5).ColorWithLightness(0.25) (0.5, 0.25, 0.0, 1.0) >>> Color.NewFromHsl(30, 1, 0.5).ColorWithLightness(0.25).hsl (30, 1, 0.25)
-
Color.
DarkerColor
(level)¶ Create a new instance based on this one but darker.
- Parameters:
level: The amount by which the color should be darkened to produce the new one [0…1]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 1, 0.5).DarkerColor(0.25) (0.5, 0.25, 0.0, 1.0) >>> Color.NewFromHsl(30, 1, 0.5).DarkerColor(0.25).hsl (30, 1, 0.25)
-
Color.
LighterColor
(level)¶ Create a new instance based on this one but lighter.
- Parameters:
level: The amount by which the color should be lightened to produce the new one [0…1]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 1, 0.5).LighterColor(0.25) (1.0, 0.75, 0.5, 1.0) >>> Color.NewFromHsl(30, 1, 0.5).LighterColor(0.25).hsl (30, 1, 0.75)
-
Color.
Saturate
(level)¶ Create a new instance based on this one but more saturated.
- Parameters:
level: The amount by which the color should be saturated to produce the new one [0…1]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 0.5, 0.5).Saturate(0.25) (0.875, 0.5, 0.125, 1.0) >>> Color.NewFromHsl(30, 0.5, 0.5).Saturate(0.25).hsl (30, 0.75, 0.5)
-
Color.
Desaturate
(level)¶ Create a new instance based on this one but less saturated.
- Parameters:
level: The amount by which the color should be desaturated to produce the new one [0…1]. - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 0.5, 0.5).Desaturate(0.25) (0.625, 0.5, 0.375, 1.0) >>> Color.NewFromHsl(30, 0.5, 0.5).Desaturate(0.25).hsl (30, 0.25, 0.5)
-
Color.
WebSafeDither
()¶ Return the two websafe colors nearest to this one.
- Returns:
- A tuple of two grapefruit.Color instances which are the two web safe colors closest this one.
>>> c = Color.NewFromRgb(1.0, 0.45, 0.0) >>> c1, c2 = c.WebSafeDither() >>> str(c1) '(1, 0.4, 0, 1)' >>> str(c2) '(1, 0.6, 0, 1)'
Generation methods¶
The generation methods let you create a color scheme by using a color as the start point.
All the method, apart 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.
-
Color.
Gradient
(target, steps=100)¶ Create a list with the gradient colors between this and the other color.
- Parameters:
target: The grapefruit.Color at the other end of the gradient. steps: The number of gradients steps to create. - Returns:
- A list of grapefruit.Color instances.
>>> c1 = Color.NewFromRgb(1.0, 0.0, 0.0, alpha=1) >>> c2 = Color.NewFromRgb(0.0, 1.0, 0.0, alpha=0) >>> c1.Gradient(c2, 3) [(0.75, 0.25, 0.0, 0.75), (0.5, 0.5, 0.0, 0.5), (0.25, 0.75, 0.0, 0.25)]
-
Color.
ComplementaryColor
(mode='ryb')¶ Create a new instance which is the complementary color of this one.
- Parameters:
mode: Select which color wheel to use for the generation (ryb/rgb). - Returns:
- A grapefruit.Color instance.
>>> Color.NewFromHsl(30, 1, 0.5).ComplementaryColor() (0.0, 0.5, 1.0, 1.0) >>> Color.NewFromHsl(30, 1, 0.5).ComplementaryColor().hsl (210, 1, 0.5)
-
Color.
MonochromeScheme
()¶ Return 4 colors in the same hue with varying saturation/lightness.
- Returns:
- A tuple of 4 grapefruit.Color in the same hue as this one, with varying saturation/lightness.
>>> c = Color.NewFromHsl(30, 0.5, 0.5) >>> ['(%g, %g, %g)' % clr.hsl for clr in c.MonochromeScheme()] ['(30, 0.2, 0.8)', '(30, 0.5, 0.3)', '(30, 0.2, 0.6)', '(30, 0.5, 0.8)']
-
Color.
TriadicScheme
(angle=120, mode='ryb')¶ Return two colors forming a triad or a split complementary with this one.
- Parameters:
angle: The angle between the hues of the created colors. The default value makes a triad. mode: Select which color wheel to use for the generation (ryb/rgb). - Returns:
- A tuple of two grapefruit.Color forming a color triad with this one or a split complementary.
>>> c1 = Color.NewFromHsl(30, 1, 0.5)
>>> c2, c3 = c1.TriadicScheme() >>> c2.hsl (150.0, 1, 0.5) >>> c3.hsl (270.0, 1, 0.5)
>>> c2, c3 = c1.TriadicScheme(40) >>> c2.hsl (190.0, 1, 0.5) >>> c3.hsl (230.0, 1, 0.5)
-
Color.
TetradicScheme
(angle=30, mode='ryb')¶ Return three colors forming a tetrad with this one.
- Parameters:
angle: The angle to subtract from the adjacent colors hues [-90…90]. You can use an angle of zero to generate a square tetrad. mode: Select which color wheel to use for the generation (ryb/rgb). - Returns:
- A tuple of three grapefruit.Color forming a color tetrad with this one.
>>> col = Color.NewFromHsl(30, 1, 0.5) >>> [c.hsl for c in col.TetradicScheme(mode='rgb', angle=30)] [(90, 1, 0.5), (210, 1, 0.5), (270, 1, 0.5)]
-
Color.
AnalogousScheme
(angle=30, mode='ryb')¶ Return two colors analogous to this one.
- Args:
angle: The angle between the hues of the created colors and this one. mode: Select which color wheel to use for the generation (ryb/rgb). - Returns:
- A tuple of grapefruit.Colors analogous to this one.
>>> c1 = Color.NewFromHsl(30, 1, 0.5)
>>> c2, c3 = c1.AnalogousScheme() >>> c2.hsl (330, 1, 0.5) >>> c3.hsl (90, 1, 0.5)
>>> c2, c3 = c1.AnalogousScheme(10) >>> c2.hsl (20, 1, 0.5) >>> c3.hsl (40, 1, 0.5)
Blending methods¶
-
Color.
AlphaBlend
(other)¶ Alpha-blend this color on the other one.
- Args:
other: The grapefruit.Color to alpha-blend with this one. - Returns:
- A grapefruit.Color instance which is the result of alpha-blending this color on the other one.
>>> c1 = Color.NewFromRgb(1, 0.5, 0, 0.2) >>> c2 = Color.NewFromRgb(1, 1, 1, 0.8) >>> c3 = c1.AlphaBlend(c2) >>> str(c3) '(1, 0.875, 0.75, 0.84)'
-
Color.
Blend
(other, percent=0.5)¶ Blend this color with the other one.
- Args:
other: the grapefruit.Color to blend with this one. - Returns:
- A grapefruit.Color instance which is the result of blending this color on the other one.
>>> c1 = Color.NewFromRgb(1, 0.5, 0, 0.2) >>> c2 = Color.NewFromRgb(1, 1, 1, 0.6) >>> c3 = c1.Blend(c2) >>> str(c3) '(1, 0.75, 0.5, 0.4)'