Color Objects

python-colormath has support for many of the commonly used color spaces. These are represented by Color objects.

SpectralColor

class colormath.color_objects.SpectralColor(spec_340nm=0.0, spec_350nm=0.0, spec_360nm=0.0, spec_370nm=0.0, spec_380nm=0.0, spec_390nm=0.0, spec_400nm=0.0, spec_410nm=0.0, spec_420nm=0.0, spec_430nm=0.0, spec_440nm=0.0, spec_450nm=0.0, spec_460nm=0.0, spec_470nm=0.0, spec_480nm=0.0, spec_490nm=0.0, spec_500nm=0.0, spec_510nm=0.0, spec_520nm=0.0, spec_530nm=0.0, spec_540nm=0.0, spec_550nm=0.0, spec_560nm=0.0, spec_570nm=0.0, spec_580nm=0.0, spec_590nm=0.0, spec_600nm=0.0, spec_610nm=0.0, spec_620nm=0.0, spec_630nm=0.0, spec_640nm=0.0, spec_650nm=0.0, spec_660nm=0.0, spec_670nm=0.0, spec_680nm=0.0, spec_690nm=0.0, spec_700nm=0.0, spec_710nm=0.0, spec_720nm=0.0, spec_730nm=0.0, spec_740nm=0.0, spec_750nm=0.0, spec_760nm=0.0, spec_770nm=0.0, spec_780nm=0.0, spec_790nm=0.0, spec_800nm=0.0, spec_810nm=0.0, spec_820nm=0.0, spec_830nm=0.0, observer='2', illuminant='d50')

Bases: colormath.color_objects.IlluminantMixin, colormath.color_objects.ColorBase

A SpectralColor represents a spectral power distribution, as read by a spectrophotometer. Our current implementation has wavelength intervals of 10nm, starting at 340nm and ending at 830nm.

Spectral colors are the lowest level, most “raw” measurement of color. You may convert spectral colors to any other color space, but you can’t convert any other color space back to spectral.

See Spectral power distribution on Wikipedia for some higher level details on how these work.

Parameters:

• observer (str) – Observer angle. Either '2' or '10' degrees.
• illuminant (str) – See Observers and Illuminants for valid values.

calc_density(density_standard=None)

Calculates the density of the SpectralColor. By default, Status T density is used, and the correct density distribution (Red, Green, or Blue) is chosen by comparing the Red, Green, and Blue components of the spectral sample (the values being red in via “filters”).

get_illuminant_xyz(observer=None, illuminant=None)

Parameters:

• observer (str) – Get the XYZ values for another observer angle. Must be either ‘2’ or ‘10’.
• illuminant (str) – Get the XYZ values for another illuminant.

Returns:

the color’s illuminant’s XYZ values.

get_numpy_array()

Dump this color into NumPy array.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

set_illuminant(illuminant)

Validates and sets the color’s illuminant.

Note

This only changes the illuminant. It does no conversion of the color’s coordinates. For this, you’ll want to refer to XYZColor.apply_adaptation.

Tip

Call this after setting your observer.

Parameters:illuminant (str) – One of the various illuminants.

set_observer(observer)

Validates and sets the color’s observer angle.

Note

This only changes the observer angle value. It does no conversion of the color’s coordinates.

Parameters:observer (str) – One of ‘2’ or ‘10’.

illuminant = None

The color’s illuminant. Set with set_illuminant().

observer = None

The color’s observer angle. Set with set_observer().

LabColor

class colormath.color_objects.LabColor(lab_l, lab_a, lab_b, observer='2', illuminant='d50')

Bases: colormath.color_objects.IlluminantMixin, colormath.color_objects.ColorBase

Represents a CIE Lab color. For more information on CIE Lab, see Lab color space on Wikipedia.

Parameters:

• lab_l (float) – L coordinate.
• lab_a (float) – a coordinate.
• lab_b (float) – b coordinate.
• observer (str) – Observer angle. Either '2' or '10' degrees.
• illuminant (str) – See Observers and Illuminants for valid values.

