Skip to main content
`Ctrl`+`K`

# vispy.color package

## Subpackages

- vispy.color.tests package
  - Submodules
    - vispy.color.tests.test_color module
  - Module contents

## Submodules

- vispy.color.color_array module
  - `Color`
    - `Color.RGB`
    - `Color.RGBA`
    - `Color.alpha`
    - `Color.hex`
    - `Color.hsv`
    - `Color.is_blank`
    - `Color.lab`
    - `Color.rgb`
    - `Color.rgba`
    - `Color.value`
  - `ColorArray`
    - `ColorArray.RGB`
    - `ColorArray.RGBA`
    - `ColorArray.alpha`
    - `ColorArray.copy()`
    - `ColorArray.darker()`
    - `ColorArray.extend()`
    - `ColorArray.hex`
    - `ColorArray.hsv`
    - `ColorArray.lab`
    - `ColorArray.lighter()`
    - `ColorArray.rgb`
    - `ColorArray.rgba`
    - `ColorArray.value`
- vispy.color.color_space module
- vispy.color.colormap module
  - `BaseColormap`
    - `BaseColormap.bad_color`
    - `BaseColormap.colors`
    - `BaseColormap.glsl_map`
    - `BaseColormap.high_color`
    - `BaseColormap.low_color`
    - `BaseColormap.map()`
    - `BaseColormap.texture_lut()`
    - `BaseColormap.texture_map_data`
  - `Colormap`
    - `Colormap.interpolation`
    - `Colormap.map()`
    - `Colormap.texture_lut()`
  - `CubeHelixColormap`
  - `Diverging`
  - `HSL`
  - `HSLuv`
  - `MatplotlibColormap`
  - `RedYellowBlueCyan`
  - `SingleHue`
  - `get_colormap()`
  - `get_colormaps()`
  - `mix()`
  - `smoothstep()`
  - `step()`

## Module contents

Convience interfaces to manipulate colors.

This module provides support for manipulating colors.

class vispy.color.BaseColormap(colors=None, *, bad_color=None, low_color=None, high_color=None)

  Bases: `object`

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

    bad_color None | array-like

      The color mapping for NaN values.

    high_color None | array-like

      The color mapping for values greater than or equal to 1.

    low_color None | array-like

      The color mapping for values less than or equal to 0.

  Notes

  Must be overriden. Child classes need to implement:

  glsl_mapstring

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

  bad_color = None
  colors = None
  glsl_map = None
  high_color = None
  low_color = None
  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).

  texture_lut()

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

  texture_map_data = None

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

  Bases: `ColorArray`

  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.

  property RGB

    Nx3 array of RGBA uint8s

  property RGBA

    Nx4 array of RGBA uint8s

  property alpha

    Length-N array of alpha floats

  property hex

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

  property hsv

    Nx3 array of HSV floats

  property is_blank

    Boolean indicating whether the color is invisible.

  property lab
  property rgb

    Nx3 array of RGB floats

  property rgba

    Nx4 array of RGBA floats

  property 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')

  Bases: `object`

  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

  property RGB

    Nx3 array of RGBA uint8s

  property RGBA

    Nx4 array of RGBA uint8s

  property 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.

  property hex

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

  property hsv

    Nx3 array of HSV floats

  property lab
  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.

  property rgb

    Nx3 array of RGB floats

  property rgba

    Nx4 array of RGBA floats

  property value

    Length-N array of color HSV values

class vispy.color.Colormap(colors, controls=None, interpolation='linear', *, bad_color=None, low_color=None, high_color=None)

  Bases: `BaseColormap`

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

    bad_color None | array-like

      The color mapping for NaN values.

    high_color None | array-like

      The color mapping for values greater than or equal to 1.

    low_color None | array-like

      The color mapping for values less than or equal to 0.

  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)]

  property 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. Can be None.

vispy.color.get_color_dict()

  Get the known colors

  Returns:
    color_dict dict

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

vispy.color.get_color_names()

  Get the known color names

  Returns:
    names list

      List of color names known by Vispy.

vispy.color.get_colormap(name)

  Obtain a colormap by name.

  Parameters:
    name str | Colormap

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

  Examples

      >>> get_colormap('autumn')
      >>> get_colormap('single_hue')

vispy.color.get_colormaps()

  Return the list of colormap names.