Colors

This module defines a Color object and helper functions (see, e.g., hue(), rainbow()), as well as a set of colors and colormaps to use with sage.plot.plot.Graphics objects in Sage.

For a list of pre-defined colors in Sage, evaluate:

sage: sorted(colors)
['aliceblue', 'antiquewhite', 'aqua', 'aquamarine', 'automatic', ...]

Apart from ‘automatic’ which just an alias for ‘lightblue’, this list comprises the “official” W3C CSS3 / SVG colors.

For a list of color maps in Sage, evaluate:

sage: sorted(colormaps)
['Accent', 'Accent_r', 'Blues', 'Blues_r', 'BrBG', 'BrBG_r', ...]

These are imported from matplotlib’s cm module.

class sage.plot.colors.Color(r='#0000ff', g=None, b=None, space='rgb')

Bases: object

blend(color, fraction=0.5)

Return a color blended with the given color by a given fraction. The algorithm interpolates linearly between the colors’ corresponding R, G, and B coordinates.

INPUT:

• color - a Color instance or float-convertible 3-tuple/list; the color with which to blend this color
• fraction - a float-convertible number; the fraction of color to blend with this color

OUTPUT:

• a new Color instance

EXAMPLES:

sage: from sage.plot.colors import red, blue, lime
sage: red.blend(blue)
RGB color (0.5, 0.0, 0.5)
sage: red.blend(blue, fraction=0.0)
RGB color (1.0, 0.0, 0.0)
sage: red.blend(blue, fraction=1.0)
RGB color (0.0, 0.0, 1.0)
sage: lime.blend((0.3, 0.5, 0.7))
RGB color (0.14999999999999999, 0.75, 0.34999999999999998)
sage: blue.blend(blue)
RGB color (0.0, 0.0, 1.0)
sage: red.blend(lime, fraction=0.3)
RGB color (0.69999999999999996, 0.29999999999999999, 0.0)
sage: blue.blend((0.0, 0.9, 0.2), fraction=0.2)
RGB color (0.0, 0.18000000000000002, 0.84000000000000008)
sage: red.blend(0.2)
...
TypeError: 0.200000000000000 must be a Color or float-convertible 3-tuple/list

darker(fraction=0.33333333333333331)

Return a darker “shade” of this RGB color by blend()-ing it with black. This is not an inverse of lighter().

INPUT:

• fraction - a float (default: 1.0/3.0); blending fraction to apply

OUTPUT:

• a new instance of Color

EXAMPLES:

sage: from sage.plot.colors import black
sage: vector(black.darker().rgb()) == vector(black.rgb())
True
sage: Color(0.4, 0.6, 0.8).darker(0.1)
RGB color (0.36000000000000004, 0.54000000000000004, 0.72000000000000008)
sage: Color(.1,.2,.3,space='hsl').darker()
RGB color (0.24000000000000002, 0.20800000000000002, 0.16)

hls()

Return the Hue-Lightness-Saturation (HLS) coordinates of this color.

OUTPUT:

• a 3-tuple of floats

EXAMPLES:

sage: Color(0.3, 0.5, 0.7, space='hls').hls()
(0.30000000000000004, 0.5, 0.69999999999999996)
sage: Color(0.3, 0.5, 0.7, space='hsl').hls()
(0.30000000000000004, 0.69999999999999996, 0.50000000000000011)
sage: Color('#aabbcc').hls()
(0.58333333333333337, 0.73333333333333339, 0.25000000000000017)
sage: from sage.plot.colors import orchid
sage: orchid.hls()
(0.83962264150943389, 0.64705882352941169, 0.58888888888888891)

hsl()

Return the Hue-Saturation-Lightness (HSL) coordinates of this color.

OUTPUT:

• a 3-tuple of floats

EXAMPLES:

sage: Color(1,0,0).hsl()
(0.0, 1.0, 0.5)
sage: from sage.plot.colors import orchid
sage: orchid.hsl()
(0.83962264150943389, 0.58888888888888891, 0.64705882352941169)
sage: Color('#aabbcc').hsl()
(0.58333333333333337, 0.25000000000000017, 0.73333333333333339)

hsv()

Return the Hue-Saturation-Value (HSV) coordinates of this color.

OUTPUT:

• a 3-tuple of floats

EXAMPLES:

sage: from sage.plot.colors import red
sage: red.hsv()
(0.0, 1.0, 1.0)
sage: Color(1,1,1).hsv()
(0.0, 0.0, 1.0)
sage: Color('gray').hsv()
(0.0, 0.0, 0.50196078431372548)

html_color()

Return a HTML hex representation for this color.

OUTPUT:

• a string of length 7.

EXAMPLES:

