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 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', ...]

These are imported from matplotlib’s colormaps collection.

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

Bases: object

An Red-Green-Blue (RGB) color model color object. For most consumer-grade devices (e.g., CRTs, LCDs, and printers), as well as internet applications, this is a point in the sRGB absolute color space. The Hue-Saturation-Lightness (HSL), Hue-Lightness-Saturation (HLS), and Hue-Saturation-Value (HSV) spaces are useful alternate representations, or coordinate transformations, of this space. Coordinates in all of these spaces are floating point values in the interval [0.0, 1.0].

Note

All instantiations of Color are converted to an internal RGB floating point 3-tuple. This is likely to degrade precision.

INPUT:

• r,g,b - either a triple of floats between 0 and 1, OR r - a color name string or HTML color hex string

• space - a string (default: ‘rgb’); the coordinate system (other choices are ‘hsl’, ‘hls’, and ‘hsv’) in which to interpret a triple of floats

EXAMPLES:

sage: Color('purple')
RGB color (0.5019607843137255, 0.0, 0.5019607843137255)
sage: Color('#8000ff')
RGB color (0.5019607843137255, 0.0, 1.0)
sage: Color(0.5,0,1)
RGB color (0.5, 0.0, 1.0)
sage: Color(0.5, 1.0, 1, space='hsv')
RGB color (0.0, 1.0, 1.0)
sage: Color(0.25, 0.5, 0.5, space='hls')
RGB color (0.5000000000000001, 0.75, 0.25)
sage: Color(1, 0, 1/3, space='hsl')
RGB color (0.3333333333333333, 0.3333333333333333, 0.3333333333333333)
sage: from sage.plot.colors import chocolate
sage: Color(chocolate)
RGB color (0.8235294117647058, 0.4117647058823529, 0.11764705882352941)

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.15, 0.75, 0.35)
sage: blue.blend(blue)
RGB color (0.0, 0.0, 1.0)
sage: red.blend(lime, fraction=0.3)
RGB color (0.7, 0.3, 0.0)
sage: blue.blend((0.0, 0.9, 0.2), fraction=0.2)
RGB color (0.0, 0.18000000000000002, 0.8400000000000001)
sage: red.blend(0.2)
Traceback (most recent call last):
...
TypeError: 0.200000000000000 must be a Color or float-convertible 3-tuple/list

darker(fraction=0.3333333333333333)

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/3); 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.54, 0.7200000000000001)
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.7)
sage: Color(0.3, 0.5, 0.7, space='hsl').hls() # abs tol 1e-15
(0.30000000000000004, 0.7, 0.5000000000000001)
sage: Color('#aabbcc').hls() # abs tol 1e-15
(0.5833333333333334, 0.7333333333333334, 0.25000000000000017)
sage: from sage.plot.colors import orchid
sage: orchid.hls() # abs tol 1e-15
(0.8396226415094339, 0.6470588235294117, 0.5888888888888889)

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() # abs tol 1e-15
(0.8396226415094339, 0.5888888888888889, 0.6470588235294117)
sage: Color('#aabbcc').hsl() # abs tol 1e-15
(0.5833333333333334, 0.25000000000000017, 0.7333333333333334)

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.5019607843137255)

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.3333333333333333)

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/3); blending fraction to apply

OUTPUT:

• a new instance of Color

EXAMPLES:

sage: from sage.plot.colors import khaki
sage: khaki.lighter()
RGB color (0.9607843137254903, 0.934640522875817, 0.6993464052287582)
sage: Color('white').lighter().darker()
RGB color (0.6666666666666667, 0.6666666666666667, 0.6666666666666667)
sage: Color('#abcdef').lighter(1/4)
RGB color (0.7529411764705882, 0.8529411764705883, 0.9529411764705882)
sage: Color(1, 0, 8/9, space='hsv').lighter()
RGB color (0.925925925925926, 0.925925925925926, 0.925925925925926)

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.3, 0.5, 0.7)
sage: Color('#8000ff').rgb()
(0.5019607843137255, 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.9, 0.2700000000000001, 0.2700000000000001)

class sage.plot.colors.Colormaps

Bases: MutableMapping

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

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

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)>60
True
sage: 'viridis' in maps
True

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.check_color_data(cfcm)

Make sure that the arguments are in order (coloring function, colormap).

This will allow users to use both possible orders.

EXAMPLES:

sage: from sage.plot.colors import check_color_data
sage: cf = lambda x,y : (x+y) % 1
sage: cm = colormaps.autumn
sage: check_color_data((cf, cm)) == (cf, cm)
True
sage: check_color_data((cm, cf)) == (cf, cm)
True

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

Convert 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 real number; the RGB color’s “red” intensity

• g – a real number; the RGB color’s “green” intensity

• b – a real 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.plot.colors.float_to_integer(r, g, b)

Convert a Red-Green-Blue (RGB) color tuple to an integer.

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 real number; the RGB color’s “red” intensity

• g – a real number; the RGB color’s “green” intensity

• b – a real number; the RGB color’s “blue” intensity

