14. API - Colors and Color Matching

The picamera library includes a comprehensive Color class which is capable of converting between numerous color representations and calculating color differences. Various ancillary classes can be used to manipulate aspects of a color.

14.1. Color

class picamera.Color

The Color class is a tuple which represents a color as red, green, and blue components.

The class has a flexible constructor which allows you to create an instance from a variety of color systems including RGB, Y’UV, Y’IQ, HLS, and HSV. There are also explicit constructors for each of these systems to allow you to force the use of a system in your code. For example, an instance of Color can be constructed in any of the following ways:

>>> Color('#f00')
<Color "#ff0000">
>>> Color('green')
<Color "#008000">
>>> Color(0, 0, 1)
<Color "#0000ff">
>>> Color(hue=0, saturation=1, value=0.5)
<Color "#7f0000">
>>> Color(y=0.4, u=-0.05, v=0.615)
<Color "#ff0f4c">

The specific forms that the default constructor will accept are enumerated below:

Style	Description
Single positional parameter	Equivalent to calling Color.from_string().
Three positional parameters	Equivalent to calling Color.from_rgb() if all three parameters are between 0.0 and 1.0, or Color.from_rgb_bytes() otherwise.
Three named parameters: r, g, b
Three named parameters: red, green, blue
Three named parameters: y, u, v	Equivalent to calling Color.from_yuv() if y is between 0.0 and 1.0, u is between -0.436 and 0.436, and v is between -0.615 and 0.615, or Color.from_yuv_bytes() otherwise.
Three named parameters: y, i, q	Equivalent to calling Color.from_yiq().
Three named parameters: h, l, s	Equivalent to calling Color.from_hls().
Three named parameters: hue, lightness, saturation
Three named parameters: h, s, v	Equivalent to calling Color.from_hsv()
Three named parameters: hue, saturation, value
Three named parameters: x, y, z	Equivalent to calling Color.from_cie_xyz()
Three named parameters: l, a, b	Equivalent to calling Color.from_cie_lab()
Three named parameters: l, u, v	Equivalent to calling Color.from_cie_luv()

If the constructor parameters do not conform to any of the variants in the table above, a ValueError will be thrown.

Internally, the color is always represented as 3 float values corresponding to the red, green, and blue components of the color. These values take a value from 0.0 to 1.0 (least to full intensity). The class provides several attributes which can be used to convert one color system into another:

>>> Color('#f00').hls
(0.0, 0.5, 1.0)
>>> Color.from_string('green').hue
Hue(deg=120.0)
>>> Color.from_rgb_bytes(0, 0, 255).yuv
(0.114, 0.435912, -0.099978)

As Color derives from tuple, instances are immutable. While this provides the advantage that they can be used as keys in a dict, it does mean that colors themselves cannot be directly manipulated (e.g. by reducing the red component).

However, several auxilliary classes in the module provide the ability to perform simple transformations of colors via operators which produce a new Color instance. For example:

>>> Color('red') - Red(0.5)
<Color "#7f0000">
>>> Color('green') + Red(0.5)
<Color "#7f8000">
>>> Color.from_hls(0.5, 0.5, 1.0)
<Color "#00feff">
>>> Color.from_hls(0.5, 0.5, 1.0) * Lightness(0.8)
<Color "#00cbcc">
>>> (Color.from_hls(0.5, 0.5, 1.0) * Lightness(0.8)).hls
(0.5, 0.4, 1.0)

From the last example above one can see that even attributes not directly stored by the color (such as lightness) can be manipulated in this fashion. In this case a Color instance is constructed from HLS (hue, lightness, saturation) values with a lightness of 0.5. This is multiplied by a Lightness instance with a value of 0.8 which constructs a new Color with the same hue and saturation, but a lightness of 0.5 * 0.8 = 0.4.

