"""

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

:class:`Normalize`, then this number is mapped to a color using

a subclass of :class:`Colormap`. Two are provided here:

:class:`LinearSegmentedColormap`, which uses piecewise-linear interpolation

to define colormaps, and :class:`ListedColormap`, which makes a colormap

from a list of colors.

.. seealso::

:doc:`/tutorials/colors/colormap-manipulation` for examples of how to

make colormaps and

:doc:`/tutorials/colors/colormaps` for a list of built-in colormaps.

:doc:`/tutorials/colors/colormapnorms` 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 (:func:`is_color_like`), for converting such an object

to an RGBA tuple (:func:`to_rgba`) or to an HTML-like hex string in the

`#rrggbb` format (:func:`to_hex`), and a sequence of colors to an `(n, 4)`

RGBA array (:func:`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 ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``, they are the single

character short-hand notations for blue, green, red, cyan, magenta, yellow,

black, and white.

* 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 (``matplotlib.rcParams['axes.prop_cycle']``); the

indexing is intended to occur at rendering time, and defaults to black if the

cycle does not include color.

.. _palettable: https://jiffyclub.github.io/palettable/

.. _xkcd color survey: https://xkcd.com/color/rgb/

"""

from collections.abc import Sized

import functools

import itertools

import re

import numpy as np

import matplotlib.cbook as cbook

from matplotlib import docstring

from ._color_data import BASE_COLORS, TABLEAU_COLORS, CSS4_COLORS, XKCD_COLORS

class _ColorMapping(dict):

def __init__(self, mapping):

super().__init__(mapping)

self.cache = {}

def __setitem__(self, key, value):

super().__setitem__(key, value)

self.cache.clear()

def __delitem__(self, key):

super().__delitem__(key)

self.cache.clear()

_colors_full_map = {}

# Set by reverse priority order.

_colors_full_map.update(XKCD_COLORS)

_colors_full_map.update({k.replace('grey', 'gray'): v

for k, v in XKCD_COLORS.items()

if 'grey' in k})

_colors_full_map.update(CSS4_COLORS)

_colors_full_map.update(TABLEAU_COLORS)

_colors_full_map.update({k.replace('gray', 'grey'): v

for k, v in TABLEAU_COLORS.items()

if 'gray' in k})

_colors_full_map.update(BASE_COLORS)

_colors_full_map = _ColorMapping(_colors_full_map)

def get_named_colors_mapping():

"""Return the global mapping of names to named colors."""

return _colors_full_map

def _sanitize_extrema(ex):

if ex is None:

return ex

try:

ret = ex.item()

except AttributeError:

ret = float(ex)

return ret

def _is_nth_color(c):

"""Return whether *c* can be interpreted as an item in the color cycle."""

return isinstance(c, str) and re.match(r"\AC[0-9]+\Z", c)

def is_color_like(c):

"""Return whether *c* can be interpreted as an RGB(A) color."""

# Special-case nth color syntax because it cannot be parsed during setup.

if _is_nth_color(c):

return True

try:

to_rgba(c)

except ValueError:

return False

else:

return True

def same_color(c1, c2):

"""

Compare two colors to see if they are the same.

Parameters

----------

c1, c2 : Matplotlib colors

Returns

-------

bool

``True`` if *c1* and *c2* are the same color, otherwise ``False``.

"""

return (to_rgba_array(c1) == to_rgba_array(c2)).all()

def to_rgba(c, alpha=None):

"""

Convert *c* to an RGBA color.

Parameters

----------

c : Matplotlib color or ``np.ma.masked``

alpha : scalar, optional

If *alpha* is not ``None``, it forces the alpha value, except if *c* is

``"none"`` (case-insensitive), which always maps to ``(0, 0, 0, 0)``.

Returns

-------

tuple

Tuple of ``(r, g, b, a)`` scalars.

"""

# Special-case nth color syntax because it should not be cached.

if _is_nth_color(c):

from matplotlib import rcParams

prop_cycler = rcParams['axes.prop_cycle']

colors = prop_cycler.by_key().get('color', ['k'])

c = colors[int(c[1:]) % len(colors)]

try:

rgba = _colors_full_map.cache[c, alpha]

except (KeyError, TypeError): # Not in cache, or unhashable.

rgba = None