OUTPUT:

• the integer \(256^2 r_int + 256 g_int + b_int\), where \(r_int\), \(g_int\), and \(b_int\) are obtained from \(r\), \(g\), and \(b\) by converting from the real interval [0.0, 1.0] to the integer range 0, 1, …, 255.

EXAMPLES:

sage: from sage.plot.colors import float_to_integer
sage: float_to_integer(1.,1.,0.)
16776960
sage: float_to_integer(.03,.06,.02)
462597
sage: float_to_integer(*Color('brown').rgb())
10824234

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', ...]

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 object at 0x...>
sage: get_cmap([(0,0,0), (0.5,0.5,0.5), (1,1,1)])
<matplotlib.colors.ListedColormap object at 0x...>
sage: get_cmap(['green', 'lightblue', 'blue'])
<matplotlib.colors.ListedColormap object 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 object at 0x...>
sage: get_cmap('jolies')
Traceback (most recent call last):
...
RuntimeError: Color map jolies not known (type "import matplotlib; list(matplotlib.colormaps.keys())" for valid names)
sage: get_cmap('mpl')
Traceback (most recent call last):
...
RuntimeError: Color map mpl not known (type "import matplotlib; list(matplotlib.colormaps.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.803921568627451, 0.9372549019607843)
sage: html_to_float('#123xyz')
Traceback (most recent call last):
...
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
Graphics object consisting of 20 graphics primitives

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.2549019607843137, 0.4117647058823529, 0.8823529411764706)
sage: hue(*royalblue.hsv())
(0.2549019607843137, 0.4117647058823529, 0.8823529411764706)
sage: hue(.5, .5, .5)
(0.25, 0.5, 0.5)

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(int(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.2857142857142858, 1.0, 0.0), (0.0, 1.0, 0.5714285714285712), (0.0, 0.5714285714285716, 1.0), (0.2857142857142856, 0.0, 1.0), (1.0, 0.0, 0.8571428571428577)]

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.4, 0.9)
sage: rgbcolor('purple')
(0.5019607843137255, 0.0, 0.5019607843137255)
sage: rgbcolor('#fa0')
(1.0, 0.6666666666666666, 0.0)
sage: rgbcolor('#ffffff')
(1.0, 1.0, 1.0)
sage: rgbcolor((1,1/2,1/3))
(1.0, 0.5, 0.3333333333333333)
sage: rgbcolor([1,1/2,1/3])
(1.0, 0.5, 0.3333333333333333)
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.9999999999999999, 1.0)
sage: rgbcolor((0.5,1.0,0.75), space='hsl')
(0.5, 0.9999999999999999, 1.0)
sage: rgbcolor([1,2,255])   # WARNING -- numbers are reduced mod 1!!
(1.0, 0.0, 0.0)
sage: rgbcolor('#abcd')
Traceback (most recent call last):
...
ValueError: color hex string (= 'abcd') must have length 3 or 6
sage: rgbcolor('fff')
Traceback (most recent call last):
...
ValueError: unknown color 'fff'
sage: rgbcolor(1)
Traceback (most recent call last):
...
TypeError: '1' must be a Color, list, tuple, or string
sage: rgbcolor((0.2,0.8,1), space='grassmann')
Traceback (most recent call last):
...
ValueError: space must be one of 'rgb', 'hsv', 'hsl', 'hls'
sage: rgbcolor([0.4, 0.1])
Traceback (most recent call last):
...
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.4, 0.9)
sage: rgbcolor('purple')
(0.5019607843137255, 0.0, 0.5019607843137255)
sage: rgbcolor('#fa0')
(1.0, 0.6666666666666666, 0.0)
sage: rgbcolor('#ffffff')
(1.0, 1.0, 1.0)
sage: rgbcolor((1,1/2,1/3))
(1.0, 0.5, 0.3333333333333333)
sage: rgbcolor([1,1/2,1/3])
(1.0, 0.5, 0.3333333333333333)
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.9999999999999999, 1.0)
sage: rgbcolor((0.5,1.0,0.75), space='hsl')
(0.5, 0.9999999999999999, 1.0)
sage: rgbcolor([1,2,255])   # WARNING -- numbers are reduced mod 1!!
(1.0, 0.0, 0.0)
sage: rgbcolor('#abcd')
Traceback (most recent call last):
...
ValueError: color hex string (= 'abcd') must have length 3 or 6
sage: rgbcolor('fff')
Traceback (most recent call last):
...
ValueError: unknown color 'fff'
sage: rgbcolor(1)
Traceback (most recent call last):
...
TypeError: '1' must be a Color, list, tuple, or string
sage: rgbcolor((0.2,0.8,1), space='grassmann')
Traceback (most recent call last):
...
ValueError: space must be one of 'rgb', 'hsv', 'hsl', 'hls'
sage: rgbcolor([0.4, 0.1])
Traceback (most recent call last):
...
ValueError: color list or tuple '[0.400000000000000, 0.100000000000000]' must have 3 entries, one for each RGB, HSV, HLS, or HSL channel