Welcome to ColourAlpha’s documentation!¶

Color Library.

This module defines several color formats that can be converted to one or another.

Formats¶

HSL:: 3-uple of Hue, Saturation, Lightness all between 0.0 and 1.0
RGB:: 3-uple of Red, Green, Blue all between 0.0 and 1.0
HEX:: string object beginning with ‘#’ and with red, green, blue value. This format accept color in 3 or 6 value ex: ‘#fff’ or ‘#ffffff’
WEB:: string object that defaults to HEX representation or human if possible

Usage¶

Several function exists to convert from one format to another. But all function are not written. So the best way is to use the object Color.

Please see the documentation of this object for more information.

Note

Some constants are defined for convenience in HSL, RGB, HEX

class colour.colour.C_HEX¶

RGB colors container.

Provides a quick color access.

>>> from colour import HEX

>>> HEX.WHITE
'#fff'
>>> HEX.BLUE
'#00f'

>>> HEX.DONOTEXISTS  
Traceback (most recent call last):
...
AttributeError: ... has no attribute 'DONOTEXISTS'

class colour.colour.C_HSL¶

HSL colors container.

Provides a quick color access.

>>> from colour import HSL

>>> HSL.WHITE
(0.0, 0.0, 1.0)
>>> HSL.BLUE 
(0.66..., 1.0, 0.5)

>>> HSL.DONOTEXISTS  
Traceback (most recent call last):
...
AttributeError: ... has no attribute 'DONOTEXISTS'

class colour.colour.C_RGB¶

RGB colors container.

Provides a quick color access.

>>> from colour import RGB

>>> RGB.WHITE
(1.0, 1.0, 1.0)
>>> RGB.BLUE
(0.0, 0.0, 1.0)

>>> RGB.DONOTEXISTS  
Traceback (most recent call last):
...
AttributeError: ... has no attribute 'DONOTEXISTS'

class colour.colour.Color(color: Optional[Union[str, colour.colour.Color]] = None, pick_for: Optional[object] = None, picker: Callable[[object], colour.colour.Color] = <function RGB_color_picker>, pick_key: Callable[[object], Union[str, int]] = <function hash_or_str>, **kwargs: Any)¶

Abstraction of a color object.

Color object keeps information of a color. It can input/output to different format (HSL, RGB, HEX, WEB) and their partial representation.

>>> from colour import Color, HSL

>>> b = Color()
>>> b.hsl = HSL.BLUE

>>> b.hue  
0.66...
>>> b.saturation
1.0
>>> b.luminance
0.5

>>> b.red
0.0
>>> b.blue
1.0
>>> b.green
0.0

>>> b.rgb
(0.0, 0.0, 1.0)
>>> b.hsl  
(0.66..., 1.0, 0.5)
>>> b.hex
'#00f'

Let’s change Hue toward red tint:

>>> b.hue = 0.0
>>> b.hex
'#f00'

>>> b.hue = 2.0/3
>>> b.hex
'#00f'

In the other way round:

>>> b.hex = '#f00'
>>> b.hsl
(0.0, 1.0, 0.5)

Long hex can be accessed directly:

>>> b.hex_l = '#123456'
>>> b.hex_l
'#123456'
>>> b.hex
'#123456'

>>> b.hex_l = '#ff0000'
>>> b.hex_l
'#ff0000'
>>> b.hex
'#f00'

>>> c = Color('blue')
>>> c
<Color blue>
>>> c.hue = 0
>>> c
<Color red>

>>> c.saturation = 0.0
>>> c.hsl  
(..., 0.0, 0.5)
>>> c.rgb
(0.5, 0.5, 0.5)
>>> c.hex
'#7f7f7f'
>>> c
<Color #7f7f7f>

>>> c.luminance = 0.0
>>> c
<Color black>

>>> c.hex
'#000'

>>> c.green = 1.0
>>> c.blue = 1.0
>>> c.hex
'#0ff'
>>> c
<Color cyan>

>>> c = Color('blue', luminance=0.75)
>>> c
<Color #7f7fff>

>>> c = Color('red', red=0.5)
>>> c
<Color #7f0000>

>>> print(c)
#7f0000

You can try to query unexisting attributes:

>>> c.lightness  
Traceback (most recent call last):
...
AttributeError: 'lightness' not found

TODO: could add HSV, CMYK, YUV conversion.

# >>> b.hsv # >>> b.value # >>> b.cyan # >>> b.magenta # >>> b.yellow # >>> b.key # >>> b.cmyk

To support blind conversion of web strings (or already converted object), the Color object supports instantiation with another Color object.

>>> Color(Color(Color('red')))
<Color red>