get_illuminant_xyz(observer=None, illuminant=None)

Parameters:

• observer (str) – Get the XYZ values for another observer angle. Must be either ‘2’ or ‘10’.
• illuminant (str) – Get the XYZ values for another illuminant.

Returns:

the color’s illuminant’s XYZ values.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

set_illuminant(illuminant)

Validates and sets the color’s illuminant.

Note

This only changes the illuminant. It does no conversion of the color’s coordinates. For this, you’ll want to refer to XYZColor.apply_adaptation.

Tip

Call this after setting your observer.

Parameters:illuminant (str) – One of the various illuminants.

set_observer(observer)

Validates and sets the color’s observer angle.

Note

This only changes the observer angle value. It does no conversion of the color’s coordinates.

Parameters:observer (str) – One of ‘2’ or ‘10’.

illuminant = None

The color’s illuminant. Set with set_illuminant().

lab_a = None

a coordinate

lab_b = None

b coordinate

lab_l = None

L coordinate

observer = None

The color’s observer angle. Set with set_observer().

LCHabColor

class colormath.color_objects.LCHabColor(lch_l, lch_c, lch_h, observer='2', illuminant='d50')

Bases: colormath.color_objects.IlluminantMixin, colormath.color_objects.ColorBase

Represents an CIE LCH color that was converted to LCH by passing through CIE Lab. This differs from LCHuvColor, which was converted to LCH through CIE Luv.

See Introduction to Colour Spaces by Phil Cruse for an illustration of how CIE LCH differs from CIE Lab.

Parameters:

• lch_l (float) – L coordinate.
• lch_c (float) – C coordinate.
• lch_h (float) – H coordinate.
• observer (str) – Observer angle. Either '2' or '10' degrees.
• illuminant (str) – See Observers and Illuminants for valid values.

get_illuminant_xyz(observer=None, illuminant=None)

Parameters:

• observer (str) – Get the XYZ values for another observer angle. Must be either ‘2’ or ‘10’.
• illuminant (str) – Get the XYZ values for another illuminant.

Returns:

the color’s illuminant’s XYZ values.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

set_illuminant(illuminant)

Validates and sets the color’s illuminant.

Note

This only changes the illuminant. It does no conversion of the color’s coordinates. For this, you’ll want to refer to XYZColor.apply_adaptation.

Tip

Call this after setting your observer.

Parameters:illuminant (str) – One of the various illuminants.

set_observer(observer)

Validates and sets the color’s observer angle.

Note

This only changes the observer angle value. It does no conversion of the color’s coordinates.

Parameters:observer (str) – One of ‘2’ or ‘10’.

illuminant = None

The color’s illuminant. Set with set_illuminant().

lch_c = None

C coordinate

lch_h = None

H coordinate

lch_l = None

L coordinate

observer = None

The color’s observer angle. Set with set_observer().

LCHuvColor

class colormath.color_objects.LCHuvColor(lch_l, lch_c, lch_h, observer='2', illuminant='d50')

Bases: colormath.color_objects.IlluminantMixin, colormath.color_objects.ColorBase

Represents an CIE LCH color that was converted to LCH by passing through CIE Luv. This differs from LCHabColor, which was converted to LCH through CIE Lab.

See Introduction to Colour Spaces by Phil Cruse for an illustration of how CIE LCH differs from CIE Lab.

Parameters:

• lch_l (float) – L coordinate.
• lch_c (float) – C coordinate.
• lch_h (float) – H coordinate.
• observer (str) – Observer angle. Either '2' or '10' degrees.
• illuminant (str) – See Observers and Illuminants for valid values.

get_illuminant_xyz(observer=None, illuminant=None)

Parameters:

• observer (str) – Get the XYZ values for another observer angle. Must be either ‘2’ or ‘10’.
• illuminant (str) – Get the XYZ values for another illuminant.

Returns:

the color’s illuminant’s XYZ values.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

