# The color module

Convience interfaces to manipulate colors.

This module provides support for manipulating colors.

class `vispy.color.``Color`(color='black', alpha=None, clip=False)

  A single color

  Parameters:

  color : str | tuple

  > If str, can be any of the names in `vispy.color.get_color_names`. Can also be a hex value if it starts with `'#'` as `'#ff0000'`. If array-like, it must be an 1-dimensional array with 3 or 4 elements.

  alpha : float | None

  > If no alpha is not supplied in `color` entry and `alpha` is None, then this will default to 1.0 (opaque). If float, it will override the alpha value in `color`, if provided.

  clip : bool

  > If True, clip the color values.

  `RGB`

    Nx3 array of RGBA uint8s

  `RGBA`

    Nx4 array of RGBA uint8s

  `alpha`

    Length-N array of alpha floats

  `hex`

    Numpy array with N elements, each one a hex triplet string

  `hsv`

    Nx3 array of HSV floats

  `is_blank`

    Boolean indicating whether the color is invisible.

  `rgb`

    Nx3 array of RGB floats

  `rgba`

    Nx4 array of RGBA floats

  `value`

    Length-N array of color HSV values

class `vispy.color.``ColorArray`(color=(0.0, 0.0, 0.0), alpha=None, clip=False, color_space='rgb')

  An array of colors

  Parameters:

  color : str | tuple | list of colors

  > If str, can be any of the names in `vispy.color.get_color_names`. Can also be a hex value if it starts with `'#'` as `'#ff0000'`. If array-like, it must be an Nx3 or Nx4 array-like object. Can also be a list of colors, such as `['red', '#00ff00', ColorArray('blue')]`.

  alpha : float | None

  > If no alpha is not supplied in `color` entry and `alpha` is None, then this will default to 1.0 (opaque). If float, it will override any alpha values in `color`, if provided.

  clip : bool

  > Clip the color value.

  color_space : ‘rgb’ | ‘hsv’

  > ‘rgb’ (default) : color tuples are interpreted as (r, g, b) components. ‘hsv’ : color tuples are interpreted as (h, s, v) components.

  Notes

  Under the hood, this class stores data in RGBA format suitable for use on the GPU.

  Examples

  There are many ways to define colors. Here are some basic cases:

      >>> from vispy.color import ColorArray
      >>> r = ColorArray('red')  # using string name
      >>> r
      <ColorArray: 1 color ((1.0, 0.0, 0.0, 1.0))>
      >>> g = ColorArray((0, 1, 0, 1))  # RGBA tuple
      >>> b = ColorArray('#0000ff')  # hex color
      >>> w = ColorArray()  # defaults to black
      >>> w.rgb = r.rgb + g.rgb + b.rgb
      >>>hsv_color = ColorArray(color_space="hsv", color=(0, 0, 0.5))
      >>>hsv_color
      <ColorArray: 1 color ((0.5, 0.5, 0.5, 1.0))>
      >>> w == ColorArray('white')
      True
      >>> w.alpha = 0
      >>> w
      <ColorArray: 1 color ((1.0, 1.0, 1.0, 0.0))>
      >>> rgb = ColorArray(['r', (0, 1, 0), '#0000FFFF'])
      >>> rgb
      <ColorArray: 3 colors ((1.0, 0.0, 0.0, 1.0) ... (1.0, 0.0, 0.0, 1.0))>
      >>> rgb == ColorArray(['red', '#00ff00', ColorArray('blue')])
      True

  `RGB`

    Nx3 array of RGBA uint8s

  `RGBA`

    Nx4 array of RGBA uint8s

  `alpha`

    Length-N array of alpha floats

  `copy`()

    Return a copy

  `darker`(dv=0.1, copy=True)

    Produce a darker color (if possible)

    Parameters:

    dv : float

    > Amount to decrease the color value by.

    copy : bool

    > If False, operation will be carried out in-place.

    Returns:

    color : instance of ColorArray

    > The darkened Color.

  `extend`(colors)

    Extend a ColorArray with new colors

    Parameters:

    colors : instance of ColorArray

    > The new colors.

  `hex`

    Numpy array with N elements, each one a hex triplet string

  `hsv`

    Nx3 array of HSV floats

  `lighter`(dv=0.1, copy=True)

    Produce a lighter color (if possible)

    Parameters:

    dv : float

    > Amount to increase the color value by.

    copy : bool

    > If False, operation will be carried out in-place.

    Returns:

    color : instance of ColorArray

    > The lightened Color.

  `rgb`

    Nx3 array of RGB floats

  `rgba`

    Nx4 array of RGBA floats

  `value`

    Length-N array of color HSV values