Default equality is RGB hex comparison:

>>> Color('red') == Color('blue')
False
>>> Color('red') == Color('red')
True
>>> Color('red') != Color('blue')
True
>>> Color('red') != Color('red')
False

But this can be changed:

>>> saturation_equality = lambda c1, c2: c1.luminance == c2.luminance
>>> Color('red', equality=saturation_equality) == Color('blue')
True

You should be able to subclass Color object without any issues:

>>> class Tint(Color):
...     pass

And keep the internal API working:

>>> Tint("red").hsl
(0.0, 1.0, 0.5)

static equality(c1: colour.colour.Color, c2: colour.colour.Color) → bool¶: Compare whether two colors are equivalent according to their RGB values.

static from_hex(hex_value: str) → colour.colour.Color¶: Return new Color object based on provided hex vaue.

static from_hsl(hsl_value: Tuple[float, float, float]) → colour.colour.Color¶: Return new Color object based on provided hsl vaue.

static from_rgb(rgb_value: Tuple[float, float, float]) → colour.colour.Color¶: Return new Color object based on provided rgb vaue.

static from_web(web_value: str) → colour.colour.Color¶: Return new Color object based on provided web vaue.

get_blue() → float¶: Get blue component of the color.

get_green() → float¶: Get green component of the color.

get_hex() → str¶: Get shortest possible hex notation of the color.

get_hex_l() → str¶: Get long hex notation of the color.

get_hsl() → Tuple[float, float, float]¶: Get hsl notation of the color.

get_hue() → float¶: Get hue of the color.

get_luminance() → float¶: Get luminance of the color.

get_red() → float¶: Get red component of the color.

get_rgb() → Tuple[float, float, float]¶: Get rgb notation of the color.

get_saturation() → float¶: Get saturation of the color.

get_web() → str¶: Get web representation of the color.

range_to(value: colour.colour.Color, steps: int) → Iterator[colour.colour.Color]¶: Produce a uniform range of colors. starting with self and ending with value.

property rgb: Tuple[float, float, float]¶: Get rgb notation of the color.

set_blue(value: float) → None¶: Set blue coordinate of the color.

set_green(value: float) → None¶: Set green coordinate of the color.

set_hex(value: str) → None¶: Set a color using hex notation.

set_hex_l(value: str) → None¶: Set a color using hex notation.

set_hsl(value: Tuple[float, float, float]) → None¶: Set color using hsl notation.

set_hue(value: float) → None¶: Set hue of the color.

set_luminance(value: float) → None¶: Set luminance of the color.

set_red(value: float) → None¶: Set red coordinate of the color.

set_rgb(value: Tuple[float, float, float]) → None¶: Set color using rgb notation.

set_saturation(value: float) → None¶: Set saturation of the color.

set_web(value: str) → None¶: Set a color using web notation.

property web: str¶: Get web notation of the color.

colour.colour.HSL_equivalence(c1: colour.colour.Color, c2: colour.colour.Color) → bool¶: Compare whether two colors are equivalent according to their HSL values.

colour.colour.RGB_color_picker(obj: object) → colour.colour.Color¶

Build a color representation from the string representation of an object.

This allows to quickly get a color from some data, with the additional benefit that the color will be the same as long as the (string representation of the) data is the same:

>>> from colour import RGB_color_picker, Color

Same inputs produce the same result:

>>> RGB_color_picker("Something") == RGB_color_picker("Something")
True

… but different inputs produce different colors:

>>> RGB_color_picker("Something") != RGB_color_picker("Something else")
True

In any case, we still get a Color object:

>>> isinstance(RGB_color_picker("Something"), Color)
True

colour.colour.RGB_equivalence(c1: colour.colour.Color, c2: colour.colour.Color) → bool¶: Compare whether two colors are equivalent according to their RGB values.

colour.colour.color_scale(begin_hsl: Tuple[float, float, float], end_hsl: Tuple[float, float, float], nb: int) → Sequence[Tuple[float, float, float]]¶

Return a list of nb color HSL tuples between begin_hsl and end_hsl.

>>> from colour import color_scale

>>> [rgb2hex(hsl2rgb(hsl)) for hsl in color_scale((0, 1, 0.5),
...                                               (1, 1, 0.5), 3)]
['#f00', '#0f0', '#00f', '#f00']

>>> [rgb2hex(hsl2rgb(hsl))
...  for hsl in color_scale((0, 0, 0),
...                         (0, 0, 1),
...                         15)]  
['#000', '#111', '#222', ..., '#ccc', '#ddd', '#eee', '#fff']

Of course, asking for negative values is not supported:

>>> color_scale((0, 1, 0.5), (1, 1, 0.5), -2)
Traceback (most recent call last):
...
ValueError: Unsupported negative number of colors (nb=-2).

colour.colour.hash_or_str(obj: object) → Union[int, str]¶

Convert an object into a unique hash.

obj: object to be converted

colour.colour.hex2hsl(x: str) → Tuple[float, float, float]¶: Convert color from hex to hsl.

colour.colour.hex2rgb(str_rgb: str) → Tuple[float, float, float]¶

Transform hex RGB representation to RGB tuple.

Parameters: str_rgb – 3 hex char or 6 hex char string representation
Return type: RGB 3-uple of float between 0 and 1

>>> from colour import hex2rgb

>>> hex2rgb('#00ff00')
(0.0, 1.0, 0.0)

>>> hex2rgb('#0f0')
(0.0, 1.0, 0.0)

>>> hex2rgb('#aaa')  
(0.66..., 0.66..., 0.66...)

>>> hex2rgb('#aa')  
Traceback (most recent call last):
...
ValueError: Invalid value '#aa' provided for rgb color.

colour.colour.hex2web(hex_color: str) → str¶

Convert HEX representation to WEB.

Parameters: rgb – 3 hex char or 6 hex char string representation
Return type: web string representation (human readable if possible)

WEB representation uses X11 rgb.txt to define conversion between RGB and english color names.

>>> from colour import hex2web

>>> hex2web('#ff0000')
'red'

>>> hex2web('#aaaaaa')
'#aaa'

>>> hex2web('#abc')
'#abc'

>>> hex2web('#acacac')
'#acacac'

colour.colour.hsl2hex(x: Tuple[float, float, float]) → str¶: Convert color from hsl to hex.

colour.colour.hsl2rgb(hsl: Tuple[float, float, float]) → Tuple[float, float, float]¶

Convert HSL representation towards RGB.

Parameters

h – Hue, position around the chromatic circle (h=1 equiv h=0)
s – Saturation, color saturation (0=full gray, 1=full color)
l – Ligthness, Overhaul lightness (0=full black, 1=full white)

Return type

3-uple for RGB values in float between 0 and 1

Hue, Saturation, Range from Lightness is a float between 0 and 1

Note that Hue can be set to any value but as it is a rotation around the chromatic circle, any value above 1 or below 0 can be expressed by a value between 0 and 1 (Note that h=0 is equiv to h=1).

This algorithm came from: http://www.easyrgb.com/index.php?X=MATH&H=19#text19

Here are some quick notion of HSL to RGB conversion:

>>> from colour import hsl2rgb

With a lightness put at 0, RGB is always rgbblack

>>> hsl2rgb((0.0, 0.0, 0.0))
(0.0, 0.0, 0.0)
>>> hsl2rgb((0.5, 0.0, 0.0))
(0.0, 0.0, 0.0)
>>> hsl2rgb((0.5, 0.5, 0.0))
(0.0, 0.0, 0.0)

Same for lightness put at 1, RGB is always rgbwhite

>>> hsl2rgb((0.0, 0.0, 1.0))
(1.0, 1.0, 1.0)
>>> hsl2rgb((0.5, 0.0, 1.0))
(1.0, 1.0, 1.0)
>>> hsl2rgb((0.5, 0.5, 1.0))
(1.0, 1.0, 1.0)

With saturation put at 0, the RGB should be equal to Lightness:

>>> hsl2rgb((0.0, 0.0, 0.25))
(0.25, 0.25, 0.25)
>>> hsl2rgb((0.5, 0.0, 0.5))
(0.5, 0.5, 0.5)
>>> hsl2rgb((0.5, 0.0, 0.75))
(0.75, 0.75, 0.75)

With saturation put at 1, and lightness put to 0.5, we can find normal full red, green, blue colors:

>>> hsl2rgb((0 , 1.0, 0.5))
(1.0, 0.0, 0.0)
>>> hsl2rgb((1 , 1.0, 0.5))
(1.0, 0.0, 0.0)
>>> hsl2rgb((1.0/3 , 1.0, 0.5))
(0.0, 1.0, 0.0)
>>> hsl2rgb((2.0/3 , 1.0, 0.5))
(0.0, 0.0, 1.0)

Of course: >>> hsl2rgb((0.0, 2.0, 0.5)) # doctest: +ELLIPSIS Traceback (most recent call last): … ValueError: Saturation must be between 0 and 1.

And: >>> hsl2rgb((0.0, 0.0, 1.5)) # doctest: +ELLIPSIS Traceback (most recent call last): … ValueError: Lightness must be between 0 and 1.

