Palettes¶

The palettes module provides a user-friendly interface to HCL based color palettes.

Rainbow HCL¶

class palettes.rainbow_hcl(c = 50, l = 70, start = 0, end = 360, gamma = None, fixup = True, rev = False, *args, **kwargs)[source]¶

HCL rainbow, a qualitative cyclic rainbow color palette with uniform luminance and chroma.

Parameters:

c (int) – chroma of the color map [0-100+].
l (int) – luminance of the color map [0-100].
start (int) – hue at which the rainbow should start.
end (int) – hue at which the rainbow should end.
rev (bool) – should the color map be reversed.
gamma (float) – gamma value used for transfiromation from/to sRGB. @TODO implemented? Check!
fixup (bool) – only used when converting the HCL colors to hex. Should RGB values outside the defined RGB color space be corrected?

Returns:

Initialize new object, no return. Raises a set of errors if the parameters
are misspecified. Note that the object is callable, the default object call
can be used to return hex colors (identical to the .colors() method),
see examples.

Example

>>> from colorspace import rainbow_hcl
>>> pal = rainbow_hcl()
>>> pal.colors(3); pal.colors(20)
>>> # The standard call of the object also returns hex colors. Thus,
>>> # you can make your code slimmer by calling:
>>> rainbow_hcl("Dynamic")(10)

Qualitative HCL¶

class palettes.qualitative_hcl(h = [0, 360.], c = 50, l = 70, fixup = True, palette = None, rev = False, **kwargs)[source]¶

Qualitative HCL color palette.

Parameters:

h (numeric list) – hue values, qualitative color palettes require two hues. If more than two values are provided the first two will be used while the rest is ignored. If input h is a string this argument acts like the palette argument (see palette input parameter).
c (numeric) – chroma value, a single numeric value. If multiple values are provided only the first one will be used.
l (numeric) – luminance value, a single numeric value. If multiple values are provided only the first one will be used.
fixup (bool) – only used when converting the HCL colors to hex. Should RGB values outside the defined RGB color space be corrected?
palette (None, string) – can be used to load a default diverging color palette specification. If the palette does not exist an exception will be raised. Else the settings of the palette as defined will be used to create the color palette.
rev (bool) – should the color map be reversed.
args – unused.
kwargs – Additional arguments to overwrite the h/c/l settings. @TODO has to be documented.

Returns:

Initialize new object, no return. Raises a set of errors if the parameters
are misspecified. Note that the object is callable, the default object call
can be used to return hex colors (identical to the .colors() method),
see examples.

Examples

>>> from colorspace import diverging_hcl
>>> a = qualitative_hcl()
>>> a.colors(10)
>>> b = qualitative_hcl("Dynamic")
>>> b.colors(10)
>>> # The standard call of the object also returns hex colors. Thus,
>>> # you can make your code slimmer by calling:
>>> qualitative_hcl("Dynamic")(10)

colors(n = 11, type_ = "hex", fixup = None)[source]¶

Returns the colors of the current color palette.

Parameters:	n (int) – number of colors which should be returned. fixup (None, bool) – should sRGB colors be corrected if they lie outside the defined color space? If `None` the `fixup` parameter from the object will be used. Can be set to `True` or `False` to explicitly control the fixup here.

Diverging HCL¶

class palettes.diverging_hcl(h = [260, 0], c = 80, l = [30, 90], power = 1.5, fixup = True, palette = None, rev = False, *args, **kwargs)[source]¶

Diverging HCL color palette.

Parameters:

h (numeric list) – hue values, diverging color palettes should have different hues for both ends of the palette. If only one value is present it will be recycled ending up in a diverging color palette with the same colors on both ends. If more than two values are provided the first two will be used while the rest is ignored. If input h is a string this argument acts like the palette argument (see palette input parameter).
c (numeric) – chroma value, a single numeric value. If multiple values are provided only the first one will be used.
l (numeric list) – luminance values. The first value is for the two ends of the color palette, the second one for the neutral center point. If only one value is given this value will be recycled.
power (numeric) – power parameter for non-linear behaviour of the color palette.
fixup (bool) – only used when converting the HCL colors to hex. Should RGB values outside the defined RGB color space be corrected?
palette (string) – can be used to load a default diverging color palette specification. If the palette does not exist an exception will be raised. Else the settings of the palette as defined will be used to create the color palette.
rev (bool) – should the color map be reversed.
args – unused.
kwargs – Additional arguments to overwrite the h/c/l settings. @TODO has to be documented.

Returns:

Initialize new object, no return. Raises a set of errors if the parameters
are misspecified. Note that the object is callable, the default object call
can be used to return hex colors (identical to the .colors() method),
see examples.

Examples

>>> from colorspace import diverging_hcl
>>> a = diverging_hcl()
>>> a.colors(10)
>>> b = diverging_hcl("Blue-Yellow 3")
>>> b.colors(10)
>>> # The standard call of the object also returns hex colors. Thus,
>>> # you can make your code slimmer by calling:
>>> diverging_hcl("Dynamic")(10)

colors(n = 11, type_ = "hex", fixup = None)[source]¶

Returns the colors of the current color palette.

Parameters:

n (int) – number of colors which should be returned.
fixup (None, bool) – should sRGB colors be corrected if they lie outside the defined color space? If None the fixup parameter from the object will be used. Can be set to True or False to explicitly control the fixup here.
alpha (None, float) – float (single value) or vector of floats in the range of [0.,1.] for alpha transparency channel (0. means full transparency, 1. opaque). If a single value is provided it will be applied to all colors, if a vector is given the length has to be n.