if rgba is None: # Suppress exception chaining of cache lookup failure.

rgba = _to_rgba_no_colorcycle(c, alpha)

try:

_colors_full_map.cache[c, alpha] = rgba

except TypeError:

pass

return rgba

def _to_rgba_no_colorcycle(c, alpha=None):

"""Convert *c* to an RGBA color, with no support for color-cycle syntax.

If *alpha* is not ``None``, it forces the alpha value, except if *c* is

``"none"`` (case-insensitive), which always maps to ``(0, 0, 0, 0)``.

"""

orig_c = c

if c is np.ma.masked:

return (0., 0., 0., 0.)

if isinstance(c, str):

if c.lower() == "none":

return (0., 0., 0., 0.)

# Named color.

try:

# This may turn c into a non-string, so we check again below.

c = _colors_full_map[c]

except KeyError:

try:

c = _colors_full_map[c.lower()]

except KeyError:

pass

else:

if len(orig_c) == 1:

cbook.warn_deprecated(

"3.1", message="Support for uppercase "

"single-letter colors is deprecated since Matplotlib "

"%(since)s and will be removed %(removal)s; please "

"use lowercase instead.")

if isinstance(c, str):

# hex color in #rrggbb format.

match = re.match(r"\A#[a-fA-F0-9]{6}\Z", c)

if match:

return (tuple(int(n, 16) / 255

for n in [c[1:3], c[3:5], c[5:7]])

+ (alpha if alpha is not None else 1.,))

# hex color in #rgb format, shorthand for #rrggbb.

match = re.match(r"\A#[a-fA-F0-9]{3}\Z", c)

if match:

return (tuple(int(n, 16) / 255

for n in [c[1]*2, c[2]*2, c[3]*2])

+ (alpha if alpha is not None else 1.,))

# hex color with alpha in #rrggbbaa format.

match = re.match(r"\A#[a-fA-F0-9]{8}\Z", c)

if match:

color = [int(n, 16) / 255

for n in [c[1:3], c[3:5], c[5:7], c[7:9]]]

if alpha is not None:

color[-1] = alpha

return tuple(color)

# hex color with alpha in #rgba format, shorthand for #rrggbbaa.

match = re.match(r"\A#[a-fA-F0-9]{4}\Z", c)

if match:

color = [int(n, 16) / 255

for n in [c[1]*2, c[2]*2, c[3]*2, c[4]*2]]

if alpha is not None:

color[-1] = alpha

return tuple(color)

# string gray.

try:

c = float(c)

except ValueError:

pass

else:

if not (0 <= c <= 1):

raise ValueError(

f"Invalid string grayscale value {orig_c!r}. "

f"Value must be within 0-1 range")

return c, c, c, alpha if alpha is not None else 1.

raise ValueError(f"Invalid RGBA argument: {orig_c!r}")

# tuple color.

c = np.array(c)

if not np.can_cast(c.dtype, float, "same_kind") or c.ndim != 1:

# Test the dtype explicitly as `map(float, ...)`, `np.array(...,

# float)` and `np.array(...).astype(float)` all convert "0.5" to 0.5.

# Test dimensionality to reject single floats.

raise ValueError(f"Invalid RGBA argument: {orig_c!r}")

# Return a tuple to prevent the cached value from being modified.

c = tuple(c.astype(float))

if len(c) not in [3, 4]:

raise ValueError("RGBA sequence should have length 3 or 4")

if len(c) == 3 and alpha is None:

alpha = 1

if alpha is not None:

c = c[:3] + (alpha,)

if any(elem < 0 or elem > 1 for elem in c):

raise ValueError("RGBA values should be within 0-1 range")

return c

def to_rgba_array(c, alpha=None):

"""Convert *c* to a (n, 4) array of RGBA colors.

If *alpha* is not ``None``, it forces the alpha value. If *c* is

``"none"`` (case-insensitive) or an empty list, an empty array is returned.

If *c* is a masked array, an ndarray is returned with a (0, 0, 0, 0)

row for each masked value or row in *c*.

"""

# Special-case inputs that are already arrays, for performance. (If the

# array has the wrong kind or shape, raise the error during one-at-a-time

# conversion.)

if (isinstance(c, np.ndarray) and c.dtype.kind in "if"

and c.ndim == 2 and c.shape[1] in [3, 4]):

