1. Reference guide

1.1. colors

Utilities provided in this module can be found either in the standard Python module called colorsys or in matplotlib.colors (e.g rgb2hex) or are original to this module (e.g., rgb2huv)

class HEX

Class to check the validity of an hexadecimal string and get standard string

By standard, we mean #FFFFFF (6 digits)

>>> h = HEX()
>>> h.is_valid_hex_color("#FFFF00")
True
get_standard_hex_color(value)

Return standard hexadecimal color

By standard, we mean a string that starts with # sign followed by 6 character, e.g. #AABBFF

is_valid_hex_color(value, verbose=True)

Return True is the string can be interpreted as hexadecimal color

Valid formats are

  • #FFF
  • #0000FF
  • 0x0000FF
  • 0xFA1
class Color(name=None, rgb=None, hls=None, hsv=None)

Class to ease manipulation and conversion between color codes

You can create an instance in many differen ways. You can either use a human-readable name as long as it is part of the XFree86 list You can also provide a hexadecimal string (either 3 or 6 digits). You can use triplets of values corresponding to the RGB, HSV or HLS conventions.

Here are some examples:

from colormap import Color

Color("red")           # human XFree86 compatible representation
Color("#f00")          # standard 3 hex digits
Color("#ff0000")       # standard 6 hex digits
Color(hsv=(0,1,0.5))
Color(hls=(0, 1, 0.5)) # HLS triplet
Color(rgb=(1, 0, 0))   # RGB triplet
Color(Color("red"))    # using an instance of :class:`Color`

Note that the RGB, HLS and HSV triplets use normalised values. If you need to normalise the triplet, you can use colormap.colors._normalise that provides a function to normalise RGB, HLS and HSV triplets:

colors._normalise(*(255, 255, 0), mode="rgb")
colors._normalise(*(360, 50, 100), mode="hls")

If you provide a string, it has to be a valid string from XFree86. In addition to the official names, the lower case names are valid. Besides, there are names with spaces. The equivalent names without space are also valid. Therefore the name “Spring Green”, which is an official name can be provided as “Spring Green”, “spring green”, “springgreen” or “SpringGreen”.

blue

getter/setter for the blue color in RGB triplet

get_standard_hex_color(value)

Return standard hexadecimal color

By standard, we mean a string that starts with # sign followed by 6 character, e.g. #AABBFF

green

getter/setter for the green color in RGB triplet

hex

getter/setter the hexadecimal value.

hls

getter/setter the HLS values (3-length tuple)

hsv

getter/setter the HSV values (3-length tuple)

hue

getter/setter the saturation in the HLS triplet

is_valid_hex_color(value, verbose=True)

Return True is the string can be interpreted as hexadecimal color

Valid formats are

  • #FFF
  • #0000FF
  • 0x0000FF
  • 0xFA1
lightness

getter/setter the lightness in the HLS triplet

red

getter/setter for the red color in RGB triplet

rgb

getter/setter the RGB values (3-length tuple)

saturation_hls

getter/setter the saturation in the HLS triplet

value

getter/setter the value in the HSV triplet

yiq

Getter for the YIQ triplet

hex2web(hexa)

Convert hexadecimal string (6 digits) into web version (3 digits)

>>> from colormap.colors import hex2web
>>> hex2web("#FFAA11")
'#FA1'
web2hex(web)

Convert web hexadecimal string (3 digits) into 6 digits version

>>> from colormap.colors import web2hex
>>> web2hex("#FA1")
'#FFAA11'
hex2rgb(hexcolor, normalise=False)

This function converts a hex color triplet into RGB

Valid hex code are:

  • #FFF
  • #0000FF
  • 0x0000FF
  • 0xFA1
>>> from colormap.colors import hex2rgb
>>> hex2rgb("#FFF", normalise=False)
(255, 255, 255)
>>> hex2rgb("#FFFFFF", normalise=True)
(1.0, 1.0, 1.0)
hex2dec(data)

convert hexadecimal string (data) into a float in the [0-65536] inclusive range

rgb2hex(r, g, b, normalised=False)

Convert RGB to hexadecimal color

Param:can be a tuple/list/set of 3 values (R,G,B)
Returns:a hex vesion ofthe RGB 3-tuple
>>> from colormap.colors import rgb2hex
>>> rgb2hex(0,0,255, normalised=False)
'#0000FF'
>>> rgb2hex(0,0,1, normalised=True)
'#0000FF'
rgb2hsv(r, g, b, normalised=True)

Convert an RGB value to an HSV value.

Parameters:normalised (bool) – if normalised is True, the input RGB triplet should be in the range 0-1 (0-255 otherwise)
Returns:the HSV triplet. If normalised parameter is True, the output triplet is in the range 0-1; otherwise, H in the range 0-360 and LS in the range 0-100.
>>> from colormap.colors import rgb2hsv
>>> rgb2hsv(0.5,0,1)
(0.75, 1, 1)
hsv2rgb(h, s, v, normalised=True)

Convert a hue-saturation-value (HSV) value to a red-green-blue (RGB).

Parameters:normalised (bool) – If normalised is True, the input HSV triplet should be in the range 0-1; otherwise, H in the range 0-360 and LS in the range 0-100.
Returns:the RGB triplet. The output triplet is in the range 0-1 whether the input is normalised or not.
>>> from colormap.colors import hsv2rgb
>>> hsv2rgb(0.5,1,1, normalised=True)  
(0, 1, 1)

See also

rgb2hex()

rgb2hls(r, g, b, normalised=True)

Convert an RGB value to an HLS value.

