GrapeFruit - Color manipulation in Python
Hold a color value.
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.lab
To 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)
Alpha-blend this color on the other one.
other: | The grapefruit.Color to alpha-blend with this 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)'
Return two colors analogous to this one.
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). |
>>> 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)
Blend this color with the other one.
other: | the grapefruit.Color to blend with this 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)'
Convert the color from CMY coordinates to CMYK.
c: | The Cyan component value [0...1] |
---|---|
m: | The Magenta component value [0...1] |
y: | The Yellow component value [0...1] |
>>> '(%g, %g, %g, %g)' % Color.CmyToCmyk(1, 0.66, 0.5)
'(1, 0.32, 0, 0.5)'
Convert the color from CMY coordinates to RGB.
c: | The Cyan component value [0...1] |
---|---|
m: | The Magenta component value [0...1] |
y: | The Yellow component value [0...1] |
>>> Color.CmyToRgb(0, 0.5, 1)
(1, 0.5, 0)
Convert the color from CMYK coordinates to CMY.
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] |
>>> '(%g, %g, %g)' % Color.CmykToCmy(1, 0.32, 0, 0.5)
'(1, 0.66, 0.5)'
Create a new instance based on this one with a new alpha value.
alpha: | The transparency of the new color [0...1]. |
---|
>>> Color.NewFromRgb(1.0, 0.5, 0.0, 1.0).ColorWithAlpha(0.5)
(1.0, 0.5, 0.0, 0.5)
Create a new instance based on this one with a new hue.
hue: | The hue of the new color [0...360]. |
---|
>>> 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)
Create a new instance based on this one with a new lightness value.
lightness: | The lightness of the new color [0...1]. |
---|
>>> 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)
Create a new instance based on this one with a new saturation value.
Note
The saturation is defined for the HSL mode.
saturation: | The saturation of the new color [0...1]. |
---|
>>> 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)
Create a new instance based on this one with a new white reference.
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. |
>>> 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)'
Create a new instance which is the complementary color of this one.
mode: | Select which color wheel to use for the generation (ryb/rgb). |
---|
>>> 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)
Create a new instance based on this one but darker.
level: | The amount by which the color should be darkened to produce the new one [0...1]. |
---|
>>> 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)
Create a new instance based on this one but less saturated.
level: | The amount by which the color should be desaturated to produce the new one [0...1]. |
---|
>>> 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)
Create a list with the gradient colors between this and the other color.
target: | The grapefruit.Color at the other end of the gradient. |
---|---|
steps: | The number of gradients steps to create. |
>>> 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)]
Convert the color from HSL coordinates to RGB.
h: | The Hue component value [0...1] |
---|---|
s: | The Saturation component value [0...1] |
l: | The Lightness component value [0...1] |
>>> Color.HslToRgb(30.0, 1.0, 0.5)
(1.0, 0.5, 0.0)
Convert the color from RGB coordinates to HSV.
h: | The Hus component value [0...1] |
---|---|
s: | The Saturation component value [0...1] |
v: | The Value component [0...1] |
>>> Color.HslToRgb(30.0, 1.0, 0.5)
(1.0, 0.5, 0.0)
Convert the HTML color to (r, g, b).
html: | the HTML definition of the color (#RRGGBB or #RGB or a color name). |
---|
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)'
Convert the color from CIE L*a*b* to CIE 1931 XYZ.
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. |
>>> '(%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)'
Create a new instance based on this one but lighter.
level: | The amount by which the color should be lightened to produce the new one [0...1]. |
---|
>>> 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)
Return 4 colors in the same hue 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)']
Create a new instance based on the specifed CMY values.
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. |
>>> 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)
Create a new instance based on the specifed CMYK values.
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. |
>>> 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)'
Create a new instance based on the specifed HSL values.
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. |
>>> 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)
Create a new instance based on the specifed HSV values.
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. |
>>> 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)
Create a new instance based on the specifed HTML color definition.
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. |
>>> 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)'
Create a new instance based on the specifed CIE-LAB values.
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. |
>>> 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)'
Create a new instance based on the specifed PIL color.
pil: | A PIL compatible color representation (0xBBGGRR) |
---|---|
alpha: | The color transparency [0...1], default is opaque |
wref: | The whitepoint reference, default is 2° D65. |
>>> str(Color.NewFromPil(0x0080ff))
'(1, 0.501961, 0, 1)'
>>> str(Color.NewFromPil(0x0080ff, 0.5))
'(1, 0.501961, 0, 0.5)'
Create a new instance based on the specifed RGB values.
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. |
>>> 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)
Create a new instance based on the specifed CIE-XYZ values.
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. |
>>> 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)'
Create a new instance based on the specifed YIQ values.
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. |
>>> 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)'
Create a new instance based on the specifed YUV values.
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. |
>>> 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)'
Convert the color from a PIL-compatible integer to RGB.
>>> '(%g, %g, %g)' % Color.PilToRgb(0x0080ff)
'(1, 0.501961, 0)'
Convert the color from RGB coordinates to CMY.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> Color.RgbToCmy(1, 0.5, 0)
(0, 0.5, 1)
Convert the color from RGB to its greyscale equivalent
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> '(%g, %g, %g)' % Color.RgbToGreyscale(1, 0.8, 0)
'(0.6, 0.6, 0.6)'
Convert the color from RGB coordinates to HSL.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> Color.RgbToHsl(1, 0.5, 0)
(30.0, 1.0, 0.5)
Convert the color from RGB coordinates to HSV.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> Color.RgbToHsv(1, 0.5, 0)
(30.0, 1, 1)
Convert the color from (r, g, b) to #RRGGBB.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> Color.RgbToHtml(1, 0.5, 0)
'#ff8000'
Convert the color from RGB to a PIL-compatible integer.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> '0x%06x' % Color.RgbToPil(1, 0.5, 0)
'0x0080ff'
Maps a hue on the RGB color wheel to Itten’s RYB wheel.
hue: | The hue on the RGB color wheel [0...360] |
---|
>>> Color.RgbToRyb(15)
26
Convert the color from RGB to ‘web safe’ RGB
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. |
>>> '(%g, %g, %g)' % Color.RgbToWebSafe(1, 0.55, 0.0)
'(1, 0.6, 0)'
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.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> '(%g, %g, %g)' % Color.RgbToXyz(1, 0.5, 0)
'(0.488941, 0.365682, 0.0448137)'
Convert the color from RGB to YIQ.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> '(%g, %g, %g)' % Color.RgbToYiq(1, 0.5, 0)
'(0.592263, 0.458874, -0.0499818)'
Convert the color from RGB coordinates to YUV.
r: | The Red component value [0...1] |
---|---|
g: | The Green component value [0...1] |
b: | The Blue component value [0...1] |
>>> '(%g, %g, %g)' % Color.RgbToYuv(1, 0.5, 0)
'(0.5925, -0.29156, 0.357505)'
Maps a hue on Itten’s RYB color wheel to the standard RGB wheel.
hue: | The hue on Itten’s RYB color wheel [0...360] |
---|
>>> Color.RybToRgb(15)
8
Create a new instance based on this one but more saturated.
level: | The amount by which the color should be saturated to produce the new one [0...1]. |
---|
>>> 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)
Return three colors froming a tetrad with this one.
angle: | The angle to substract 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). |
>>> 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)]
Return two colors forming a triad or a split complementary with this one.
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). |
>>> 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)
Return the two websafe colors nearest to 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)'
Convert the color from CIE XYZ to CIE L*a*b*.
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. |
>>> '(%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)'
Convert the color from CIE XYZ coordinates to sRGB.
Note
Compensation for sRGB gamma correction is applied before converting.
x: | The X component value [0...1] |
---|---|
y: | The Y component value [0...1] |
z: | The Z component value [0...1] |
>>> '(%g, %g, %g)' % Color.XyzToRgb(0.488941, 0.365682, 0.0448137)
'(1, 0.5, 6.81883e-008)'
Convert the color from YIQ coordinates to RGB.
y: | Tte Y component value [0...1] |
---|---|
i: | The I component value [0...1] |
q: | The Q component value [0...1] |
>>> '(%g, %g, %g)' % Color.YiqToRgb(0.592263, 0.458874, -0.0499818)
'(1, 0.5, 5.442e-007)'
Convert the color from YUV coordinates to RGB.
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] |
>>> '(%g, %g, %g)' % Color.YuvToRgb(0.5925, -0.2916, 0.3575)
'(0.999989, 0.500015, -6.3276e-005)'
The transparency of this color. 0.0 is transparent and 1.0 is fully opaque.
The CMY values of this Color.
The CMYK values of this Color.
The greyscale equivalent to this color (RGB).
The HSL values of this Color.
The HSV values of this Color.
This Color as an HTML color definition.
The hue of this color.
The CIE-LAB values of this Color.
This Color as a PIL compatible value.
The RGB values of this Color.
The web safe color nearest to this one (RGB).
the white reference point of this color.
The CIE-XYZ values of this Color.
The YIQ values of this Color.
The YUV values of this Color.