mask = c.mask.any(axis=1) if np.ma.is_masked(c) else None

c = np.ma.getdata(c)

if c.shape[1] == 3:

result = np.column_stack([c, np.zeros(len(c))])

result[:, -1] = alpha if alpha is not None else 1.

elif c.shape[1] == 4:

result = c.copy()

if alpha is not None:

result[:, -1] = alpha

if mask is not None:

result[mask] = 0

if np.any((result < 0) | (result > 1)):

raise ValueError("RGBA values should be within 0-1 range")

return result

# Handle single values.

# Note that this occurs *after* handling inputs that are already arrays, as

# `to_rgba(c, alpha)` (below) is expensive for such inputs, due to the need

# to format the array in the ValueError message(!).

if cbook._str_lower_equal(c, "none"):

return np.zeros((0, 4), float)

try:

return np.array([to_rgba(c, alpha)], float)

except (ValueError, TypeError):

pass

# Convert one at a time.

if isinstance(c, str):

# Single string as color sequence.

# This is deprecated and will be removed in the future.

try:

result = np.array([to_rgba(cc, alpha) for cc in c])

except ValueError:

raise ValueError(

"'%s' is neither a valid single color nor a color sequence "

"consisting of single character color specifiers such as "

"'rgb'. Note also that the latter is deprecated." % c)

else:

cbook.warn_deprecated("3.2", message="Using a string of single "

"character colors as a color sequence is "

"deprecated. Use an explicit list instead.")

return result

if len(c) == 0:

return np.zeros((0, 4), float)

else:

return np.array([to_rgba(cc, alpha) for cc in c])

def to_rgb(c):

"""Convert *c* to an RGB color, silently dropping the alpha channel."""

return to_rgba(c)[:3]

def to_hex(c, keep_alpha=False):

"""

Convert *c* to a hex color.

Uses the ``#rrggbb`` format if *keep_alpha* is False (the default),

``#rrggbbaa`` otherwise.

"""

c = to_rgba(c)

if not keep_alpha:

c = c[:3]

return "#" + "".join(format(int(round(val * 255)), "02x") for val in c)

### Backwards-compatible color-conversion API

cnames = CSS4_COLORS

hexColorPattern = re.compile(r"\A#[a-fA-F0-9]{6}\Z")

rgb2hex = to_hex

hex2color = to_rgb

class ColorConverter:

"""

This class is only kept for backwards compatibility.

Its functionality is entirely provided by module-level functions.

"""

colors = _colors_full_map

cache = _colors_full_map.cache

to_rgb = staticmethod(to_rgb)

to_rgba = staticmethod(to_rgba)

to_rgba_array = staticmethod(to_rgba_array)

colorConverter = ColorConverter()

### End of backwards-compatible color-conversion API

def _create_lookup_table(N, data, gamma=1.0):

r"""Create an *N* -element 1-d lookup table.

This assumes a mapping :math:`f : [0, 1] \rightarrow [0, 1]`. The returned

data is an array of N values :math:`y = f(x)` where x is sampled from

[0, 1].

By default (*gamma* = 1) x is equidistantly sampled from [0, 1]. The

*gamma* correction factor :math:`\gamma` distorts this equidistant

sampling by :math:`x \rightarrow x^\gamma`.

Parameters

----------

N : int

The number of elements of the created lookup table.

This must be N >= 1.

data : Mx3 array-like or callable

Defines the mapping :math:`f`.

If a Mx3 array-like, the rows define values (x, y0, y1). The x values

must start with x=0, end with x=1, and all x values be in increasing

order.

A value between :math:`x_i` and :math:`x_{i+1}` is mapped to the range

:math:`y^1_{i-1} \ldots y^0_i` by linear interpolation.

For the simple case of a y-continuous mapping, y0 and y1 are identical.

The two values of y are to allow for discontinuous mapping functions.

E.g. a sawtooth with a period of 0.2 and an amplitude of 1 would be::

[(0, 1, 0), (0.2, 1, 0), (0.4, 1, 0), ..., [(1, 1, 0)]

In the special case of ``N == 1``, by convention the returned value

is y0 for x == 1.

If *data* is a callable, it must accept and return numpy arrays::

data(x : ndarray) -> ndarray

and map values between 0 - 1 to 0 - 1.

gamma : float

Gamma correction factor for input distribution x of the mapping.

See also https://en.wikipedia.org/wiki/Gamma_correction.

Returns

-------

lut : array

The lookup table where ``lut[x * (N-1)]`` gives the closest value

for values of x between 0 and 1.

Notes

-----

This function is internally used for `.LinearSegmentedColormaps`.

"""