Sequential HCL¶

class palettes.sequential_hcl(h = 260, c = [80, 30], l = [30, 90], power = 1.5, fixup = True, palette = None, rev = False, *args, **kwargs)[source]¶

Sequential HCL color palette.

Parameters:

h (numeric) – hue values. If only one value is given the value is recycled which yields a single-hue sequential color palette. If input h is a string this argument acts like the palette argument (see palette input parameter).
c (numeric list) – chroma values, numeric of length two. If multiple values are provided only the first one will be used.
l (numeric list) – luminance values, numeric of length two. If multiple values are provided only the first one will be used.
power (numeric, numeric list) – power parameter for non-linear behaviour of the color palette. One or two values can be provided.
fixup (bool) – only used when converting the HCL colors to hex. Should RGB values outside the defined RGB color space be corrected?
palette (string) – can be used to load a default diverging color palette specification. If the palette does not exist an exception will be raised. Else the settings of the palette as defined will be used to create the color palette.
rev (bool) – should the color map be reversed.
args – unused.
kwargs – Additional arguments to overwrite the h/c/l settings. @TODO has to be documented.

Returns:

Initialize new object, no return. Raises a set of errors if the parameters
are misspecified. Note that the object is callable, the default object call
can be used to return hex colors (identical to the .colors() method),
see examples.

Examples

>>> from colorspace import sequential_hcl
>>> a = sequential_hcl()
>>> a.colors(10)
>>> b = sequential_hcl("Reds")
>>> b.colors(10)
>>> # The standard call of the object also returns hex colors. Thus,
>>> # you can make your code slimmer by calling:
>>> sequential_hcl("Dynamic")(10)

colors(n = 11, type_ = "hex", fixup = None)[source]¶

Returns the colors of the current color palette.

Parameters:	n (int) – number of colors which should be returned. fixup (None, bool) – should sRGB colors be corrected if they lie outside the defined color space? If `None` the `fixup` parameter from the object will be used. Can be set to `True` or `False` to explicitly control the fixup here.

HCL Palette Baseclass¶

The different HCL color palettes (palettes.rainbow_hcl, palettes.diverging_hcl, palettes.qualitative_hcl) are extending tihs palettes.hclpalette base class.

The palettes.hclpalette class provides several methods to interact with the HCL palette objects above to e.g., extract colors or check the current palette settings.

class palettes.hclpalette[source]¶

Hy, I am the base class. Is extended by the different HCL based color palettes such as the classes diverging_hcl, qualitative_hcl, rainbow_hcl, sequential_hcl, and maybe more in the future.

cmap(n = 51, name = "custom_hcl_cmap")[source]¶

Allows to retrieve a matplotlib LinearSegmentedColormap color map. Clasically LinearSegmentedColormaps allow to retrieve a set of N colors from a set of n colors where N >> n. The matplotlib simply linearely interpolates between all n colors to extend the number of colors to N.

In case of hclpalette() objects this is not necessary as hclpalette() objects allow to retrieve N colors directly along well-specified Hue-Chroma-Luminance paths. Thus, this method returns a matplotlib color map with n==N colors. The linear interpolation between the colors (as typically done by LinearSegmentedColormap) is not necessary. However, for convenience cmaps have been implemented such that you can easily use hcl based palettes in your existing workflow.

Parameters:	n (int) – number of colors name (str) – name of the custom color map. Default is `custom_hcl_cmap`
Returns:	Returns a `LinearSegmentedColormap` (cmap) to be used with the matplotlib library.
Return type:	matplotlib.colors.LinearSegmentedColormap

get(key)[source]¶

Returns one specific item of the palette settings, e.g., the current value for h1 or l2. If not existing a None will be returned.

Parameters:	key (str) – name of the setting to be returned.
Returns:	None if `key` does ont exist, else the current value will be returned.

Examples

>>> from colorspace.palettes import rainbow_hcl
>>> a = rainbow_hcl()
>>> a.get("h1")
>>> a.get("c1")
>>> a.get("l1")
>>> a.get("not_defined")

name()[source]¶

Returns:
Return type:	Returns the name of the palette, string.

show_settings()[source]¶

Shows the current settings (table like print to stdout). Should more be seen as a development method than a very useful thing.

Examples

>>> from colorspace.palettes import rainbow_hcl
>>> a = rainbow_hcl(10)
>>> a.show_settings()

specplot(n = 180, *args, **kwargs)[source]¶

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

Parameters:	n (int) – number of colors. args – forwarded to `specplot.specplot()`. kwargs – forwarded to `specplot.specplot()`.

Examples

>>> from colorspace import diverging_hcl
>>> pal = diverging_hcl()
>>> pal.specplot()
>>> pal.specplot(rgb = False)

swatchplot(n = 7)[source]¶

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

Parameters:	n (int) – number of colors.

Examples

>>> from colorspace import diverging_hcl
>>> pal = diverging_hcl()
>>> pal.swatchplot()
>>> pal.swatchplot(n = 21)

Other Methods¶

class palettes.palette(colors, name)[source]¶: Custom named color palette with a fixed number of colors. Used for hcl_palettes.swatchplot().

class palettes.hclpalette[source]: Hy, I am the base class. Is extended by the different HCL based color palettes such as the classes diverging_hcl, qualitative_hcl, rainbow_hcl, sequential_hcl, and maybe more in the future.