sage: Color('yellow').html_color()
'#ffff00'
sage: Color('#fedcba').html_color()
'#fedcba'
sage: Color(0.0, 1.0, 0.0).html_color()
'#00ff00'
sage: from sage.plot.colors import honeydew
sage: honeydew.html_color()
'#f0fff0'

lighter(fraction=0.33333333333333331)

Return a lighter “shade” of this RGB color by blend()-ing it with white. This is not an inverse of darker().

INPUT:

• fraction - a float (default: 1.0/3.0); blending fraction to apply

OUTPUT:

• a new instance of Color

EXAMPLES:

sage: from sage.plot.colors import khaki
sage: khaki.lighter()
RGB color (0.96078431372549034, 0.934640522875817, 0.69934640522875824)
sage: Color('white').lighter().darker()
RGB color (0.66666666666666674, 0.66666666666666674, 0.66666666666666674)
sage: Color('#abcdef').lighter(1/4)
RGB color (0.75294117647058822, 0.85294117647058831, 0.95294117647058818)
sage: Color(1, 0, 8/9, space='hsv').lighter()
RGB color (0.92592592592592604, 0.92592592592592604, 0.92592592592592604)

rgb()

Return the underlying Red-Green-Blue (RGB) coordinates of this color.

OUTPUT:

• a 3-tuple of floats

EXAMPLES:

sage: Color(0.3, 0.5, 0.7).rgb()
(0.29999999999999999, 0.5, 0.69999999999999996)
sage: Color('#8000ff').rgb()
(0.50196078431372548, 0.0, 1.0)
sage: from sage.plot.colors import orange
sage: orange.rgb()
(1.0, 0.6470588235294118, 0.0)
sage: Color('magenta').rgb()
(1.0, 0.0, 1.0)
sage: Color(1, 0.7, 0.9, space='hsv').rgb()
(0.90000000000000002, 0.27000000000000007, 0.27000000000000007)

class sage.plot.colors.Colormaps

Bases: _abcoll.MutableMapping

A dict-like collection of lazily-loaded matplotlib color maps. For a list of map names, evaluate:

sage: sorted(colormaps)
['Accent', 'Accent_r', 'Blues', 'Blues_r', ...]

load_maps()

If it’s necessary, loads matplotlib’s color maps and adds them to the collection.

EXAMPLES:

sage: from sage.plot.colors import Colormaps
sage: maps = Colormaps()
sage: len(maps.maps)
0
sage: maps.load_maps()
sage: len(maps.maps)
116

class sage.plot.colors.ColorsDict

Bases: dict

A dict-like collection of colors, accessible via key or attribute. For a list of color names, evaluate:

sage: sorted(colors)
['aliceblue', 'antiquewhite', 'aqua', 'aquamarine', ...]

sage.plot.colors.float_to_html(r, g, b)

Converts a Red-Green-Blue (RGB) color tuple to a HTML hex color. Each input value should be in the interval [0.0, 1.0]; otherwise, the values are first reduced modulo one (see mod_one()).

INPUT:

• r - a number; the RGB color’s “red” intensity
• g - a number; the RGB color’s “green” intensity
• b - a number; the RGB color’s “blue” intensity

OUTPUT:

• a string of length 7, starting with ‘#’

EXAMPLES:

sage: from sage.plot.colors import float_to_html
sage: float_to_html(1.,1.,0.)
'#ffff00'
sage: float_to_html(.03,.06,.02)
'#070f05'
sage: float_to_html(*Color('brown').rgb())
'#a52a2a'
sage: float_to_html((0.2, 0.6, 0.8))
...
TypeError: float_to_html() takes exactly 3 arguments (1 given)

sage.plot.colors.get_cmap(cmap)

Returns a color map (actually, a matplotlib Colormap object), given its name or a [mixed] list/tuple of RGB list/tuples and color names. For a list of map names, evaluate:

sage: sorted(colormaps)
['Accent', 'Accent_r', 'Blues', 'Blues_r', ...]

See rgbcolor() for valid list/tuple element formats.

INPUT:

• cmap - a string, list, tuple, or matplotlib.colors.Colormap; a string must be a valid color map name

OUTPUT:

• a matplotlib.colors.Colormap instance

EXAMPLES:

sage: from sage.plot.colors import get_cmap
sage: get_cmap('jet')
<matplotlib.colors.LinearSegmentedColormap instance at 0x...>
sage: get_cmap([(0,0,0), (0.5,0.5,0.5), (1,1,1)])
<matplotlib.colors.ListedColormap instance at 0x...>
sage: get_cmap(['green', 'lightblue', 'blue'])
<matplotlib.colors.ListedColormap instance at 0x...>
sage: get_cmap(((0.5, 0.3, 0.2), [1.0, 0.0, 0.5], 'purple', Color(0.5,0.5,1, space='hsv')))
<matplotlib.colors.ListedColormap instance at 0x...>
sage: get_cmap('jolies')
...
RuntimeError: Color map jolies not known (type import matplotlib.cm; matplotlib.cm.datad.keys() for valid names)
sage: get_cmap('mpl')
...
RuntimeError: Color map mpl not known (type import matplotlib.cm; matplotlib.cm.datad.keys() for valid names)

