# The color objects¶

The colorlib module is handling the transformation between different color spaces. A set of different color spaces is available including colorlib.CIELUV, colorlib.CIELAB, colorlib.CIEXYZ, colorlib.polarLUV/colorlib.HCL, colorlib.polarLAB, colorlib.HSV, colorlib.HLS, colorlib.RGB, colorlib.sRGB, and colorlib.hexcols for HEX colors.

class colorlib.colorobject[source]

This is the base class of all color objects and provides some default methods.

colors(fixup = True)[source]

Returns hex colors of the current colorobject. Converts the colors into a hexcols object to retrieve hex colors which are returned as list.

If the object contains alpha values the alpha level is added to the hex string if and only if alpha is not equal to 1.0.

Parameters: fixup (bool) – whether or not to correct rgb values outside the defined range of [0., 1.] rev (bool) – return colors in reversed order? Returns a list of hex colors. list

Examples

>>> from colorspace.colorlib import HCL
>>> cols = HCL([0, 40, 80], [30, 60, 80], [85, 60, 35])
>>> cols.colors()

dropalpha()[source]

Remove alpha information from the color object, if defined.

get(dimname = None)[source]

Returns the current color coordinates. Either a single coordinate (if dimname is set) or all coordinates of the current colorobject. The latter will return a dictionary containing the data with all defined dimensions.

Parameters: dimname (None, st) – can be set to only retrieve one very specific coordinate. Either a dictionary or a single numpy.ndarray if input dimname was not specified. If a specific dimension is requested bu the dimension does not exist a ValueError is raised. dict or numpy.ndarray

Examples

>>> from colorspace.colorlib import HCL
>>> cols = HCL([260, 80, 30], [80, 0, 80], [30, 90, 30])
>>> cols.get()
>>> cols.get("H")

get_whitepoint()[source]

A white point definition is used to adjust the colors. If not explicitly set via set_whitepoint() default values are used. This method returns the definition of the white point in use.

Returns: Returns a dict with X, Y, Z, the white point specification for the three dimensions. dict

Examples

>>> from colorspace.colorlib import hexcols
>>> c = hexcols("#ff0000")
>>> c.get_whitepoint()

hasalpha()[source]

Small helper function to check whether the current color object has alpha values or not.

Returns: Returns True if alpha values are present, False if not. bool
set(kwargs)[source]

Allows to manipulate the current colors. The named input arguments have to fulfil a specific set or requirements. If not, the function raises a ValueError.

The dimension has to exist, and the new data have to be of the same type and of the same length to be accepted.

No return, modifies the current object.

Parameters: kwargs – named arguments. The key is the name of the dimension to be changed, the value an object which fulfills the requirements (see description of this method)

Examples

>>> from colorspace.colorlib import HCL
>>> cols = HCL([260, 80, 30], [80, 0, 80], [30, 90, 30])
>>> print cols
>>> cols.set(H = [150, 150, 30])
>>> print cols

set_whitepoint(**kwargs)[source]

A white point definition is used to adjust the colors. This method allows to set custom values. If not explicitly set a default specification is used.

No return, stores the new definition on the object. get_whitepoint() can be used to get the current specification.

Parameters: X (float) – white specification for dimension X Y (float) – white specification for dimension Y Z (float) – white specification for dimension Z

Examples

>>> from colorspace.colorlib import hexcols
>>> c = hexcols("#ff0000")
>>> c.set_whitepoint(X = 100., Y = 100., Z = 101.)
>>> c.get_whitepoint()

specplot(**kwargs)[source]

Plotting a specplot (see specplot.specplot()) of the current color object. Additional arguments can be used to control the specplot.

Parameters: kwargs – named list of additional arguments forwarded to the specplot function

Examples

>>> from colorspace.colorlib import HCL
>>> cols = HCL([260, 80, 30], [80, 0, 80], [30, 90, 30])
>>> cols.specplot()
>>> cols.specplot(rgb = False)

swatchplot(n = 7)[source]

Interfacing the swatchplot.swatchplot() function. Plotting the spectrum of the current color palette.

Examples

>>> from colorspace.colorlib import HCL
>>> cols = HCL(H = [160, 210, 260, 310, 360],
>>>    C = [ 70,  40,  10,  40,  70],
>>>    L = [ 50,  70,  90,  70,  50])
>>> cols.swatchplot()

class colorlib.hexcols(hex_)[source]

Color object for hex colors.

Takes up a set of hex colors. Can be converted to all other color spaces including RGB, sRGB, HLS, and “hex” (hexcols), CIEXYZ, CIELUV, CIELAB, polarLUV, polarLAB,

