4. API

The colorzero 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.

4.1. Color

This the primary class in the package, and often the only class you’ll need or want to interact with. It has an extremely flexible constructor, along with numerous explicit constructors, and attributes for conversion to other color systems.

class colorzero.Color

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

The class has a flexible constructor which allows you to create an instance from any registered color system (see color_conversion()). There are also explicit constructors for every registered system that can convert (directly or indirectly) to linear RGB. For example, an instance of Color can be constructed in any of the following ways:

>>> Color('#f00')
<Color html='#ff0000' rgb=(1, 0, 0)>
>>> Color('green')
<Color html='#008000' rgb=(0.0, 0.501961, 0.0)>
>>> Color(0, 0, 1)
<Color html='#0000ff' rgb=(0, 0, 1)>
>>> Color(h=0, s=1, v=0.5)
<Color html='#800000' rgb=(0.5, 0, 0)>
>>> Color(y=0.4, u=-0.05, v=0.615)
<Color html='#ff104c' rgb=(1, 0.0626644, 0.298394)>

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

Style	Description
Single scalar parameter	Equivalent to calling Color.from_string(), or Color.from_rgb24().
Three positional parameters or a 3-tuple with no field names	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, or a 3-tuple with fields “r”, “g”, “b”
Three named parameters, or a 3-tuple with fields “red”, “green”, “blue”
Three named parameters, or a 3-tuple with fields “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, or a 3-tuple with fields “y”, “i”, “q”	Equivalent to calling Color.from_yiq().
Three named parameters, or a 3-tuple with fields “h”, “l”, “s”	Equivalent to calling Color.from_hls().
Three named parameters, or a 3-tuple with fields “hue”, “lightness”, “saturation”
Three named parameters, or a 3-tuple with fields “h”, “s”, “v”	Equivalent to calling Color.from_hsv()
Three named parameters, or a 3-tuple with fields “hue”, “saturation”, “value”
Three named parameters, or a 3-tuple with fields “x”, “y”, “z”	Equivalent to calling Color.from_cie_xyz()
Three named parameters, or a 3-tuple with fields “l”, “a”, “b”	Equivalent to calling Color.from_cie_lab()
Three named parameters, or a 3-tuple with fields “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 raised.

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
HLS(h=0.0, l=0.5, s=1.0)
>>> Color.from_string('green').hue
Hue(deg=120.0)
>>> Color.from_rgb_bytes(0, 0, 255).yuv
YUV(y=0.114, u=0.436, v=-0.10001426533523537)

As Color derives from tuple, instances are immutable. While this provides the advantage that they can be used in a set or as keys of a dict, it does mean that colors themselves cannot be directly manipulated (e.g. by setting 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, you can add, subtract, and multiply colors directly:

>>> Color('red') + Color('blue')
<Color html='#ff00ff' rgb=(1, 0, 1)>
>>> Color('magenta') - Color('red')
<Color html='#0000ff' rgb=(0, 0, 1)>

Values are clipped to ensure the resulting color is still valid:

>>> Color('#ff00ff') + Color('#ff0000')
<Color html='#ff00ff' rgb=(1, 0, 1)>

You can wrap numbers in constructors like Red (or obtain elements of existing colors), then add, subtract, or multiply them with a Color:

>>> Color('red') - Red(0.5)
<Color html='#800000' rgb=(0.5, 0, 0)>
>>> Color('green') + Color('grey').red
<Color html='#808000' rgb=(0.501961, 0.501961, 0)>

You can even manipulate non-primary attributes like hue, saturation, and lightness with standard addition, subtraction or multiplication operators:

>>> Color.from_hls(0.5, 0.5, 1.0)
<Color html='#00ffff' rgb=(0, 1, 1)>
>>> Color.from_hls(0.5, 0.5, 1.0) * Lightness(0.8)
<Color html='#00cccc' rgb=(0, 0.8, 0.8)>
>>> (Color.from_hls(0.5, 0.5, 1.0) * Lightness(0.8)).hls
HLS(h=0.5, l=0.4, s=1.0)

In the last example above, a Color instance is constructed from HLS (hue, lightness, saturation) values with a lightness of 0.5. This is multiplied by a Lightness a value of 0.8 which constructs a new Color with the same hue and saturation, but a lightness of 0.4 (0.8 * 0.5).

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 included for the output of 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).