sage.plot.colors.html_to_float(c)

Convert a HTML hex color to a Red-Green-Blue (RGB) tuple.

INPUT:

• c - a string; a valid HTML hex color

OUTPUT:

• a RGB 3-tuple of floats in the interval [0.0, 1.0]

EXAMPLES:

sage: from sage.plot.colors import html_to_float
sage: html_to_float('#fff')
(1.0, 1.0, 1.0)
sage: html_to_float('#abcdef')
(0.6705882352941176, 0.80392156862745101, 0.93725490196078431)
sage: html_to_float('#123xyz')
...
ValueError: invalid literal for int() with base 16: '3x'

sage.plot.colors.hue(h, s=1, v=1)

Convert a Hue-Saturation-Value (HSV) color tuple to a valid Red-Green-Blue (RGB) tuple. All three inputs should lie in the interval [0.0, 1.0]; otherwise, they are reduced modulo 1 (see mod_one()). In particular h=0 and h=1 yield red, with the intermediate hues orange, yellow, green, cyan, blue, and violet as h increases.

This function makes it easy to sample a broad range of colors for graphics:

sage: p = Graphics()
sage: for phi in xsrange(0, 2 * pi, 1 / pi):
...       p += plot(sin(x + phi), (x, -7, 7), rgbcolor = hue(phi))
sage: p

INPUT:

• h - a number; the color’s hue
• s - a number (default: 1); the color’s saturation
• v - a number (default: 1); the color’s value

OUTPUT:

• a RGB 3-tuple of floats in the interval [0.0, 1.0]

EXAMPLES:

sage: hue(0.6)
(0.0, 0.40000000000000036, 1.0)
sage: from sage.plot.colors import royalblue
sage: royalblue
RGB color (0.25490196078431371, 0.41176470588235292, 0.88235294117647056)
sage: hue(*royalblue.hsv())
(0.25490196078431371, 0.41176470588235292, 0.88235294117647056)

Note

The HSV to RGB coordinate transformation itself is given in the source code for the Python library’s colorsys module:

sage: from colorsys import hsv_to_rgb    # not tested
sage: hsv_to_rgb??                       # not tested

sage.plot.colors.mod_one(x)

Reduce a number modulo 1.

INPUT:

• x - an instance of Integer, int, RealNumber, etc.; the number to reduce

OUTPUT:

• a float

EXAMPLES:

sage: from sage.plot.colors import mod_one
sage: mod_one(1)
1.0
sage: mod_one(7.0)
0.0
sage: mod_one(-11/7)
0.4285714285714286
sage: mod_one(pi) + mod_one(-pi)
1.0

sage.plot.colors.rainbow(n, format='hex')

Returns a list of colors sampled at equal intervals over the spectrum, from Hue-Saturation-Value (HSV) coordinates (0, 1, 1) to (1, 1, 1). This range is red at the extremes, but it covers orange, yellow, green, cyan, blue, violet, and many other hues in between. This function is particularly useful for representing vertex partitions on graphs.

INPUT:

• n - a number; the length of the list
• format - a string (default: ‘hex’); the output format for each color in the list; the other choice is ‘rgbtuple’

OUTPUT:

• a list of strings or RGB 3-tuples of floats in the interval [0.0, 1.0]

EXAMPLES:

sage: from sage.plot.colors import rainbow
sage: rainbow(7)
['#ff0000', '#ffda00', '#48ff00', '#00ff91', '#0091ff', '#4800ff', '#ff00da']
sage: rainbow(7, 'rgbtuple')
[(1.0, 0.0, 0.0), (1.0, 0.8571428571428571, 0.0), (0.28571428571428581, 1.0, 0.0), (0.0, 1.0, 0.57142857142857117), (0.0, 0.57142857142857162, 1.0), (0.2857142857142847, 0.0, 1.0), (1.0, 0.0, 0.85714285714285765)]

AUTHORS:

• Robert L. Miller
• Karl-Dieter Crisman (directly use hsv_to_rgb() for hues)

sage.plot.colors.rgbcolor(c, space='rgb')

Convert a color (string, tuple, list, or Color) to a mod-one reduced (see mod_one()) valid Red-Green-Blue (RGB) tuple. The returned tuple is also a valid matplotlib RGB color.

