colorsdocs

Specifying colors.

Wherever a plot takes a color, it accepts any of several convenient spellings, and converts to a single internal representation. Wherever it takes the colors of a whole series, it accepts either one of those or an array holding one per point.

Types:

  • Color: The internal representation, an RGB triple of bytes.
  • ColorLike: Anything accepted in place of one---a named color, a hex string, or a triple of ints in 0 to 255 or floats in 0.0 to 1.0.
  • ColorSpec: Anything accepted for the colors of a series---one ColorLike for all of it, or an array with a color per point.

Conversion:

  • parse_color: Turn a ColorLike into a Color. See this function for the full list of accepted formats.
  • parse_colors: Turn a ColorSpec, scalar array, RGB array, or colormapped array into RGB bytes with requested leading dimensions.
  • NAMED_COLORS: The recognised color names.

Predefined functions for mapping data to colors live in matthewplotlib.colormaps and can be passed to parse_colors.

ColorLike = str | NDArray | tuple[int, int, int] | tuple[float, float, float] | Color : source docs

Anything accepted in place of a single color.

A named color or a hex string, an array or tuple of three integers from 0 to 255, or one of three floats from 0.0 to 1.0. parse_color standardises each of them, and documents the spellings it recognises.

parse_color(color: ColorLike | None) -> Color | None : source docs

Accept and standardise RGB triples in any of the following 'color like' formats:

  1. Named colours: The following strings are recognised and translated to RGB triples: "black", "red", "green", "blue", "cyan", "magenta", "yellow", "white".

  2. Hexadecimal: A hexadecimal string like "#ff0000" specifying the RGB values in the usual manner.

  3. Short hexadecimal: A three-character hexadecimal string like "#f00", where "#RGB" is equivalent to "#RRGGBB" in the usual hexadecimal format.

  4. Integer triple: An array or tuple of three integers in the range 0 to 255, converted directly to an RGB triple.

  5. Float triple: An array or tuple of three floats in the range 0.0 to 1.0, converted to an RGB triple by multiplying by 255 and rounding down to the nearest integer.

(Arrays or tuples with mixed integers and floats are promoted by NumPy to become float triples.)

parse_colors(spec: ColorSpec, n: int | None = None, *, shape: tuple[int | str | None, ...] | None = None, colormap: ColorMap | None = None) -> NDArray : source docs

Parse colour specifications or array data into an array of RGB bytes.

Exactly one output-shape specification is required:

  • n requests one colour for each of n points, preserving the original parse_colors(spec, n) interface.
  • shape describes any number of leading dimensions. An integer requires that exact size; None accepts any size and displays as * in errors; and a string such as "h" or "w" also accepts any size but retains that useful name in errors.

Without a colormap, an array matching the requested leading shape is read as scalar data and repeated over the three RGB channels. An array with an additional final axis of length three is read directly as RGB. A single ColorLike, or None for white, can instead be broadcast over a fully specified shape. In the n form, a three-element array remains one RGB colour rather than becoming three greyscale point colours.

If a colormap is supplied, the input array is passed to it without any shape interpretation. Its output must have the requested leading shape and a final RGB axis of length three. This permits a custom colormap to consume arbitrary array data, including feature vectors, provided it produces the requested colour array.

In every form, float channels are read in the range 0.0 to 1.0 and integer channels in the range 0 to 255. Values outside those ranges are clipped.