colour.colour.hsl2web(x: Tuple[float, float, float]) → str¶: Convert color from hsl to web.

colour.colour.make_color_factory(**kwargs_defaults: Any) → Callable[[...], colour.colour.Color]¶: Create a factory of Color with given defaults.

colour.colour.rgb2hex(rgb: Tuple[float, float, float], force_long: float = False) → str¶

Transform RGB tuple to hex RGB representation.

Parameters: rgb – RGB 3-uple of float between 0 and 1
Return type: 3 hex char or 6 hex char string representation

>>> from colour import rgb2hex

>>> rgb2hex((0.0,1.0,0.0))
'#0f0'

Rounding try to be as natural as possible:

>>> rgb2hex((0.0,0.999999,1.0))
'#0ff'

And if not possible, the 6 hex char representation is used:

>>> rgb2hex((0.23,1.0,1.0))
'#3bffff'

>>> rgb2hex((0.0,0.999999,1.0), force_long=True)
'#00ffff'

colour.colour.rgb2hsl(rgb: Tuple[float, float, float]) → Tuple[float, float, float]¶

Convert RGB representation towards HSL.

Parameters

r – Red amount (float between 0 and 1)
g – Green amount (float between 0 and 1)
b – Blue amount (float between 0 and 1)

Return type

3-uple for HSL values in float between 0 and 1

This algorithm came from: http://www.easyrgb.com/index.php?X=MATH&H=19#text19

Here are some quick notion of RGB to HSL conversion:

>>> from colour import rgb2hsl

Note that if red amount is equal to green and blue, then you should have a gray value (from black to white).

>>> rgb2hsl((1.0, 1.0, 1.0))  
(..., 0.0, 1.0)
>>> rgb2hsl((0.5, 0.5, 0.5))  
(..., 0.0, 0.5)
>>> rgb2hsl((0.0, 0.0, 0.0))  
(..., 0.0, 0.0)

If only one color is different from the others, it defines the direct Hue:

>>> rgb2hsl((0.5, 0.5, 1.0))  
(0.66..., 1.0, 0.75)
>>> rgb2hsl((0.2, 0.1, 0.1))  
(0.0, 0.33..., 0.15...)

Having only one value set, you can check that:

>>> rgb2hsl((1.0, 0.0, 0.0))
(0.0, 1.0, 0.5)
>>> rgb2hsl((0.0, 1.0, 0.0))  
(0.33..., 1.0, 0.5)
>>> rgb2hsl((0.0, 0.0, 1.0))  
(0.66..., 1.0, 0.5)

Regression check upon very close values in every component of red, green and blue:

>>> rgb2hsl((0.9999999999999999, 1.0, 0.9999999999999994))
(0.0, 0.0, 0.999...)

Of course:

>>> rgb2hsl((0.0, 2.0, 0.5))  
Traceback (most recent call last):
...
ValueError: Green must be between 0 and 1. You provided 2.0.

And: >>> rgb2hsl((0.0, 0.0, 1.5)) # doctest: +ELLIPSIS Traceback (most recent call last): … ValueError: Blue must be between 0 and 1. You provided 1.5.

colour.colour.rgb2web(x: Tuple[float, float, float]) → str¶: Convert color from rgb to web.

colour.colour.web2hex(web: str, force_long: bool = False) → str¶

Convert WEB representation to HEX.

Parameters: rgb – web string representation (human readable if possible)
Return type: 3 hex char or 6 hex char string representation

WEB representation uses X11 rgb.txt to define conversion between RGB and english color names.

>>> from colour import web2hex

>>> web2hex('red')
'#f00'

>>> web2hex('#aaa')
'#aaa'

>>> web2hex('#foo')  
Traceback (most recent call last):
...
AttributeError: '#foo' is not in web format. Need 3 or 6 hex digit.

>>> web2hex('#aaa', force_long=True)
'#aaaaaa'

>>> web2hex('#aaaaaa')
'#aaaaaa'

>>> web2hex('#aaaa')  
Traceback (most recent call last):
...
AttributeError: '#aaaa' is not in web format. Need 3 or 6 hex digit.

>>> web2hex('pinky')  
Traceback (most recent call last):
...
ValueError: 'pinky' is not a recognized color.

And color names are case insensitive:

>>> Color('RED')
<Color red>

colour.colour.web2hsl(x: str) → Tuple[float, float, float]¶: Convert color from web to hsl.

colour.colour.web2rgb(x: str) → Tuple[float, float, float]¶: Convert color from web to rgb.

Welcome to ColourAlpha’s documentation!¶

Formats¶

Usage¶

Indices and tables¶