"""

Builtin colormaps, colormap handling utilities, and the `ScalarMappable` mixin.

.. seealso::

:doc:`/gallery/color/colormap_reference` for a list of builtin colormaps.

:ref:`colormap-manipulation` for examples of how to make

colormaps.

:ref:`colormaps` an in-depth discussion of choosing

colormaps.

:ref:`colormapnorms` for more details about data normalization.

"""

from collections.abc import Mapping

import matplotlib as mpl

from matplotlib import _api, colors

# TODO make this warn on access

from matplotlib.colorizer import _ScalarMappable as ScalarMappable # noqa

from matplotlib._cm import datad

from matplotlib._cm_listed import cmaps as cmaps_listed

from matplotlib._cm_multivar import cmap_families as multivar_cmaps

from matplotlib._cm_bivar import cmaps as bivar_cmaps

_LUTSIZE = mpl.rcParams['image.lut']

def _gen_cmap_registry():

"""

Generate a dict mapping standard colormap names to standard colormaps, as

well as the reversed colormaps.

"""

cmap_d = {**cmaps_listed}

for name, spec in datad.items():

cmap_d[name] = ( # Precache the cmaps at a fixed lutsize..

colors.LinearSegmentedColormap(name, spec, _LUTSIZE)

if 'red' in spec else

colors.ListedColormap(spec['listed'], name)

if 'listed' in spec else

colors.LinearSegmentedColormap.from_list(name, spec, _LUTSIZE))

# Register colormap aliases for gray and grey.

aliases = {

# alias -> original name

'grey': 'gray',

'gist_grey': 'gist_gray',

'gist_yerg': 'gist_yarg',

'Grays': 'Greys',

}

for alias, original_name in aliases.items():

cmap = cmap_d[original_name].copy()

cmap.name = alias

cmap_d[alias] = cmap

# Generate reversed cmaps.

for cmap in list(cmap_d.values()):

rmap = cmap.reversed()

cmap_d[rmap.name] = rmap

return cmap_d

class ColormapRegistry(Mapping):

r"""

Container for colormaps that are known to Matplotlib by name.

The universal registry instance is `matplotlib.colormaps`. There should be

no need for users to instantiate `.ColormapRegistry` themselves.

Read access uses a dict-like interface mapping names to `.Colormap`\s::

import matplotlib as mpl

cmap = mpl.colormaps['viridis']

Returned `.Colormap`\s are copies, so that their modification does not

change the global definition of the colormap.

Additional colormaps can be added via `.ColormapRegistry.register`::

mpl.colormaps.register(my_colormap)

To get a list of all registered colormaps, you can do::

from matplotlib import colormaps

list(colormaps)

"""

def __init__(self, cmaps):

self._cmaps = cmaps

self._builtin_cmaps = tuple(cmaps)

def __getitem__(self, item):

try:

return self._cmaps[item].copy()

except KeyError:

raise KeyError(f"{item!r} is not a known colormap name") from None

def __iter__(self):

return iter(self._cmaps)

def __len__(self):

return len(self._cmaps)

def __str__(self):

return ('ColormapRegistry; available colormaps:\n' +

', '.join(f"'{name}'" for name in self))

def __call__(self):

"""

Return a list of the registered colormap names.

This exists only for backward-compatibility in `.pyplot` which had a

``plt.colormaps()`` method. The recommended way to get this list is

now ``list(colormaps)``.

"""

return list(self)

def register(self, cmap, *, name=None, force=False):

"""

Register a new colormap.

The colormap name can then be used as a string argument to any ``cmap``

parameter in Matplotlib. It is also available in ``pyplot.get_cmap``.

The colormap registry stores a copy of the given colormap, so that

future changes to the original colormap instance do not affect the

registered colormap. Think of this as the registry taking a snapshot

of the colormap at registration.

Parameters

----------

cmap : matplotlib.colors.Colormap

The colormap to register.

name : str, optional

The name for the colormap. If not given, ``cmap.name`` is used.

force : bool, default: False

If False, a ValueError is raised if trying to overwrite an already

registered name. True supports overwriting registered colormaps

other than the builtin colormaps.

"""

_api.check_isinstance(colors.Colormap, cmap=cmap)

name = name or cmap.name

if name in self:

if not force:

# don't allow registering an already existing cmap

# unless explicitly asked to

raise ValueError(

f'A colormap named "{name}" is already registered.')

elif name in self._builtin_cmaps:

# We don't allow overriding a builtin.