if callable(data):

xind = np.linspace(0, 1, N) ** gamma

lut = np.clip(np.array(data(xind), dtype=float), 0, 1)

return lut

try:

adata = np.array(data)

except Exception:

raise TypeError("data must be convertible to an array")

shape = adata.shape

if len(shape) != 2 or shape[1] != 3:

raise ValueError("data must be nx3 format")

x = adata[:, 0]

y0 = adata[:, 1]

y1 = adata[:, 2]

if x[0] != 0. or x[-1] != 1.0:

raise ValueError(

"data mapping points must start with x=0 and end with x=1")

if (np.diff(x) < 0).any():

raise ValueError("data mapping points must have x in increasing order")

# begin generation of lookup table

if N == 1:

# convention: use the y = f(x=1) value for a 1-element lookup table

lut = np.array(y0[-1])

else:

x = x * (N - 1)

xind = (N - 1) * np.linspace(0, 1, N) ** gamma

ind = np.searchsorted(x, xind)[1:-1]

distance = (xind[1:-1] - x[ind - 1]) / (x[ind] - x[ind - 1])

lut = np.concatenate([

[y1[0]],

distance * (y0[ind] - y1[ind - 1]) + y1[ind - 1],

[y0[-1]],

])

# ensure that the lut is confined to values between 0 and 1 by clipping it

return np.clip(lut, 0.0, 1.0)

@cbook.deprecated("3.2",

addendum='This is not considered public API any longer.')

@docstring.copy(_create_lookup_table)

def makeMappingArray(N, data, gamma=1.0):

return _create_lookup_table(N, data, gamma)

class Colormap:

"""

Baseclass for all scalar to RGBA mappings.

Typically Colormap instances are used to convert data values (floats) from

the interval ``[0, 1]`` to the RGBA color that the respective Colormap

represents. For scaling of data into the ``[0, 1]`` interval see

:class:`matplotlib.colors.Normalize`. It is worth noting that

:class:`matplotlib.cm.ScalarMappable` subclasses make heavy use of this

``data->normalize->map-to-color`` processing chain.

"""

def __init__(self, name, N=256):

"""

Parameters

----------

name : str

The name of the colormap.

N : int

The number of rgb quantization levels.

"""

self.name = name

self.N = int(N) # ensure that N is always int

self._rgba_bad = (0.0, 0.0, 0.0, 0.0) # If bad, don't paint anything.

self._rgba_under = None

self._rgba_over = None

self._i_under = self.N

self._i_over = self.N + 1

self._i_bad = self.N + 2

self._isinit = False

#: When this colormap exists on a scalar mappable and colorbar_extend

#: is not False, colorbar creation will pick up ``colorbar_extend`` as

#: the default value for the ``extend`` keyword in the

#: :class:`matplotlib.colorbar.Colorbar` constructor.

self.colorbar_extend = False

def __call__(self, X, alpha=None, bytes=False):

"""

Parameters

----------

X : scalar, ndarray

The data value(s) to convert to RGBA.

For floats, X should be in the interval ``[0.0, 1.0]`` to

return the RGBA values ``X*100`` percent along the Colormap line.

For integers, X should be in the interval ``[0, Colormap.N)`` to

return RGBA values *indexed* from the Colormap with index ``X``.

alpha : float, None

Alpha must be a scalar between 0 and 1, or None.

bytes : bool

If False (default), the returned RGBA values will be floats in the

interval ``[0, 1]`` otherwise they will be uint8s in the interval

``[0, 255]``.

Returns

-------

Tuple of RGBA values if X is scalar, otherwise an array of

RGBA values with a shape of ``X.shape + (4, )``.

"""

# See class docstring for arg/kwarg documentation.

if not self._isinit:

self._init()

mask_bad = None

if np.ma.is_masked(X):

mask_bad = X.mask

