5. Reference guide¶
5.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 Color(name=None, rgb=None, hls=None, hsv=None)[source]¶
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”.
- property 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
- property green¶
getter/setter for the green color in RGB triplet
- property hex¶
getter/setter the hexadecimal value.
- property hls¶
getter/setter the HLS values (3-length tuple)
- property hsv¶
getter/setter the HSV values (3-length tuple)
- property 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
- property lightness¶
getter/setter the lightness in the HLS triplet
- property red¶
getter/setter for the red color in RGB triplet
- property rgb¶
getter/setter the RGB values (3-length tuple)
- property saturation_hls¶
getter/setter the saturation in the HLS triplet
- property value¶
getter/setter the value in the HSV triplet
- property yiq¶
Getter for the YIQ triplet
- class Colormap[source]¶
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)
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:
Sequential schemes for unipolar data that progresses from low to high
Diverging schemes for bipolar data that emphasizes positive or negative deviations from acentral value
Cyclic schemes meant for plotting values that wrap around at the endpoints, such as phase angle, wind direction, or time of day
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)[source]¶
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)[source]¶
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)[source]¶
Provide 3 colors in format accepted by
Color
red = Color('red') cmap = cmap_linear(red, 'white', '#0000FF')
- get_cmap_heat()[source]¶
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()[source]¶
Return a heat colormap matplotlib-compatible colormap
Same as
get_cmap_heat()
but reversed
- get_cmap_rainbow()[source]¶
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)[source]¶
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)[source]¶
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)
- test_colormap(cmap=None)[source]¶
plot one colormap for testing
By default, test the
get_cmap_heat()
- class HEX[source]¶
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
- hex2dec(data)[source]¶
convert hexadecimal string (data) into a float in the [0-65536] inclusive range
- hex2rgb(hexcolor, normalise=False)[source]¶
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)
- hex2web(hexa)[source]¶
Convert hexadecimal string (6 digits) into web version (3 digits)
>>> from colormap.colors import hex2web >>> hex2web("#FFAA11") '#FA1'
- hls2rgb(h, l, s, normalised=True)[source]¶
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)
- hsv2rgb(h, s, v, normalised=True)[source]¶
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(r, g, b, normalised=False)[source]¶
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'
- rgb2hls(r, g, b, normalised=True)[source]¶
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)
- rgb2hsv(r, g, b, normalised=True)[source]¶
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)
- rgb2yuv(r, g, b)[source]¶
Convert RGB triplet into YUV
- Returns:
YUV triplet with values between 0 and 1
Warning
expected input must be between 0 and 1
Note
the constants referenc used is Rec. 601
- rgb2yuv_int(r, g, b)[source]¶
Convert RGB triplet into YUV
Warning
expected input must be between 0 and 255 (not normalised)
- to_intensity(n)[source]¶
Return intensity
- Parameters:
n – value between 0 and 1
- Returns:
value between 0 and 255; round(n*127.5+127.5)
- web2hex(web)[source]¶
Convert web hexadecimal string (3 digits) into 6 digits version
>>> from colormap.colors import web2hex >>> web2hex("#FA1") '#FFAA11'