INPUT:

• c - a Color instance, string (name or HTML hex), 3-tuple, or 3-list; the color to convert
• space - a string (default: ‘rgb’); the color space coordinate system (other choices are ‘hsl’, ‘hls’, and ‘hsv’) in which to interpret a 3-tuple or 3-list

OUTPUT:

• a RGB 3-tuple of floats in the interval [0.0, 1.0]

EXAMPLES:

sage: from sage.plot.colors import rgbcolor
sage: rgbcolor(Color(0.25, 0.4, 0.9))
(0.25, 0.40000000000000002, 0.90000000000000002)
sage: rgbcolor('purple')
(0.50196078431372548, 0.0, 0.50196078431372548)
sage: rgbcolor('#fa0')
(1.0, 0.66666666666666663, 0.0)
sage: rgbcolor('#ffffff')
(1.0, 1.0, 1.0)
sage: rgbcolor((1,1/2,1/3))
(1.0, 0.5, 0.33333333333333331)
sage: rgbcolor([1,1/2,1/3])
(1.0, 0.5, 0.33333333333333331)
sage: rgbcolor((1,1,1), space='hsv')
(1.0, 0.0, 0.0)
sage: rgbcolor((0.5,0.75,1), space='hls')
(0.5, 0.99999999999999989, 1.0)
sage: rgbcolor((0.5,1.0,0.75), space='hsl')
(0.5, 0.99999999999999989, 1.0)
sage: rgbcolor([1,2,255])   # WARNING -- numbers are reduced mod 1!!
(1.0, 0.0, 0.0)
sage: rgbcolor('#abcd')
...
ValueError: color hex string (= 'abcd') must have length 3 or 6
sage: rgbcolor('fff')
...
ValueError: unknown color 'fff'
sage: rgbcolor(1)
...
TypeError: '1' must be a Color, list, tuple, or string
sage: rgbcolor((0.2,0.8,1), space='grassmann')
...
ValueError: space must be one of 'rgb', 'hsv', 'hsl', 'hls'
sage: rgbcolor([0.4, 0.1])
...
ValueError: color list or tuple '[0.400000000000000, 0.100000000000000]' must have 3 entries, one for each RGB, HSV, HLS, or HSL channel

sage.plot.colors.to_mpl_color(c, space='rgb')

Convert a color (string, tuple, list, or Color) to a mod-one reduced (see mod_one()) valid Red-Green-Blue (RGB) tuple. The returned tuple is also a valid matplotlib RGB color.

INPUT:

• c - a Color instance, string (name or HTML hex), 3-tuple, or 3-list; the color to convert
• space - a string (default: ‘rgb’); the color space coordinate system (other choices are ‘hsl’, ‘hls’, and ‘hsv’) in which to interpret a 3-tuple or 3-list

OUTPUT:

• a RGB 3-tuple of floats in the interval [0.0, 1.0]

EXAMPLES:

sage: from sage.plot.colors import rgbcolor
sage: rgbcolor(Color(0.25, 0.4, 0.9))
(0.25, 0.40000000000000002, 0.90000000000000002)
sage: rgbcolor('purple')
(0.50196078431372548, 0.0, 0.50196078431372548)
sage: rgbcolor('#fa0')
(1.0, 0.66666666666666663, 0.0)
sage: rgbcolor('#ffffff')
(1.0, 1.0, 1.0)
sage: rgbcolor((1,1/2,1/3))
(1.0, 0.5, 0.33333333333333331)
sage: rgbcolor([1,1/2,1/3])
(1.0, 0.5, 0.33333333333333331)
sage: rgbcolor((1,1,1), space='hsv')
(1.0, 0.0, 0.0)
sage: rgbcolor((0.5,0.75,1), space='hls')
(0.5, 0.99999999999999989, 1.0)
sage: rgbcolor((0.5,1.0,0.75), space='hsl')
(0.5, 0.99999999999999989, 1.0)
sage: rgbcolor([1,2,255])   # WARNING -- numbers are reduced mod 1!!
(1.0, 0.0, 0.0)
sage: rgbcolor('#abcd')
...
ValueError: color hex string (= 'abcd') must have length 3 or 6
sage: rgbcolor('fff')
...
ValueError: unknown color 'fff'
sage: rgbcolor(1)
...
TypeError: '1' must be a Color, list, tuple, or string
sage: rgbcolor((0.2,0.8,1), space='grassmann')
...
ValueError: space must be one of 'rgb', 'hsv', 'hsl', 'hls'
sage: rgbcolor([0.4, 0.1])
...
ValueError: color list or tuple '[0.400000000000000, 0.100000000000000]' must have 3 entries, one for each RGB, HSV, HLS, or HSL channel