raise ValueError("Re-registering the builtin cmap "

f"{name!r} is not allowed.")

# Warn that we are updating an already existing colormap

_api.warn_external(f"Overwriting the cmap {name!r} "

"that was already in the registry.")

self._cmaps[name] = cmap.copy()

# Someone may set the extremes of a builtin colormap and want to register it

# with a different name for future lookups. The object would still have the

# builtin name, so we should update it to the registered name

if self._cmaps[name].name != name:

self._cmaps[name].name = name

def unregister(self, name):

"""

Remove a colormap from the registry.

You cannot remove built-in colormaps.

If the named colormap is not registered, returns with no error, raises

if you try to de-register a default colormap.

.. warning::

Colormap names are currently a shared namespace that may be used

by multiple packages. Use `unregister` only if you know you

have registered that name before. In particular, do not

unregister just in case to clean the name before registering a

new colormap.

Parameters

----------

name : str

The name of the colormap to be removed.

Raises

------

ValueError

If you try to remove a default built-in colormap.

"""

if name in self._builtin_cmaps:

raise ValueError(f"cannot unregister {name!r} which is a builtin "

"colormap.")

self._cmaps.pop(name, None)

def get_cmap(self, cmap):

"""

Return a color map specified through *cmap*.

Parameters

----------

cmap : str or `~matplotlib.colors.Colormap` or None

- if a `.Colormap`, return it

- if a string, look it up in ``mpl.colormaps``

- if None, return the Colormap defined in :rc:`image.cmap`

Returns

-------

Colormap

"""

# get the default color map

if cmap is None:

return self[mpl.rcParams["image.cmap"]]

# if the user passed in a Colormap, simply return it

if isinstance(cmap, colors.Colormap):

return cmap

if isinstance(cmap, str):

_api.check_in_list(sorted(_colormaps), cmap=cmap)

# otherwise, it must be a string so look it up

return self[cmap]

raise TypeError(

'get_cmap expects None or an instance of a str or Colormap . ' +

f'you passed {cmap!r} of type {type(cmap)}'

)

# public access to the colormaps should be via `matplotlib.colormaps`. For now,

# we still create the registry here, but that should stay an implementation

# detail.

_colormaps = ColormapRegistry(_gen_cmap_registry())

globals().update(_colormaps)

_multivar_colormaps = ColormapRegistry(multivar_cmaps)

_bivar_colormaps = ColormapRegistry(bivar_cmaps)

# This is an exact copy of pyplot.get_cmap(). It was removed in 3.9, but apparently

# caused more user trouble than expected. Re-added for 3.9.1 and extended the

# deprecation period for two additional minor releases.

@_api.deprecated(

'3.7',

removal='3.11',

alternative="``matplotlib.colormaps[name]`` or ``matplotlib.colormaps.get_cmap()``"

" or ``pyplot.get_cmap()``"

)

def get_cmap(name=None, lut=None):

"""

Get a colormap instance, defaulting to rc values if *name* is None.

Parameters

----------

name : `~matplotlib.colors.Colormap` or str or None, default: None

If a `.Colormap` instance, it will be returned. Otherwise, the name of

a colormap known to Matplotlib, which will be resampled by *lut*. The

default, None, means :rc:`image.cmap`.

lut : int or None, default: None

If *name* is not already a Colormap instance and *lut* is not None, the

colormap will be resampled to have *lut* entries in the lookup table.

Returns

-------

Colormap

"""

if name is None:

name = mpl.rcParams['image.cmap']

if isinstance(name, colors.Colormap):

return name

_api.check_in_list(sorted(_colormaps), name=name)

if lut is None:

return _colormaps[name]

else:

return _colormaps[name].resampled(lut)

def _ensure_cmap(cmap):

"""

Ensure that we have a `.Colormap` object.

For internal use to preserve type stability of errors.

Parameters

----------

cmap : None, str, Colormap

- if a `Colormap`, return it

- if a string, look it up in mpl.colormaps

- if None, look up the default color map in mpl.colormaps

Returns

-------

Colormap

"""

if isinstance(cmap, colors.Colormap):

return cmap

cmap_name = cmap if cmap is not None else mpl.rcParams["image.cmap"]

# use check_in_list to ensure type stability of the exception raised by

# the internal usage of this (ValueError vs KeyError)

if cmap_name not in _colormaps:

_api.check_in_list(sorted(_colormaps), cmap=cmap_name)

return mpl.colormaps[cmap_name]