Parameters:normalised (bool) – if normalised is True, the input RGB triplet should be in the range 0-1 (0-255 otherwise)
Returns:the HLS triplet. If normalised parameter is True, the output triplet is in the range 0-1; otherwise, H in the range 0-360 and LS in the range 0-100.
>>> from colormap.colors import rgb2hls
>>> rgb2hls(255,255,255, normalised=False)
(0.0, 1.0, 0.0)
hls2rgb(h, l, s, normalised=True)

Convert an HLS value to a RGB value.

Parameters:normalised (bool) – If normalised is True, the input HLS triplet should be in the range 0-1; otherwise, H in the range 0-360 and LS in the range 0-100.
Returns:the RGB triplet. The output triplet is in the range 0-1 whether the input is normalised or not.
>>> from colormap.colors import hls2rgb
>>> hls2rgb(360, 50, 60, normalised=False)  
(0.8, 0.2, 0.2)
yuv2rgb(y, u, v)

Convert YUV triplet into RGB

YUV

Warning

expected input must be between 0 and 255 (not normalised)

rgb2yuv(r, g, b)

Convert RGB triplet into YUV

Returns:YUV triplet with values between 0 and 1

YUV wikipedia

Warning

expected input must be between 0 and 1

Note

the constants referenc used is Rec. 601

to_intensity(n)

Return intensity

Parameters:n – value between 0 and 1
Returns:value between 0 and 255; round(n*127.5+127.5)
yuv2rgb_int(y, u, v)

Convert YUV triplet into RGB

YUV

Warning

expected input must be between 0 and 255 (not normalised)

rgb2yuv_int(r, g, b)

Convert RGB triplet into YUV

YUV wikipedia

Warning

expected input must be between 0 and 255 (not normalised)

class Colormap

Class to create matplotlib colormap

This example show how to get the pre-defined colormap called heat

from pylab import *
from colormap.colors import Colormap

c = Colormap()
cmap = c.get_cmap_heat()
c.test_colormap(cmap)

(Source code, png, hires.png, pdf)

_images/references-1.png

You may be more interested in building your own colormap:

# design your own colormap
d = {'blue': [0,0,0,1,1,1,0],
        'green':[0,1,1,1,0,0,0],
        'red':  [1,1,0,0,0,1,1]}
cmap = c.cmap(d, reverse=False)

# see the results
c.test_colormap(cmap)

If you want a simple linear colormap, you can use the example above, or use the cmap_linear(). For instance for a diverging colormap from red to green (with with color in between):

cmap = c.cmap_linear("red", "white", "green")
c.test_colormap(cmap)

Even simpler, you can use a bicolor colormap cmap_bicolor(). For instance for a red to green colormap:

cmap = c.cmap_bicolor("red", "green")
c.test_colormap(cmap)

From matplotlib documentation, colormaps falls into 4 categories:

  1. Sequential schemes for unipolar data that progresses from low to high
  2. Diverging schemes for bipolar data that emphasizes positive or negative deviations from acentral value
  3. Cyclic schemes meant for plotting values that wrap around at the endpoints, such as phase angle, wind direction, or time of day
  4. Qualitative schemes for nominal data that has no inherent ordering, where color is used only to distinguish categories
References:matplotlib documentation and examples http://matplotlib.org/examples/color/colormaps_reference.html
cmap(colors=None, reverse=False, N=256)

Return a colormap object to be used within matplotlib

Parameters:
  • colors (dict) – a dictionary that defines the RGB colors to be used in the colormap. See get_cmap_heat() for an example.
  • reverse (bool) – reverse the colormap is set to True (defaults to False)
  • N (int) – Defaults to 50
cmap_bicolor(color1, color2, reverse=False, N=256)

Provide 3 colors in format accepted by Color

>>> red = Color('red')
>>> white = Color('white')
>>> cmap = cmap_bicolor(red, white)
cmap_linear(color1, color2, color3, reverse=False, N=256)

Provide 3 colors in format accepted by Color

red = Color('red')
cmap = cmap_linear(red, 'white', '#0000FF')
get_cmap_heat()

Return a heat colormap matplotlib-compatible colormap

This heat colormap should be equivalent to heat.colors() in R.

>>> from colormap.colors import Colormap
>>> cmap = Colormap.get_cmap_heat()

You can generate the colormap based solely on this information for the RGB functions along:

d=  {   'blue':[0,0,0,0,1],
        'green':[0,.35,.7,1,1],
        'red':[1,1,1,1,1]}
cmap = Colormap.get_cmap(d)
get_cmap_heat_r()

Return a heat colormap matplotlib-compatible colormap

Same as get_cmap_heat() but reversed

get_cmap_rainbow()

colormap similar to rainbow colormap from R

Note

The red is actually appearing on both sides… Yet this looks like what is coded in R 3.0.1

plot_colormap(cmap_list=None)

cmap_list list of valid cmap or name of a set (sequential, diverging,)

if none, plot all known colors

plot_rgb_from_hex_list(cols)

This functions takes a list of hexadecimal values and plots the RGB curves. This can be handy to figure out the RGB functions to be used in the get_cmap().

from colormap.colors import Colormap
c = Colormap()
t = ['#FF0000FF', '#FF4D00FF', '#FF9900FF', '#FFE500FF',
     '#CCFF00FF', '#80FF00FF', '#33FF00FF', '#00FF19FF',
     '#00FF66FF', '#00FFB2FF', '#00FFFFFF', '#00B3FFFF',
     '#0066FFFF', '#001AFFFF', '#3300FFFF', '#7F00FFFF',
     '#CC00FFFF','#FF00E6FF','#FF0099FF', '#FF004DFF']
c.plot_rgb_from_hex_list(t)

(Source code, png, hires.png, pdf)

_images/references-2.png
test_colormap(cmap=None)

plot one colormap for testing

By default, test the get_cmap_heat()