set_illuminant(illuminant)

Validates and sets the color’s illuminant.

Note

This only changes the illuminant. It does no conversion of the color’s coordinates. For this, you’ll want to refer to XYZColor.apply_adaptation.

Tip

Call this after setting your observer.

Parameters:illuminant (str) – One of the various illuminants.

set_observer(observer)

Validates and sets the color’s observer angle.

Note

This only changes the observer angle value. It does no conversion of the color’s coordinates.

Parameters:observer (str) – One of ‘2’ or ‘10’.

illuminant = None

The color’s illuminant. Set with set_illuminant().

lch_c = None

C coordinate

lch_h = None

H coordinate

lch_l = None

L coordinate

observer = None

The color’s observer angle. Set with set_observer().

LuvColor

class colormath.color_objects.LuvColor(luv_l, luv_u, luv_v, observer='2', illuminant='d50')

Bases: colormath.color_objects.IlluminantMixin, colormath.color_objects.ColorBase

Represents an Luv color.

Parameters:

• luv_l (float) – L coordinate.
• luv_u (float) – u coordinate.
• luv_v (float) – v coordinate.
• observer (str) – Observer angle. Either '2' or '10' degrees.
• illuminant (str) – See Observers and Illuminants for valid values.

get_illuminant_xyz(observer=None, illuminant=None)

Parameters:

• observer (str) – Get the XYZ values for another observer angle. Must be either ‘2’ or ‘10’.
• illuminant (str) – Get the XYZ values for another illuminant.

Returns:

the color’s illuminant’s XYZ values.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

set_illuminant(illuminant)

Validates and sets the color’s illuminant.

Note

This only changes the illuminant. It does no conversion of the color’s coordinates. For this, you’ll want to refer to XYZColor.apply_adaptation.

Tip

Call this after setting your observer.

Parameters:illuminant (str) – One of the various illuminants.

set_observer(observer)

Validates and sets the color’s observer angle.

Note

This only changes the observer angle value. It does no conversion of the color’s coordinates.

Parameters:observer (str) – One of ‘2’ or ‘10’.

illuminant = None

The color’s illuminant. Set with set_illuminant().

luv_l = None

L coordinate

luv_u = None

u coordinate

luv_v = None

v coordinate

observer = None

The color’s observer angle. Set with set_observer().

XYZColor

class colormath.color_objects.XYZColor(xyz_x, xyz_y, xyz_z, observer='2', illuminant='d50')

Bases: colormath.color_objects.IlluminantMixin, colormath.color_objects.ColorBase

Represents an XYZ color.

Parameters:

• xyz_x (float) – X coordinate.
• xyz_y (float) – Y coordinate.
• xyz_z (float) – Z coordinate.
• observer (str) – Observer angle. Either '2' or '10' degrees.
• illuminant (str) – See Observers and Illuminants for valid values.

apply_adaptation(target_illuminant, adaptation='bradford')

This applies an adaptation matrix to change the XYZ color’s illuminant. You’ll most likely only need this during RGB conversions.

get_illuminant_xyz(observer=None, illuminant=None)

Parameters:

• observer (str) – Get the XYZ values for another observer angle. Must be either ‘2’ or ‘10’.
• illuminant (str) – Get the XYZ values for another illuminant.

Returns:

the color’s illuminant’s XYZ values.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

set_illuminant(illuminant)

Validates and sets the color’s illuminant.

Note

This only changes the illuminant. It does no conversion of the color’s coordinates. For this, you’ll want to refer to XYZColor.apply_adaptation.

Tip

Call this after setting your observer.

Parameters:illuminant (str) – One of the various illuminants.

set_observer(observer)

Validates and sets the color’s observer angle.

Note

This only changes the observer angle value. It does no conversion of the color’s coordinates.

Parameters:observer (str) – One of ‘2’ or ‘10’.

illuminant = None

The color’s illuminant. Set with set_illuminant().

observer = None

The color’s observer angle. Set with set_observer().

