You are reading documentation for the unreleased version of Matplotlib. Try searching for the released version of this page instead?
Applications are open for the 2018 John Hunter Matplotlib Summer Fellowship. Apply now!
Version 2.2.2.post1762+g66a6d70bd
matplotlib
Fork me on GitHub

Table Of Contents

colors

For a visual representation of the Matplotlib colormaps, see:

  • The Color examples for examples of controlling color with Matplotlib.
  • The Colors tutorial for an in-depth guide on controlling color.

matplotlib.colors

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. Colormapping typically involves two steps: a data array is first mapped onto the range 0-1 using an instance of Normalize or of a subclass; then this number in the 0-1 range is mapped to a color using an instance of a subclass of Colormap. Two are provided here: LinearSegmentedColormap, which is used to generate all the built-in colormap instances, but is also useful for making custom colormaps, and ListedColormap, which is used for generating a custom colormap from a list of color specifications.

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 tuple of float values in [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 '#0F0F0F0F');
  • a string representation of a float value in [0, 1] inclusive for gray level (e.g., '0.5');
  • one of {'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'};
  • a X11/CSS4 color name;
  • a name from the xkcd color survey; prefixed with 'xkcd:' (e.g., 'xkcd:sky blue');
  • one of {'tab:blue', 'tab:orange', 'tab:green', 'tab:red', 'tab:purple', 'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'} which are the Tableau Colors from the 'T10' categorical palette (which is the default color cycle);
  • a "CN" color spec, i.e. 'C' followed by a single digit, which is an index into the default property cycle (matplotlib.rcParams['axes.prop_cycle']); the indexing occurs at artist creation time and defaults to black if the cycle does not include color.

All string specifications of color, other than "CN", are case-insensitive.

Classes

BoundaryNorm(boundaries, ncolors[, clip]) Generate a colormap index based on discrete intervals.
Colormap(name[, N]) Baseclass for all scalar to RGBA mappings.
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, can normalize 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.

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 in a numpy array to rgb values all values assumed to be in range [0, 1]
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.
makeMappingArray(N, data[, gamma]) Create an N -element 1-d lookup table
get_named_colors_mapping() Return the global mapping of names to named colors.