Color Classes

Common color spaces and systems.

This module contains different classes that represent a few of the most common color spaces [1]. Colors can be compared, converted to and passed as arguments to different classes.

Examples

Create some colors and compare them:

>>> RGB(1, 0, 0) == HSL(0, 1 , 0.5)
True

Convert an RGB color to CMYK:

>>> rgb_red = RGB(1, 0, 0)
>>> rgb_red.cmyk()
CMYK(0.0, 1.0, 1.0, 0.0)

Color arithmetic makes it easy to change the properties of a color. The operations are performed element-wise in the format of the color used as the right operand, allowing specific color components to be changed in the color on the left of the operator. If the right operand is not a color, but rather a tuple, than the left color is not converted prior to the operation being performed.

Add some CIE lightness to the color black (right operand is CIELab, meaning that the Hex color will be converted to CIELab before adding 50 to its lighness value and then converted back to Hex):

>>> Hex("#000000") + CIELab(50, 0, 0)
Hex('#777777')

Make a red 50% less saturated by multiplying its saturation component by 0.5 (here no conversion is performed because the right operand is a tuple rather than a color class):

>>> HSV(0.0, 1.0, 1.0) * (1, 0.5, 1)
HSV(0.0, 0.5, 1.0)

References

[1]

Wikipedia at https://en.wikipedia.org/wiki/Color_model.

colorir.color_class.ColorLike

Type constant that describes common representations of colors in python.

alias of Union[ColorBase, str, tuple]

class colorir.color_class.RGB(r, g, b, a=None, max_rgb=1, max_a=1, include_a=False, round_to=-1, linear=False)

Bases: ColorTupleBase

Represents a color in the RGB color space [2].

References

[2]

Wikipedia at https://en.wikipedia.org/wiki/SRGB.

Parameters:

• r (float) – Red component of the color.

• g (float) – Green component of the color.

• b (float) – Blue component of the color.

• a (float) – Opacity component of the color. Defaults to None, which means it will be the same as the max_rgba parameter.

• max_rgb – What is the maximum value for the r, g and b components. Some common values for this parameter would be 255 or 1.

• max_a – What is the maximum value for the a component. Some common values for this parameter would be 100 or 1.

• include_a – Whether to include the opacity parameter a in the constructed tuple. Setting it to True may result in an object such as RGB(255, 255, 0, 255) instead of RGB(255, 255, 0), for example.

• round_to – Rounds the value of each color component to this many decimal places. Setting this parameter to 0 ensures that the components will be of type int. -1 means that the components won’t be rounded at all.

• linear – Whether the values are linear RGB or sRGB. It is strongly advised not to keep values as linear RGB, but it can be useful for quick conversions.

colorir.color_class.sRGB

alias of RGB

class colorir.color_class.HSV(h, s, v, a=None, max_h=360, max_sva=1, include_a=False, round_to=-1)

Bases: ColorPolarBase

Represents a color in the HSV color space [3].

References

[3]

Wikipedia at https://en.wikipedia.org/wiki/HSL_and_HSV.

Parameters:

• h (float) – Hue component of the color.

• s (float) – Saturation component of the color.

• v (float) – Value component of the color.

• a (float) – Opacity component of the color. Defaults to None, which means it will be the same as the max_sva parameter.

• max_h (float) – What is the maximum value for the h component. Some common values for this parameter would be 360 or 1.

• max_sva – What is the maximum value for the s, v and a components. Some common values for this parameter would be 1 or 100.

• include_a – Whether to include the opacity parameter a in the constructed tuple. Setting it to True may result in an object such as HSV(360, 1, 0, 1) instead of HSV(360, 1, 0), for exemple.

• round_to – Rounds the value of each color component to this many decimal places. Setting this parameter to 0 ensures that the components will be of type int. -1 means that the components won’t be rounded at all.

h: float

max_h: float

class colorir.color_class.HSL(h, s, l, a=None, max_h=360, max_sla=1, include_a=False, round_to=-1)

Bases: ColorPolarBase

Represents a color in the HSL color space [4].

[4]

Wikipedia at https://en.wikipedia.org/wiki/HSL_and_HSV.

Parameters:

• h (float) – Hue component of the color.

• s (float) – Saturation component of the color.

• l (float) – Lightness component of the color.

• a (float) – Opacity component of the color. Defaults to None, which means it will be the same as the max_sla parameter.

• max_h (float) – What is the maximum value for the h component. Some common values for this parameter would be 360 or 1.

• max_sla – What is the maximum value for the s, l and a components. Some common values for this parameter would be 1 or 100.

• include_a – Whether to include the opacity parameter a in the constructed tuple. Setting it to True may result in an object such as HSL(360, 1, 0, 1) instead of HSL(360, 1, 0), for exemple.

• round_to – Rounds the value of each color component to this many decimal places. Setting this parameter to 0 ensures that the components will be of type int. -1 means that the components won’t be rounded at all.

h: float

max_h: float

class colorir.color_class.CMY(c, m, y, a=None, max_cmya=1, include_a=False, round_to=-1)

Bases: ColorTupleBase

Represents a color in the CMY color space [5].

References

[5]

Wikipedia at https://en.wikipedia.org/wiki/CMY_color_model.

Parameters:

• c (float) – Cyan component of the color.

• m (float) – Magenta component of the color.