xyz_x = None

X coordinate

xyz_y = None

Y coordinate

xyz_z = None

Z coordinate

xyYColor

class colormath.color_objects.xyYColor(xyy_x, xyy_y, xyy_Y, observer='2', illuminant='d50')

Bases: colormath.color_objects.IlluminantMixin, colormath.color_objects.ColorBase

Represents an xYy color.

Parameters:

• xyy_x (float) – x coordinate.
• xyy_y (float) – y coordinate.
• xyy_Y (float) – Y coordinate.
• observer (str) – Observer angle. Either '2' or '10' degrees.
• illuminant (str) – See Observers and Illuminants for valid values.

get_illuminant_xyz(observer=None, illuminant=None)

Parameters:

• observer (str) – Get the XYZ values for another observer angle. Must be either ‘2’ or ‘10’.
• illuminant (str) – Get the XYZ values for another illuminant.

Returns:

the color’s illuminant’s XYZ values.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

set_illuminant(illuminant)

Validates and sets the color’s illuminant.

Note

This only changes the illuminant. It does no conversion of the color’s coordinates. For this, you’ll want to refer to XYZColor.apply_adaptation.

Tip

Call this after setting your observer.

Parameters:illuminant (str) – One of the various illuminants.

set_observer(observer)

Validates and sets the color’s observer angle.

Note

This only changes the observer angle value. It does no conversion of the color’s coordinates.

Parameters:observer (str) – One of ‘2’ or ‘10’.

illuminant = None

The color’s illuminant. Set with set_illuminant().

observer = None

The color’s observer angle. Set with set_observer().

xyy_Y = None

Y coordinate

xyy_x = None

x coordinate

xyy_y = None

y coordinate

sRGBColor

class colormath.color_objects.sRGBColor(rgb_r, rgb_g, rgb_b, is_upscaled=False)

Bases: colormath.color_objects.BaseRGBColor

Represents an sRGB color.

Note

If you pass in upscaled values, we automatically scale them down to 0.0-1.0. If you need the old upscaled values, you can retrieve them with get_upscaled_value_tuple().

Variables:

• rgb_r (float) – R coordinate
• rgb_g (float) – G coordinate
• rgb_b (float) – B coordinate
• is_upscaled (bool) – If True, RGB values are between 1-255. If False, 0.0-1.0.

Parameters:

• rgb_r (float) – R coordinate. 0...1. 1-255 if is_upscaled=True.
• rgb_g (float) – G coordinate. 0...1. 1-255 if is_upscaled=True.
• rgb_b (float) – B coordinate. 0...1. 1-255 if is_upscaled=True.
• is_upscaled (bool) – If False, RGB coordinate values are beteween 0.0 and 1.0. If True, RGB values are between 1 and 255.

get_rgb_hex()

Converts the RGB value to a hex value in the form of: #RRGGBB

Return type:str

get_upscaled_value_tuple()

Scales an RGB color object from decimal 0.0-1.0 to int 0-255.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

classmethod new_from_rgb_hex(hex_str)

Converts an RGB hex string like #RRGGBB and assigns the values to this sRGBColor object.

Return type:sRGBColor

clamped_rgb_b

The clamped (0.0-1.0) B value.

clamped_rgb_g

The clamped (0.0-1.0) G value.

clamped_rgb_r

The clamped (0.0-1.0) R value.

native_illuminant = 'd65'

The RGB space’s native illuminant. Important when converting to XYZ.

rgb_gamma = 2.2

RGB space’s gamma constant.

AdobeRGBColor

class colormath.color_objects.AdobeRGBColor(rgb_r, rgb_g, rgb_b, is_upscaled=False)

Bases: colormath.color_objects.BaseRGBColor

Represents an Adobe RGB color.

Note

If you pass in upscaled values, we automatically scale them down to 0.0-1.0. If you need the old upscaled values, you can retrieve them with get_upscaled_value_tuple().

Variables:

• rgb_r (float) – R coordinate
• rgb_g (float) – G coordinate
• rgb_b (float) – B coordinate
• is_upscaled (bool) – If True, RGB values are between 1-255. If False, 0.0-1.0.

Parameters:

• rgb_r (float) – R coordinate. 0...1. 1-255 if is_upscaled=True.
• rgb_g (float) – G coordinate. 0...1. 1-255 if is_upscaled=True.
• rgb_b (float) – B coordinate. 0...1. 1-255 if is_upscaled=True.
• is_upscaled (bool) – If False, RGB coordinate values are beteween 0.0 and 1.0. If True, RGB values are between 1 and 255.

get_rgb_hex()

Converts the RGB value to a hex value in the form of: #RRGGBB

Return type:str

get_upscaled_value_tuple()

Scales an RGB color object from decimal 0.0-1.0 to int 0-255.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

classmethod new_from_rgb_hex(hex_str)

Converts an RGB hex string like #RRGGBB and assigns the values to this sRGBColor object.

Return type:sRGBColor

clamped_rgb_b

The clamped (0.0-1.0) B value.

clamped_rgb_g

The clamped (0.0-1.0) G value.

clamped_rgb_r

The clamped (0.0-1.0) R value.

native_illuminant = 'd65'

The RGB space’s native illuminant. Important when converting to XYZ.

rgb_gamma = 2.2

RGB space’s gamma constant.

HSLColor

class colormath.color_objects.HSLColor(hsl_h, hsl_s, hsl_l)

Bases: colormath.color_objects.ColorBase

Represents an HSL color.

Parameters:

• hsl_h (float) – H coordinate.
• hsl_s (float) – S coordinate.
• hsl_l (float) – L coordinate.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

hsl_h = None

H coordinate

hsl_l = None

L coordinate

hsl_s = None

S coordinate

HSVColor

class colormath.color_objects.HSVColor(hsv_h, hsv_s, hsv_v)

Bases: colormath.color_objects.ColorBase

Represents an HSV color.

Parameters:

• hsv_h (float) – H coordinate.
• hsv_s (float) – S coordinate.
• hsv_v (float) – V coordinate.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

hsv_h = None

H coordinate

hsv_s = None

S coordinate

hsv_v = None

V coordinate

CMYColor

class colormath.color_objects.CMYColor(cmy_c, cmy_m, cmy_y)

Bases: colormath.color_objects.ColorBase

Represents a CMY color.

Parameters:

• cmy_c (float) – C coordinate.
• cmy_m (float) – M coordinate.
• cmy_y (float) – Y coordinate.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

cmy_c = None

C coordinate

cmy_m = None

M coordinate

cmy_y = None

Y coordinate

CMYKColor

class colormath.color_objects.CMYKColor(cmyk_c, cmyk_m, cmyk_y, cmyk_k)

Bases: colormath.color_objects.ColorBase

Represents a CMYK color.

Parameters:

• cmyk_c (float) – C coordinate.
• cmyk_m (float) – M coordinate.
• cmyk_y (float) – Y coordinate.
• cmyk_k (float) – K coordinate.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

cmyk_c = None

C coordinate

cmyk_k = None

K coordinate

cmyk_m = None

M coordinate

cmyk_y = None

Y coordinate

IPTColor

class colormath.color_objects.IPTColor(ipt_i, ipt_p, ipt_t)

Bases: colormath.color_objects.ColorBase

Represents an IPT color.

Reference: Fairchild, M. D. (2013). Color appearance models, 3rd Ed. (pp. 271-272). John Wiley & Sons.

Parameters:

• ipt_i – I coordinate.
• ipt_p – P coordinate.
• ipt_t – T coordinate.

get_value_tuple()

Returns a tuple of the color’s values (in order). For example, an LabColor object will return (lab_l, lab_a, lab_b), where each member of the tuple is the float value for said variable.

ipt_i = None

I coordinate

ipt_p = None

P coordinate

ipt_t = None

T coordinate