elif np.any(np.isnan(X)):

# mask nan's

mask_bad = np.isnan(X)

xa = np.array(X, copy=True)

# Fill bad values to avoid warnings

# in the boolean comparisons below.

if mask_bad is not None:

xa[mask_bad] = 0.

# Calculations with native byteorder are faster, and avoid a

# bug that otherwise can occur with putmask when the last

# argument is a numpy scalar.

if not xa.dtype.isnative:

xa = xa.byteswap().newbyteorder()

if xa.dtype.kind == "f":

xa *= self.N

# Negative values are out of range, but astype(int) would truncate

# them towards zero.

xa[xa < 0] = -1

# xa == 1 (== N after multiplication) is not out of range.

xa[xa == self.N] = self.N - 1

# Avoid converting large positive values to negative integers.

np.clip(xa, -1, self.N, out=xa)

xa = xa.astype(int)

# Set the over-range indices before the under-range;

# otherwise the under-range values get converted to over-range.

xa[xa > self.N - 1] = self._i_over

xa[xa < 0] = self._i_under

if mask_bad is not None:

xa[mask_bad] = self._i_bad

if bytes:

lut = (self._lut * 255).astype(np.uint8)

else:

lut = self._lut.copy() # Don't let alpha modify original _lut.

if alpha is not None:

alpha = np.clip(alpha, 0, 1)

if bytes:

alpha = int(alpha * 255)

if (lut[-1] == 0).all():

lut[:-1, -1] = alpha

# All zeros is taken as a flag for the default bad

# color, which is no color--fully transparent. We

# don't want to override this.

else:

lut[:, -1] = alpha

# If the bad value is set to have a color, then we

# override its alpha just as for any other value.

rgba = lut.take(xa, axis=0, mode='clip')

if not np.iterable(X):

# Return a tuple if the input was a scalar

rgba = tuple(rgba)

return rgba

def __copy__(self):

"""Create new object with the same class, update attributes

"""

cls = self.__class__

cmapobject = cls.__new__(cls)

cmapobject.__dict__.update(self.__dict__)

if self._isinit:

cmapobject._lut = np.copy(self._lut)

return cmapobject

def set_bad(self, color='k', alpha=None):

"""Set color to be used for masked values.

"""

self._rgba_bad = to_rgba(color, alpha)

if self._isinit:

self._set_extremes()

def set_under(self, color='k', alpha=None):

"""

Set the color for low out-of-range values when ``norm.clip = False``.

"""

self._rgba_under = to_rgba(color, alpha)

if self._isinit:

self._set_extremes()

def set_over(self, color='k', alpha=None):

"""

Set the color for high out-of-range values when ``norm.clip = False``.

"""

self._rgba_over = to_rgba(color, alpha)

if self._isinit:

self._set_extremes()

def _set_extremes(self):

if self._rgba_under:

self._lut[self._i_under] = self._rgba_under

else:

self._lut[self._i_under] = self._lut[0]

if self._rgba_over:

self._lut[self._i_over] = self._rgba_over

else:

self._lut[self._i_over] = self._lut[self.N - 1]

self._lut[self._i_bad] = self._rgba_bad

def _init(self):

"""Generate the lookup table, self._lut"""

raise NotImplementedError("Abstract class only")

def is_gray(self):

if not self._isinit:

self._init()

return (np.all(self._lut[:, 0] == self._lut[:, 1]) and

np.all(self._lut[:, 0] == self._lut[:, 2]))

def _resample(self, lutsize):

"""

Return a new color map with *lutsize* entries.

"""

raise NotImplementedError()

def reversed(self, name=None):

"""

Make a reversed instance of the Colormap.

.. note:: Function not implemented for base class.

Parameters

----------

name : str, optional

The name for the reversed colormap. If it's None the

name will be the name of the parent colormap + "_r".

See Also

--------

LinearSegmentedColormap.reversed

ListedColormap.reversed

"""

raise NotImplementedError()

class LinearSegmentedColormap(Colormap):

"""

Colormap objects based on lookup tables using linear segments.

The lookup table is generated using linear interpolation for each

primary color, with the 0-1 domain divided into any number of

segments.

"""

def __init__(self, name, segmentdata, N=256, gamma=1.0):