Parameters: hex (str, list of str, or numpy.ndarray of type str) – hex colors. Only six and eight digit hex colors are allowed (e.g., #000000 or #00000050 if with alpha value). If invalid hex colors are provided the object will raise a ValueError. Input can be a single string, a list of strings, or a numpy.ndarray containing a set of hex colors. Invalid hex colors will be handled as numpy.nan, alpha values can be provided but will be ignored

Examples

>>> from colorspace.colorlib import hexcols
>>> c = hexcols("#cecece")
>>> c = hexcols(["#ff0000", "#00ff00"])
>>> from numpy import asarray
>>> c = hexcols(asarray(["#ff000030", "#00ff0030"], dtype = "|S9"))
>>> #Convert hex colors to another color space (CIEXYZ for example):
>>> c.to("CIEXYZ")


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary
class colorlib.sRGB(R, G, B, alpha = None, gamma = None)[source]

sRGB (device dependent RGB) color object.

Allowes conversions to: CIEXYZ, CIELUV, CIELAB, RGB, HSV, HLS, polarLUV, polarLAB, “hex” (hexcols). Allows additional alpha input. Note that the alpha channel will not be modified but preserved. R, G, and B have to be within [0., 1.].

Parameters: R (float, list of floats, numpy.ndarray) – intensity of red [0.,1.] G (float, list of floats, numpy.ndarray) – intensity of green [0.,1] B (float, list of floats, numpy.ndarray) – intensity of blue [0.,1] alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added gamma (None, float) – gamma parameter. Used to convert from device dependent sRGB to RGB. If not set the default of 2.4 is used

Examples

>>> from colorspace.colorlib import sRGB
>>> c = sRGB(1., 0.3, 0.5)
>>> c = sRGB([1.,0.8], [0.5,0.5], [0.0,0.2])
>>>
>>> from numpy import asarray
>>> c = sRGB(asarray([1.,0.8]), asarray([0.5,0.5]), asarray([0.0,0.2]))


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary.
class colorlib.RGB(R, G, B, alpha = None)[source]

Device independent RGB color object.

Allowes conversions to: CIEXYZ, CIELUV, CIELAB, sRGB, HSV, HLS, polarLUV, polarLAB, “hex” (hexcols). Allows additional alpha input. Note that the alpha channel will not be modified but preserved.

Parameters: R (numeric) – intensity of red [0.,1.] G (numeric) – intensity of green [0.,1.] B (numeric) – intensity of blue [0.,1.] alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added

Examples

>>> from colorspace.colorlib import sRGB
>>> c = sRGB(1., 0.3, 0.5)
>>> c = sRGB([1.,0.8], [0.5,0.5], [0.0,0.2])
>>>
>>> from numpy import asarray
>>> c = sRGB(asarray([1.,0.8]), asarray([0.5,0.5]), asarray([0.0,0.2]))


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary.
class colorlib.polarLUV(H, C, L, alpha = None)[source]

polarLUV or HCL color object. The polar representation of the CIELUV (colorspace.CIELUV) color space is also known as Hue-Chroma-Luminance (HCL) color space. polarLUV colors can be converted into: CIEXYZ , CIELUV , CIELAB , RGB , sRGB , polarLAB , hex. Not allowed (ambiguous) to convert into: HSV, HLS.

Parameters: L (numeric) – single value or vector for hue dimension [-360.,360.] U (numeric) – single value or vector for chroma dimension [0., 100.+] V (numeric) – single value or vector for luminance dimension [0., 100.] alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added

Examples

>>> from colorspace.colorlib import polarLUV, HCL
>>> c = polarLUV(100., 30, 50.)
>>> c = HCL(100., 30, 50.) # Equivalent to the command above
>>> c = HCL([100.], [30.], [50.])
>>> c = HCL([100, 80], [30,50], [30,80])
>>> from numpy import asarray
>>> c = HCL(asarray([100,80]), asarray([30,50]), asarray([30,80]))


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary
colorlib.HCL

alias of colorlib.polarLUV

class colorlib.CIELUV(L, U, V, alpha = None)[source]

CIELUV color object.

polarLUV colors can be converted into: CIEXYZ, CIELUV, CIELAB, RGB, sRGB, polarLAB, hex. Not allowed (ambiguous) to convert into: HSV, HLS.

Parameters: L (numeric) – single value or multiple values for L-dimension U (numeric) – single value or multiple values for U-dimension V (numeric) – single value or multiple values for V-dimension alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added

Examples

>>> from colorspace.colorlib import CIELUV
>>> c = CIELUV(0, 10, 10)
>>> c = CIELUV([10, 30], [20, 80], [100, 40])
>>> from numpy import asarray
>>> c = CIELUV(asarray([10, 30]), asarray([20, 80]), asarray([100, 40]))


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary
class colorlib.CIEXYZ(X, Y, Z, alpha = None)[source]

CIEXYZ color object.

Allowes conversions to: CIEXYZ, CIELUV, CIELAB, RGB, polarLUV, polarLAB, hexcols. Not possible are conversions to (ambiguous): HSV, HLS.

Parameters: X (numeric) – single value or multiple values for X-dimension Y (numeric) – single value or multiple values for Y-dimension Z (numeric) – single value or multiple values for Z-dimension alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added

Examples

>>> from colorspace.colorlib import CIEXYZ
>>> c = CIEXYZ(80, 30, 10)
>>> c = CIEXYZ([10, 0], [20, 80], [40, 40])
>>> from numpy import asarray
>>> c = CIEXYZ(asarray([10, 0]), asarray([20, 80]), asarray([40, 40]))


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary
class colorlib.CIELAB(L, A, B, alpha = None)[source]

CIELAB color object.

Allowes conversions to: CIEXYZ, CIELUV, CIELAB, RGB, polarLUV, polarLAB, “hex” (hexcols). Not possible are conversions to (ambiguous): HSV, HLS.

Parameters: L (numeric) – single value or multiple values for L dimension A (numeric) – single value or multiple values for A dimension B (numeric) – single value or multiple values for B dimension alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added

Examples

>>> from colorspace.colorlib import CIELAB
>>> c = CIELAB(-30, 10, 10)
>>> c = CIELAB([-30, 30], [20, 80], [40, 40])
>>> from numpy import asarray
>>> c = CIELAB(asarray([-30, 30]), asarray([20, 80]), asarray([40, 40]))


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary
class colorlib.polarLAB(L, A, B, alpha = None)[source]

polarLAB color object.

Allowes conversions to: CIEXYZ, CIELUV, CIELAB, RGB, polarLUV, polarLAB, “hex” (hexcols). Not possible are conversions to (ambiguous): HSV, HLS.

Parameters: L (numeric) – single value or multiple values for L dimension A (numeric) – single value or multiple values for A dimension B (numeric) – single value or multiple values for B dimension alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added
:param .. seealso::: This object extens the colorlib.colorobject which
provides some methods to e.g., extract color or to modify the whitepoint.
to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary.
class colorlib.HLS(H, L, S, alpha = None)[source]

HLS (Hue-Lightness-Saturation) color space.

Allowes conversions to: RGB, sRGB, HLS, and “hex” (hexcols). Not possible are conversions to (ambiguous): CIEXYZ, CIELUV, CIELAB, polarLUV, polarLAB,

Parameters: H (numeric) – single value or multiple values for the hue dimension L (numeric) – single value or multiple values for the lightness dimension S (numeric) – single value or multiple values for the saturation dimension alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added

Examples

>>> from colorspace.colorlib import HLS
>>> cols = HLS([150, 0, 10], [0.1, 0.7, 0.1], [3, 0, 3])


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.

to(to, fixup = True)[source]

Transforms the colors into a new color space, if possible.

No return, converts the object into a new color space and modifies the underlying object. After calling this method the original object will be of a different type.

Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary.
class colorlib.HSV(H, S, V, alpha = None)[source]

HSV (Hue-Saturation-Value) color object.

Allowes conversions to: RGB, sRGB, HLS, and “hex” (hexcols). Not possible are conversions to (ambiguous): CIEXYZ, CIELUV, CIELAB, polarLUV, polarLAB,

Parameters: H (numeric) – single value or multiple values for the hue dimension S (numeric) – single value or multiple values for the saturation dimension V (numeric) – single value or multiple values for the value dimension alpha (None or numeric) – single value or vector of numerics in [0.,1.] for the alpha channel (0. means transparent, 1. opaque). If None no transparency is added

Examples

>>> from colorspace.colorlib import HSV
>>> cols = HSV([150, 150, 10], [1.5, 0, 1.5], [0.1, 0.7, 0.1])


This object extens the colorlib.colorobject which provides some methods to e.g., extract color or to modify the whitepoint.
to(to, fixup = True)[source]
Parameters: to (str) – name of the color space into which the colors should be converted (e.g., CIEXYZ, HCL, hex, RGB, …) fixup (bool) – whether or not colors outside the defined rgb color space should be corrected if necessary.