|
15 | 15 | normalization. |
16 | 16 | """ |
17 | 17 |
|
18 | | -from collections.abc import MutableMapping |
| 18 | +from collections.abc import Mapping, MutableMapping |
19 | 19 |
|
20 | 20 | import numpy as np |
21 | 21 | from numpy import ma |
@@ -91,13 +91,85 @@ def _warn_deprecated(self): |
91 | 91 | ) |
92 | 92 |
|
93 | 93 |
|
| 94 | +class ColormapRegistry(Mapping): |
| 95 | + r""" |
| 96 | + Container for colormaps that are known to Matplotlib by name. |
| 97 | +
|
| 98 | + The universal registry instance is `matplotlib.colormaps`. There should be |
| 99 | + no need for users to instantiate `.ColormapRegistry` themselves. |
| 100 | +
|
| 101 | + Read access uses a dict-like interface mapping names to `.Colormap`\s:: |
| 102 | +
|
| 103 | + import matplotlib as mpl |
| 104 | + cmap = mpl.colormaps['viridis'] |
| 105 | +
|
| 106 | + Returned `.Colormap`\s are copies, so that their modification does not |
| 107 | + change the global definition of the colormap. |
| 108 | +
|
| 109 | + Additional colormaps can be added via `.ColormapRegistry.register`:: |
| 110 | +
|
| 111 | + mpl.colormaps.register(my_colormap) |
| 112 | + """ |
| 113 | + def __init__(self, cmaps): |
| 114 | + self._cmaps = cmaps |
| 115 | + |
| 116 | + def __getitem__(self, item): |
| 117 | + try: |
| 118 | + return self._cmaps[item].copy() |
| 119 | + except KeyError: |
| 120 | + raise KeyError(f"{item!r} is not a known colormap name") |
| 121 | + |
| 122 | + def __iter__(self): |
| 123 | + return iter(self._cmaps) |
| 124 | + |
| 125 | + def __len__(self): |
| 126 | + return len(self._cmaps) |
| 127 | + |
| 128 | + def __str__(self): |
| 129 | + return ('ColormapRegistry; available colormaps:\n' + |
| 130 | + ', '.join(f"'{name}'" for name in self)) |
| 131 | + |
| 132 | + def register(self, cmap, *, name=None, force=False): |
| 133 | + """ |
| 134 | + Register a new colormap. |
| 135 | +
|
| 136 | + The colormap name can then be used as a string argument to any ``cmap`` |
| 137 | + parameter in Matplotlib. It is also available in `.pyplot.get_cmap`. |
| 138 | +
|
| 139 | + The colormap registry stores a copy of the given colormap, so that |
| 140 | + future changes to the original colormap instance do not affect the |
| 141 | + registered colormap. Think of this as the registry taking a snapshot |
| 142 | + of the colormap at registration. |
| 143 | +
|
| 144 | + Parameters |
| 145 | + ---------- |
| 146 | + cmap : matplotlib.colors.Colormap |
| 147 | + The colormap to register. |
| 148 | +
|
| 149 | + name : str, optional |
| 150 | + The name for the colormap. If not given, the |
| 151 | + :attr:`~.Colormap.name` attribute of *cmap* is used. |
| 152 | +
|
| 153 | + force: bool, default: False |
| 154 | +
|
| 155 | + """ |
| 156 | + name_ = name or cmap.name |
| 157 | + if name_ in self and not force: |
| 158 | + raise ValueError( |
| 159 | + f'A colormap named "{name}" is already registered.') |
| 160 | + register_cmap(name, cmap.copy()) |
| 161 | + |
| 162 | + |
94 | 163 | _cmap_registry = _gen_cmap_registry() |
95 | 164 | globals().update(_cmap_registry) |
96 | 165 | # This is no longer considered public API |
97 | 166 | cmap_d = _DeprecatedCmapDictWrapper(_cmap_registry) |
98 | 167 | __builtin_cmaps = tuple(_cmap_registry) |
99 | 168 |
|
100 | | -# Continue with definitions ... |
| 169 | +# public acces to the colormaps should be via `matplotlib.colormaps`. For now, |
| 170 | +# we still create the registry here, but that should stay an implementation |
| 171 | +# detail. |
| 172 | +_colormaps = ColormapRegistry(_cmap_registry) |
101 | 173 |
|
102 | 174 |
|
103 | 175 | def register_cmap(name=None, cmap=None, *, override_builtin=False): |
|
0 commit comments