class `vispy.color.``Colormap`(colors, controls=None, interpolation='linear')

  A colormap defining several control colors and an interpolation scheme.

  Parameters:

  colors : list of colors | ColorArray

  > The list of control colors. If not a `ColorArray`, a new `ColorArray` instance is created from this list. See the documentation of `ColorArray`.

  controls : array-like

  > The list of control points for the given colors. It should be an increasing list of floating-point number between 0.0 and 1.0. The first control point must be 0.0. The last control point must be 1.0. The number of control points depends on the interpolation scheme.

  interpolation : str

  > The interpolation mode of the colormap. Default: ‘linear’. Can also be ‘zero’. If ‘linear’, ncontrols = ncolors (one color per control point). If ‘zero’, ncontrols = ncolors+1 (one color per bin).

  Examples

  Here is a basic example:

      >>> from vispy.color import Colormap
      >>> cm = Colormap(['r', 'g', 'b'])
      >>> cm[0.], cm[0.5], cm[np.linspace(0., 1., 100)]

  `interpolation`

    The interpolation mode of the colormap

  `map`(x)

    The Python mapping function from the [0,1] interval to a list of rgba colors

    Parameters:

    x : array-like

    > The values to map.

    Returns:

    colors : list

    > List of rgba colors.

  `texture_lut`()

    Return a texture2D object for LUT after its value is set.

class `vispy.color.``BaseColormap`(colors=None)

  Class representing a colormap:

  > t in [0, 1] –> rgba_color

  Parameters:

  colors : list of lists, tuples, or ndarrays

  > The control colors used by the colormap (shape = (ncolors, 4)).

  Notes

  Must be overriden. Child classes need to implement:

  glsl_map : string
    The GLSL function for the colormap. Use $color_0 to refer to the first color in colors, and so on. These are vec4 vectors.
  map(item) : function
    Takes a (N, 1) vector of values in [0, 1], and returns a rgba array of size (N, 4).
  `map`(item)

    Return a rgba array for the requested items.

    This function must be overriden by child classes.

    This function doesn’t need to implement argument checking on item. It can always assume that item is a (N, 1) array of values between 0 and 1.

    Parameters:

    item : ndarray

    > An array of values in [0,1].

    Returns:

    rgba : ndarray

    > An array with rgba values, with one color per item. The shape should be `item.shape + (4,)`.

    Notes

    Users are expected to use a colormap with `__getitem__()` rather than `map()` (which implements a lower-level API).

`vispy.color.``get_colormap`(name, *args, **kwargs)

  Obtain a colormap

  Some colormaps can have additional configuration parameters. Refer to their corresponding documentation for more information.

  Parameters:

  name : str | Colormap

  > Colormap name. Can also be a Colormap for pass-through.

  Examples

      >>> get_colormap('autumn')
      >>> get_colormap('single_hue', hue=10)

`vispy.color.``get_colormaps`()

  Return the list of colormap names.

`vispy.color.``get_color_names`()

  Get the known color names

  Returns:

  names : list

  > List of color names known by Vispy.

`vispy.color.``get_color_dict`()

  Get the known colors

  Returns:

  color_dict : dict

  > Dict of colors known by Vispy {name: #rgb}.