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.

Methods

copy() Return a copy
darker([dv, copy]) Produce a darker color (if possible)
extend(colors) Extend a ColorArray with new colors
lighter([dv, copy]) Produce a lighter color (if possible)
is_blank

Boolean indicating whether the color is invisible.

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

Methods

copy() Return a copy
darker([dv, copy]) Produce a darker color (if possible)
extend(colors) Extend a ColorArray with new colors
lighter([dv, copy]) Produce a lighter color (if possible)
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)]

Attributes

colors
glsl_map

Methods

map(x) The Python mapping function from the [0,1] interval to a
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.

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

Attributes

colors
glsl_map

Methods

map(item) Return a rgba array for the requested items.
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}.