### Navigation

- index
- modules |
- next |
- previous |
- 2D Graphics »

# 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', '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`

  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.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.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()
        (0.30000000000000004, 0.7, 0.5000000000000001)
        sage: Color('#aabbcc').hls()
        (0.5833333333333334, 0.7333333333333334, 0.25000000000000017)
        sage: from sage.plot.colors import orchid
        sage: orchid.hls()
        (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()
        (0.8396226415094339, 0.5888888888888889, 0.6470588235294117)
        sage: Color('#aabbcc').hsl()
        (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.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.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: `_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)>130
        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.``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))
      Traceback (most recent call last):
      ...
      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 object at 0x...>
      sage: get_cmap(u'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.cm; matplotlib.cm.datad.keys() for valid names)
      sage: get_cmap('mpl')
      Traceback (most recent call last):
      ...
      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.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(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(u'purple')
      (0.5019607843137255, 0.0, 0.5019607843137255)
      sage: rgbcolor('#fa0')
      (1.0, 0.6666666666666666, 0.0)
      sage: rgbcolor(u'#fa0')
      (1.0, 0.6666666666666666, 0.0)
      sage: rgbcolor('#ffffff')
      (1.0, 1.0, 1.0)
      sage: rgbcolor(u'#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(u'purple')
      (0.5019607843137255, 0.0, 0.5019607843137255)
      sage: rgbcolor('#fa0')
      (1.0, 0.6666666666666666, 0.0)
      sage: rgbcolor(u'#fa0')
      (1.0, 0.6666666666666666, 0.0)
      sage: rgbcolor('#ffffff')
      (1.0, 1.0, 1.0)
      sage: rgbcolor(u'#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

### Navigation

- index
- modules |
- next |
- previous |
- 2D Graphics »