"""

Create color map from linear mapping segments

segmentdata argument is a dictionary with a red, green and blue

entries. Each entry should be a list of *x*, *y0*, *y1* tuples,

forming rows in a table. Entries for alpha are optional.

Example: suppose you want red to increase from 0 to 1 over

the bottom half, green to do the same over the middle half,

and blue over the top half. Then you would use::

cdict = {'red': [(0.0, 0.0, 0.0),

(0.5, 1.0, 1.0),

(1.0, 1.0, 1.0)],

'green': [(0.0, 0.0, 0.0),

(0.25, 0.0, 0.0),

(0.75, 1.0, 1.0),

(1.0, 1.0, 1.0)],

'blue': [(0.0, 0.0, 0.0),

(0.5, 0.0, 0.0),

(1.0, 1.0, 1.0)]}

Each row in the table for a given color is a sequence of

*x*, *y0*, *y1* tuples. In each sequence, *x* must increase

monotonically from 0 to 1. For any input value *z* falling

between *x[i]* and *x[i+1]*, the output value of a given color

will be linearly interpolated between *y1[i]* and *y0[i+1]*::

row i: x y0 y1

/

/

row i+1: x y0 y1

Hence y0 in the first row and y1 in the last row are never used.

See Also

--------

LinearSegmentedColormap.from_list

Static method; factory function for generating a smoothly-varying

LinearSegmentedColormap.

makeMappingArray

For information about making a mapping array.

"""

# True only if all colors in map are identical; needed for contouring.

self.monochrome = False

Colormap.__init__(self, name, N)

self._segmentdata = segmentdata

self._gamma = gamma

def _init(self):

self._lut = np.ones((self.N + 3, 4), float)

self._lut[:-3, 0] = _create_lookup_table(

self.N, self._segmentdata['red'], self._gamma)

self._lut[:-3, 1] = _create_lookup_table(

self.N, self._segmentdata['green'], self._gamma)

self._lut[:-3, 2] = _create_lookup_table(

self.N, self._segmentdata['blue'], self._gamma)

if 'alpha' in self._segmentdata:

self._lut[:-3, 3] = _create_lookup_table(

self.N, self._segmentdata['alpha'], 1)

self._isinit = True

self._set_extremes()

def set_gamma(self, gamma):

"""

Set a new gamma value and regenerate color map.

"""

self._gamma = gamma

self._init()

@staticmethod

def from_list(name, colors, N=256, gamma=1.0):

"""

Make a linear segmented colormap with *name* from a sequence

of *colors* which evenly transitions from colors[0] at val=0

to colors[-1] at val=1. *N* is the number of rgb quantization

levels.

Alternatively, a list of (value, color) tuples can be given

to divide the range unevenly.

"""

if not np.iterable(colors):

raise ValueError('colors must be iterable')

if (isinstance(colors[0], Sized) and len(colors[0]) == 2

and not isinstance(colors[0], str)):

# List of value, color pairs

vals, colors = zip(*colors)

else:

vals = np.linspace(0, 1, len(colors))

cdict = dict(red=[], green=[], blue=[], alpha=[])

for val, color in zip(vals, colors):

r, g, b, a = to_rgba(color)

cdict['red'].append((val, r, r))

cdict['green'].append((val, g, g))

cdict['blue'].append((val, b, b))

cdict['alpha'].append((val, a, a))

return LinearSegmentedColormap(name, cdict, N, gamma)

def _resample(self, lutsize):

"""

Return a new color map with *lutsize* entries.

"""

return LinearSegmentedColormap(self.name, self._segmentdata, lutsize)

# Helper ensuring picklability of the reversed cmap.

@staticmethod

def _reverser(func, x):

return func(1 - x)

def reversed(self, name=None):

"""

Make a reversed instance of the Colormap.

Parameters

----------

name : str, optional

The name for the reversed colormap. If it's None the

name will be the name of the parent colormap + "_r".

Returns

-------

LinearSegmentedColormap

The reversed colormap.

"""

if name is None:

name = self.name + "_r"

# Using a partial object keeps the cmap picklable.

data_r = {key: (functools.partial(self._reverser, data)

if callable(data) else

[(1.0 - x, y1, y0) for x, y0, y1 in reversed(data)])

for key, data in self._segmentdata.items()}