• y (float) – Yellow component of the color.

• a (float) – Opacity component of the color. Defaults to None, which means it will be the same as the max parameter.

• max_cmya – What is the maximum value for the c, m, y and a components. Some common values for this parameter would be 1 or 100.

• include_a – Whether to include the opacity parameter a in the constructed tuple. Setting it to True may result in an object such as CMY(1, 1, 0, 1) instead of CMY(1, 1, 0), for exemple.

• round_to – Rounds the value of each color component to this many decimal places. Setting this parameter to 0 ensures that the components will be of type int. The default, -1, means that the components won’t be rounded at all.

class colorir.color_class.CMYK(c, m, y, k, a=None, max_cmyka=1, include_a=False, round_to=-1)

Bases: ColorTupleBase

Represents a color in the CMYK color space [6].

References

[6]

Wikipedia at https://en.wikipedia.org/wiki/CMYK_color_model.

Parameters:

• c (float) – Cyan component of the color.

• m (float) – Magenta component of the color.

• y (float) – Yellow component of the color.

• k (float) – Key (black) component of the color.

• a (float) – Opacity component of the color. Defaults to None, which means it will be the same as the max parameter.

• max_cmyka – What is the maximum value for the c, m, y, k and a components. Some common values for this parameter would be 1 or 100.

• include_a – Whether to include the opacity parameter a in the constructed tuple. Setting it to True may result in an object such as CMYK(1, 1, 0, 1) instead of CMYK(1, 1, 0), for exemple.

• round_to – Rounds the value of each color component to this many decimal places. Setting this parameter to 0 ensures that the components will be of type int. The default, -1, means that the components won’t be rounded at all.

class colorir.color_class.CIELuv(l, u, v, a=None, max_a=1, include_a=False, round_to=-1)

Bases: ColorTupleBase

class colorir.color_class.CIELab(l, a_, b, a=None, max_a=1, include_a=False, round_to=-1)

Bases: ColorTupleBase

class colorir.color_class.HCLuv(h, c, l, a=None, max_h=360, max_a=1, include_a=False, round_to=-1)

Bases: ColorPolarBase

h: float

max_h: float

class colorir.color_class.HCLab(h, c, l, a=None, max_h=360, max_a=1, include_a=False, round_to=-1)

Bases: ColorPolarBase

h: float

max_h: float

class colorir.color_class.Hex(hex_str, uppercase=False, include_hash=True, include_a=False, tail_a=<object object>)

Bases: ColorBase, str

Represents a color in the RGB color space [7] as a hexadecimal string.

Is mostly used for representing colors in web applications [8].

References

[7]

Wikipedia at https://en.wikipedia.org/wiki/SRGB.

[8]

Wikipedia at https://en.wikipedia.org/wiki/Web_colors

Parameters:

• hex_str (str) – Hexadecimal string from which the Hex instance will be built. The format can be a string of 6 digits, 8 digits (with an alpha specifier in the beginning or the end), or 3 digits, optionally including a ‘#’ character.

• uppercase – Whether the color will be represented in uppercase or lowercase.

• include_a – Whether to include the opacity parameter a in the constructed string. Setting it to True may result in an object such as Hex('#ffffff00') instead of Hex('#ffff00'), for exemple.

• tail_a – Whether the alpha component is present in the tail or head of the hex string. Used only if hex_str includes an alpha component or include_a is True.

Examples

>>> Hex("#ff0000")
Hex('#ff0000')

>>> Hex("#FF0000", include_hash=False)
Hex('ff0000')

>>> Hex("ff0000", include_a=True, tail_a=True)
Hex('#ff0000ff')

class colorir.color_class.ColorBase

Bases: object

Base class from which all color classes inherit.

Notes

This class is abstract and should not be instantiated.

property format: ColorFormat

Returns a ColorFormat representing the format of this color object.

~self

Gets the inverse RGB of this color.

self % other

Blends two colors at 50% using colorir.utils.blend().

self + other

Adds two colors or a color (as the left operand) and a tuple (as the right operand) together.

self - other

Subtracts one color from another or a tuple (the right operand) from a color (the left operand).

self * other

Multiplies two colors or a color (as the left operand) and a tuple (as the right operand) together.

self / other

Divides two colors or a color (as the left operand) and a tuple (as the right operand) together.

grayscale()

Converts this color to a grayscale representation in the same format using CIE lightness component.

hex(**kwargs)

Converts the current color to a hexadecimal representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the Hex constructor.

rgb(**kwargs)

Converts the current color to an sRGB representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the sRGB constructor.

hsl(**kwargs)

Converts the current color to an HSL representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the HSL constructor.

hsv(**kwargs)

Converts the current color to an HSV representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the HSV constructor.

cmyk(**kwargs)

Converts the current color to a CMYK representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the CMYK constructor.

cmy(**kwargs)

Converts the current color to a CMY representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the CMY constructor.

cieluv(**kwargs)

Converts the current color to a CIELuv representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the CIELuv constructor.

cielab(**kwargs)

Converts the current color to a CIELab representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the CIELab constructor.

hcluv(**kwargs)

Converts the current color to a HCLuv representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the HCLuv constructor.

hclab(**kwargs)

Converts the current color to a HCLab representation.

Parameters:

**kwargs – Keyword arguments wrapped in this function will be passed on to the HCLab constructor.