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')[source]¶ 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)[source]¶ 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: 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()
.
- observer (str) – Observer angle. Either
LabColor¶
-
class
colormath.color_objects.
LabColor
(lab_l, lab_a, lab_b, observer='2', illuminant='d50')[source]¶ 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: -
get_illuminant_xyz
(observer=None, illuminant=None)¶ Parameters: 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')[source]¶ 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: -
get_illuminant_xyz
(observer=None, illuminant=None)¶ Parameters: 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')[source]¶ 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: -
get_illuminant_xyz
(observer=None, illuminant=None)¶ Parameters: 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')[source]¶ Bases:
colormath.color_objects.IlluminantMixin
,colormath.color_objects.ColorBase
Represents an Luv color.
Parameters: -
get_illuminant_xyz
(observer=None, illuminant=None)¶ Parameters: 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')[source]¶ Bases:
colormath.color_objects.IlluminantMixin
,colormath.color_objects.ColorBase
Represents an XYZ color.
Parameters: -
apply_adaptation
(target_illuminant, adaptation='bradford')[source]¶ 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: 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')[source]¶ Bases:
colormath.color_objects.IlluminantMixin
,colormath.color_objects.ColorBase
Represents an xyY color.
Parameters: -
get_illuminant_xyz
(observer=None, illuminant=None)¶ Parameters: 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)[source]¶ 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: 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_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.
BT2020Color¶
-
class
colormath.color_objects.
BT2020Color
(rgb_r, rgb_g, rgb_b, is_upscaled=False)[source]¶ Bases:
colormath.color_objects.BaseRGBColor
Represents a ITU-R BT.2020 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: 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_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.4¶ RGB space’s gamma constant.
AdobeRGBColor¶
-
class
colormath.color_objects.
AdobeRGBColor
(rgb_r, rgb_g, rgb_b, is_upscaled=False)[source]¶ 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: 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_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)[source]¶ Bases:
colormath.color_objects.ColorBase
Represents an HSL color.
Parameters: -
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)[source]¶ Bases:
colormath.color_objects.ColorBase
Represents an HSV color.
Parameters: -
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)[source]¶ Bases:
colormath.color_objects.ColorBase
Represents a CMY color.
Parameters: -
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)[source]¶ Bases:
colormath.color_objects.ColorBase
Represents a CMYK color.
Parameters: -
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)[source]¶ 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