matplotlib.colors

The Color tutorials and examples demonstrate how to set colors and colormaps.

A module for converting numbers or color arguments to RGB or RGBA.

RGB and RGBA are sequences of, respectively, 3 or 4 floats in the range 0-1.

This module includes functions and classes for color specification conversions, and for mapping numbers to colors in a 1-D array of colors called a colormap.

Mapping data onto colors using a colormap typically involves two steps: a data array is first mapped onto the range 0-1 using a subclass of Normalize, then this number is mapped to a color using a subclass of Colormap. Two sublasses of Colormap provided here: LinearSegmentedColormap, which uses piecewise-linear interpolation to define colormaps, and ListedColormap, which makes a colormap from a list of colors.

See also

Creating Colormaps in Matplotlib for examples of how to make colormaps and

Choosing Colormaps in Matplotlib for a list of built-in colormaps.

Colormap Normalization for more details about data normalization

More colormaps are available at palettable.

The module also provides functions for checking whether an object can be interpreted as a color (is_color_like), for converting such an object to an RGBA tuple (to_rgba) or to an HTML-like hex string in the "#rrggbb" format (to_hex), and a sequence of colors to an (n, 4) RGBA array (to_rgba_array). Caching is used for efficiency.

Matplotlib recognizes the following formats to specify a color:

  • an RGB or RGBA (red, green, blue, alpha) tuple of float values in closed interval [0, 1] (e.g., (0.1, 0.2, 0.5) or (0.1, 0.2, 0.5, 0.3));
  • a hex RGB or RGBA string (e.g., '#0f0f0f' or '#0f0f0f80'; case-insensitive);
  • a shorthand hex RGB or RGBA string, equivalent to the hex RGB or RGBA string obtained by duplicating each character, (e.g., '#abc', equivalent to '#aabbcc', or '#abcd', equivalent to '#aabbccdd'; case-insensitive);
  • a string representation of a float value in [0, 1] inclusive for gray level (e.g., '0.5');
  • one of the characters {'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}, which are short-hand notations for shades of blue, green, red, cyan, magenta, yellow, black, and white. Note that the colors 'g', 'c', 'm', 'y' do not coincide with the X11/CSS4 colors. Their particular shades were chosen for better visibility of colored lines against typical backgrounds.
  • a X11/CSS4 color name (case-insensitive);
  • a name from the xkcd color survey, prefixed with 'xkcd:' (e.g., 'xkcd:sky blue'; case insensitive);
  • one of the Tableau Colors from the 'T10' categorical palette (the default color cycle): {'tab:blue', 'tab:orange', 'tab:green', 'tab:red', 'tab:purple', 'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'} (case-insensitive);
  • a "CN" color spec, i.e. 'C' followed by a number, which is an index into the default property cycle (rcParams["axes.prop_cycle"] (default: cycler('color', ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf']))); the indexing is intended to occur at rendering time, and defaults to black if the cycle does not include color.

Classes

BoundaryNorm(boundaries, ncolors[, clip, extend]) Generate a colormap index based on discrete intervals.
Colormap(name[, N]) Baseclass for all scalar to RGBA mappings.
DivergingNorm(**kwargs) [Deprecated]
LightSource([azdeg, altdeg, hsv_min_val, ...]) Create a light source coming from the specified azimuth and elevation.
LinearSegmentedColormap(name, segmentdata[, ...]) Colormap objects based on lookup tables using linear segments.
ListedColormap(colors[, name, N]) Colormap object generated from a list of colors.
LogNorm([vmin, vmax, clip]) Normalize a given value to the 0-1 range on a log scale.
NoNorm([vmin, vmax, clip]) Dummy replacement for Normalize, for the case where we want to use indices directly in a ScalarMappable.
Normalize([vmin, vmax, clip]) A class which, when called, linearly normalizes data into the [0.0, 1.0] interval.
PowerNorm(gamma[, vmin, vmax, clip]) Linearly map a given value to the 0-1 range and then apply a power-law normalization over that range.
SymLogNorm(linthresh[, linscale, vmin, ...]) The symmetrical logarithmic scale is logarithmic in both the positive and negative directions from the origin.
TwoSlopeNorm(vcenter[, vmin, vmax]) Normalize data with a set center.

Functions

from_levels_and_colors(levels, colors[, extend]) A helper routine to generate a cmap and a norm instance which behave similar to contourf's levels and colors arguments.
hsv_to_rgb(hsv) Convert hsv values to rgb.
rgb_to_hsv(arr) Convert float rgb values (in the range [0, 1]), in a numpy array to hsv values.
to_hex(c[, keep_alpha]) Convert c to a hex color.
to_rgb(c) Convert c to an RGB color, silently dropping the alpha channel.
to_rgba(c[, alpha]) Convert c to an RGBA color.
to_rgba_array(c[, alpha]) Convert c to a (n, 4) array of RGBA colors.
is_color_like(c) Return whether c can be interpreted as an RGB(A) color.
same_color(c1, c2) Return whether the colors c1 and c2 are the same.
makeMappingArray(N, data[, gamma]) [Deprecated] Create an N -element 1-d lookup table.
get_named_colors_mapping() Return the global mapping of names to named colors.