14. API - picamera.color Module

The color module defines a class for representing a color, along with various ancillary classes which can be used to manipulate aspects of a color.

Note

All classes in this module are available from the picamera namespace without having to import picamera.color directly.

The following classes are defined in the module:

14.1. Color

class picamera.color.Color[source]

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”

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().

classmethod from_hls(h, l, s)[source]

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

classmethod from_hsv(h, s, v)[source]

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

classmethod from_rgb(r, g, b)[source]

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

classmethod from_rgb_bytes(r, g, b)[source]

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

classmethod from_string(s)[source]

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)[source]

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)[source]

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)[source]

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.

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_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. Red

class picamera.color.Red[source]

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)

14.3. Green

class picamera.color.Green[source]

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))

14.4. Blue

class picamera.color.Blue[source]

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">

14.5. Hue

class picamera.color.Hue[source]

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)

14.6. Saturation

class picamera.color.Saturation[source]

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">

14.7. Lightness

class picamera.color.Lightness[source]

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">