return LinearSegmentedColormap(name, data_r, self.N, self._gamma)

class ListedColormap(Colormap):

"""

Colormap object generated from a list of colors.

This may be most useful when indexing directly into a colormap,

but it can also be used to generate special colormaps for ordinary

mapping.

Parameters

----------

colors : list, array

List of Matplotlib color specifications, or an equivalent Nx3 or Nx4

floating point array (*N* rgb or rgba values).

name : str, optional

String to identify the colormap.

N : int, optional

Number of entries in the map. The default is *None*, in which case

there is one colormap entry for each element in the list of colors.

If ::

N < len(colors)

the list will be truncated at *N*. If ::

N > len(colors)

the list will be extended by repetition.

"""

def __init__(self, colors, name='from_list', N=None):

self.monochrome = False # Are all colors identical? (for contour.py)

if N is None:

self.colors = colors

N = len(colors)

else:

if isinstance(colors, str):

self.colors = [colors] * N

self.monochrome = True

elif np.iterable(colors):

if len(colors) == 1:

self.monochrome = True

self.colors = list(

itertools.islice(itertools.cycle(colors), N))

else:

try:

gray = float(colors)

except TypeError:

pass

else:

self.colors = [gray] * N

self.monochrome = True

Colormap.__init__(self, name, N)

def _init(self):

self._lut = np.zeros((self.N + 3, 4), float)

self._lut[:-3] = to_rgba_array(self.colors)

self._isinit = True

self._set_extremes()

def _resample(self, lutsize):

"""

Return a new color map with *lutsize* entries.

"""

colors = self(np.linspace(0, 1, lutsize))

return ListedColormap(colors, name=self.name)

def reversed(self, name=None):

"""

Make a reversed instance of the Colormap.

Parameters

----------

name : str, optional

The name for the reversed colormap. If it's None the

name will be the name of the parent colormap + "_r".

Returns

-------

ListedColormap

A reversed instance of the colormap.

"""

if name is None:

name = self.name + "_r"

colors_r = list(reversed(self.colors))

return ListedColormap(colors_r, name=name, N=self.N)

class Normalize:

"""

A class which, when called, can normalize data into

the ``[0.0, 1.0]`` interval.

"""

def __init__(self, vmin=None, vmax=None, clip=False):

"""

If *vmin* or *vmax* is not given, they are initialized from the

minimum and maximum value respectively of the first input

processed. That is, *__call__(A)* calls *autoscale_None(A)*.

If *clip* is *True* and the given value falls outside the range,

the returned value will be 0 or 1, whichever is closer.

Returns 0 if ::

vmin==vmax

Works with scalars or arrays, including masked arrays. If

*clip* is *True*, masked values are set to 1; otherwise they

remain masked. Clipping silently defeats the purpose of setting

the over, under, and masked colors in the colormap, so it is

likely to lead to surprises; therefore the default is

*clip* = *False*.

"""

self.vmin = _sanitize_extrema(vmin)

self.vmax = _sanitize_extrema(vmax)

self.clip = clip

@staticmethod

def process_value(value):

"""

Homogenize the input *value* for easy and efficient normalization.

*value* can be a scalar or sequence.

Returns *result*, *is_scalar*, where *result* is a

masked array matching *value*. Float dtypes are preserved;

integer types with two bytes or smaller are converted to

np.float32, and larger types are converted to np.float64.

Preserving float32 when possible, and using in-place operations,

can greatly improve speed for large arrays.

Experimental; we may want to add an option to force the

use of float32.

"""

is_scalar = not np.iterable(value)

if is_scalar:

value = [value]

dtype = np.min_scalar_type(value)

if np.issubdtype(dtype, np.integer) or dtype.type is np.bool_:

# bool_/int8/int16 -> float32; int32/int64 -> float64

dtype = np.promote_types(dtype, np.float32)

# ensure data passed in as an ndarray subclass are interpreted as

# an ndarray. See issue #6622.

mask = np.ma.getmask(value)

data = np.asarray(value)

result = np.ma.array(data, mask=mask, dtype=dtype, copy=True)

return result, is_scalar

def __call__(self, value, clip=None):

"""

Normalize *value* data in the ``[vmin, vmax]`` interval into

the ``[0.0, 1.0]`` interval and return it. *clip* defaults