classmethod from_cmy(c, m, y)

Construct a Color from CMY (cyan, magenta, yellow) floats between 0.0 and 1.0.

Note

This conversion uses the basic subtractive method which is not accurate for color reproduction on print devices. See the Color FAQ for more information.

classmethod from_cmyk(c, m, y, k)

Construct a Color from CMYK (cyan, magenta, yellow, black) floats between 0.0 and 1.0.

Note

This conversion uses the basic subtractive method which is not accurate for color reproduction on print devices. See the Color FAQ for more information.

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_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_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_rgb(r, g, b)

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

classmethod from_rgb24(n)

Construct a Color from an unsigned 24-bit integer number of the form 0x00BBGGRR.

classmethod from_rgb565(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_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_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.

cmy

Returns a 3-tuple of (cyan, magenta, yellow) float values (between 0.0 and 1.0).

Note

This conversion uses the basic subtractive method which is not accurate for color reproduction on print devices. See the Color FAQ for more information.

cmyk

Returns a 4-tuple of (cyan, magenta, yellow, black) float values (between 0.0 and 1.0).

Note

This conversion uses the basic subtractive method which is not accurate for color reproduction on print devices. See the Color FAQ for more information.

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

html

Returns the color as a string in HTML #RRGGBB format.

hue

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

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.

lightness

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

luma

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

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.

rgb

Return a simple 3-tuple of (r, g, b) float values in the range 0.0 <= n <= 1.0.

Note

The Color class can already be treated as such a 3-tuple but for the cases where you want a straight namedtuple() this property is available.

rgb565

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.

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.

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.

4.2. Manipulation Classes

These manipulation classes are used in conjunction with the standard arithmetic addition, subtraction, and multiplication operators to calculate new Color instances.

class colorzero.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 html='#800000' rgb=(0.5, 0, 0)>
>>> Color('#f00') - Color('#900').red
<Color html='#660000' rgb=(0.4, 0, 0)>
>>> (Red(0.1) * Color('red')).red
Red(0.1)

class colorzero.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 html='#001a00' rgb=(0, 0.1, 0)>
>>> Color.from_yuv(1, -0.4, -0.6) - Green(1)
<Color html='#510030' rgb=(0.316098, 0, 0.187156)>
>>> (Green(0.5) * Color('white')).rgb
RGB(r=1.0, g=0.5, b=1.0)

class colorzero.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 html='#000033' rgb=(0, 0, 0.2)>
>>> Color.from_hls(0.5, 0.5, 1.0) - Blue(1)
<Color html='#00ff00' rgb=(0, 1, 0)>
>>> Blue(0.9) * Color('white')
<Color html='#ffffe6' rgb=(1, 1, 0.9)>

class colorzero.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
HLS(h=0.0, l=0.5, s=1.0)
>>> (Color(1, 0, 0) + Hue(deg=180)).hls
HLS(h=0.5, l=0.5, s=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
HLS(h=0.0, l=0.5, s=1.0)

deg

Returns the hue as a value in degrees with the range 0.0 <= n < 360.0.

rad

Returns the hue as a value in radians with the range 0.0 <= n < 2π.

class colorzero.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 html='#ecec93' rgb=(0.925, 0.925, 0.575)>
>>> Color('red') - Saturation(1)
<Color html='#808080' rgb=(0.5, 0.5, 0.5)>
>>> Saturation(0.5) * Color('wheat')
<Color html='#e4d9c3' rgb=(0.896078, 0.85098, 0.766667)>

class colorzero.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 html='#1a1a1a' rgb=(0.1, 0.1, 0.1)>
>>> Color.from_rgb_bytes(0x80, 0x80, 0) - Lightness(0.2)
<Color html='#1a1a00' rgb=(0.101961, 0.101961, 0)>
>>> Lightness(0.9) * Color('wheat')
<Color html='#f0ce8e' rgb=(0.94145, 0.806785, 0.555021)>

class colorzero.Luma

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

>>> Color(0, 0, 0) + Luma(0.1)
<Color html='#1a1a1a' rgb=(0.1, 0.1, 0.1)>
>>> Color('red') * Luma(0.5)
<Color html='#d90000' rgb=(0.8505, 0, 0)>