If an instance is converted to a string (with str()) it will return a string containing the 7-character HTML code for the color (e.g. “#ff0000” for red). As can be seen in the examples above, a similar representation is returned for repr().

difference(other, method='euclid')

Determines the difference between this color and other using the specified method. The method is specified as a string, and the following methods are valid:

• ‘euclid’ - This is the default method. Calculate the Euclidian distance. This is by far the fastest method, but also the least accurate in terms of human perception.
• ‘cie1976’ - Use the CIE 1976 formula for calculating the difference between two colors in CIE Lab space.
• ‘cie1994g’ - Use the CIE 1994 formula with the “graphic arts” bias for calculating the difference.
• ‘cie1994t’ - Use the CIE 1994 forumula with the “textiles” bias for calculating the difference.
• ‘cie2000’ - Use the CIEDE 2000 formula for calculating the difference.

Note that the Euclidian distance will be significantly different to the other calculations; effectively this just measures the distance between the two colors by treating them as coordinates in a three dimensional Euclidian space. All other methods are means of calculating a Delta E value in which 2.3 is considered a just-noticeable difference (JND).

Warning

This implementation has yet to receive any significant testing (constructor methods for CIELab need to be added before this can be done).

classmethod from_cie_lab(l, a, b)

Construct a Color from (L*, a*, b*) float values representing a color in the CIE Lab color space. The conversion assumes the sRGB working space with reference white D65.

classmethod from_cie_luv(l, u, v)

Construct a Color from (L*, u*, v*) float values representing a color in the CIE Luv color space. The conversion assumes the sRGB working space with reference white D65.

classmethod from_cie_xyz(x, y, z)

Construct a Color from (X, Y, Z) float values representing a color in the CIE 1931 color space. The conversion assumes the sRGB working space with reference white D65.

classmethod from_hls(h, l, s)

Construct a Color from HLS (hue, lightness, saturation) floats between 0.0 and 1.0.

classmethod from_hsv(h, s, v)

Construct a Color from HSV (hue, saturation, value) floats between 0.0 and 1.0.

classmethod from_rgb(r, g, b)

Construct a Color from three RGB float values between 0.0 and 1.0.

classmethod from_rgb_565(n)

Construct a Color from an unsigned 16-bit integer number in RGB565 format.

classmethod from_rgb_bytes(r, g, b)

Construct a Color from three RGB byte values between 0 and 255.

classmethod from_string(s)

Construct a Color from a 4 or 7 character CSS-like representation (e.g. “#f00” or “#ff0000” for red), or from one of the named colors (e.g. “green” or “wheat”) from the CSS standard. Any other string format will result in a ValueError.

classmethod from_yiq(y, i, q)

Construct a Color from three Y’IQ float values. Y’ can be between 0.0 and 1.0, while I and Q can be between -1.0 and 1.0.

classmethod from_yuv(y, u, v)

Construct a Color from three Y’UV float values. The Y value may be between 0.0 and 1.0. U may be between -0.436 and 0.436, while V may be between -0.615 and 0.615.

classmethod from_yuv_bytes(y, u, v)

Construct a Color from three Y’UV byte values between 0 and 255. The U and V values are biased by 128 to prevent negative values as is typical in video applications. The Y value is biased by 16 for the same purpose.

blue

Returns the blue component of the color as a Blue instance which can be used in operations with other Color instances.

cie_lab

Returns a 3-tuple of (L*, a*, b*) float values representing the color in the CIE Lab color space with the D65 standard illuminant.

cie_luv

Returns a 3-tuple of (L*, u*, v*) float values representing the color in the CIE Luv color space with the D65 standard illuminant.

cie_xyz

Returns a 3-tuple of (X, Y, Z) float values representing the color in the CIE 1931 color space. The conversion assumes the sRGB working space, with reference white D65.

green

Returns the green component of the color as a Green instance which can be used in operations with other Color instances.

hls

Returns a 3-tuple of (hue, lightness, saturation) float values (between 0.0 and 1.0).

hsv

Returns a 3-tuple of (hue, saturation, value) float values (between 0.0 and 1.0).

hue

Returns the hue of the color as a Hue instance which can be used in operations with other Color instances.

lightness

Returns the lightness of the color as a Lightness instance which can be used in operations with other Color instances.

red

Returns the red component of the color as a Red instance which can be used in operations with other Color instances.

rgb

Returns a 3-tuple of (red, green, blue) float values (between 0.0 and 1.0).

rgb_565

Returns an unsigned 16-bit integer number representing the color in the RGB565 encoding.

rgb_bytes

Returns a 3-tuple of (red, green, blue) byte values.

saturation

Returns the saturation of the color as a Saturation instance which can be used in operations with other Color instances.

yiq

Returns a 3-tuple of (y, i, q) float values; y values can be between 0.0 and 1.0, whilst i and q values can be between -1.0 and 1.0.

yuv

Returns a 3-tuple of (y, u, v) float values; y values can be between 0.0 and 1.0, u values are between -0.436 and 0.436, and v values are between -0.615 and 0.615.

yuv_bytes

Returns a 3-tuple of (y, u, v) byte values. Y values are biased by 16 in the result to prevent negatives. U and V values are biased by 128 for the same purpose.

14.2. Manipulation Classes

class picamera.Red

Represents the red component of a Color for use in transformations. Instances of this class can be constructed directly with a float value, or by querying the Color.red attribute. Addition, subtraction, and multiplication are supported with Color instances. For example:

>>> Color.from_rgb(0, 0, 0) + Red(0.5)
<Color "#7f0000">
>>> Color('#f00') - Color('#900').red
<Color "#660000">
>>> (Red(0.1) * Color('red')).red
Red(0.1)

class picamera.Green

Represents the green component of a Color for use in transformations. Instances of this class can be constructed directly with a float value, or by querying the Color.green attribute. Addition, subtraction, and multiplication are supported with Color instances. For example:

>>> Color(0, 0, 0) + Green(0.1)
<Color "#001900">
>>> Color.from_yuv(1, -0.4, -0.6) - Green(1)
<Color "#50002f">
>>> (Green(0.5) * Color('white')).rgb
(Red(1.0), Green(0.5), Blue(1.0))

class picamera.Blue

Represents the blue component of a Color for use in transformations. Instances of this class can be constructed directly with a float value, or by querying the Color.blue attribute. Addition, subtraction, and multiplication are supported with Color instances. For example:

>>> Color(0, 0, 0) + Blue(0.2)
<Color "#000033">
>>> Color.from_hls(0.5, 0.5, 1.0) - Blue(1)
<Color "#00fe00">
>>> Blue(0.9) * Color('white')
<Color "#ffffe5">

class picamera.Hue

Represents the hue of a Color for use in transformations. Instances of this class can be constructed directly with a float value in the range [0.0, 1.0) representing an angle around the HSL hue wheel. As this is a circular mapping, 0.0 and 1.0 effectively mean the same thing, i.e. out of range values will be normalized into the range [0.0, 1.0).

The class can also be constructed with the keyword arguments deg or rad if you wish to specify the hue value in degrees or radians instead, respectively. Instances can also be constructed by querying the Color.hue attribute.

Addition, subtraction, and multiplication are supported with Color instances. For example:

>>> Color(1, 0, 0).hls
(0.0, 0.5, 1.0)
>>> (Color(1, 0, 0) + Hue(deg=180)).hls
(0.5, 0.5, 1.0)

Note that whilst multiplication by a Hue doesn’t make much sense, it is still supported. However, the circular nature of a hue value can lead to suprising effects. In particular, since 1.0 is equivalent to 0.0 the following may be observed:

>>> (Hue(1.0) * Color.from_hls(0.5, 0.5, 1.0)).hls
(0.0, 0.5, 1.0)

class picamera.Saturation

Represents the saturation of a Color for use in transformations. Instances of this class can be constructed directly with a float value, or by querying the Color.saturation attribute. Addition, subtraction, and multiplication are supported with Color instances. For example:

>>> Color(0.9, 0.9, 0.6) + Saturation(0.1)
<Color "#ebeb92">
>>> Color('red') - Saturation(1)
<Color "#7f7f7f">
>>> Saturation(0.5) * Color('wheat')
<Color "#e4d9c3">

class picamera.Lightness

Represents the lightness of a Color for use in transformations. Instances of this class can be constructed directly with a float value, or by querying the Color.lightness attribute. Addition, subtraction, and multiplication are supported with Color instances. For example:

>>> Color(0, 0, 0) + Lightness(0.1)
<Color "#191919">
>>> Color.from_rgb_bytes(0x80, 0x80, 0) - Lightness(0.2)
<Color "#191900">
>>> Lightness(0.9) * Color('wheat')
<Color "#f0cd8d">