|
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,86 @@ 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, ``cmap.name`` is used. |
| 151 | +
|
| 152 | + force: bool, default: False |
| 153 | + If False, a ValueError is raised if trying to overwrite an already |
| 154 | + registered name. True supports overwriting registered colormaps |
| 155 | + other than the builtin colormaps. |
| 156 | + """ |
| 157 | + name = name or cmap.name |
| 158 | + if name in self and not force: |
| 159 | + raise ValueError( |
| 160 | + f'A colormap named "{name}" is already registered.') |
| 161 | + register_cmap(name, cmap.copy()) |
| 162 | + |
| 163 | + |
94 | 164 | _cmap_registry = _gen_cmap_registry() |
95 | 165 | globals().update(_cmap_registry) |
96 | 166 | # This is no longer considered public API |
97 | 167 | cmap_d = _DeprecatedCmapDictWrapper(_cmap_registry) |
98 | 168 | __builtin_cmaps = tuple(_cmap_registry) |
99 | 169 |
|
100 | | -# Continue with definitions ... |
| 170 | +# public acces to the colormaps should be via `matplotlib.colormaps`. For now, |
| 171 | +# we still create the registry here, but that should stay an implementation |
| 172 | +# detail. |
| 173 | +_colormaps = ColormapRegistry(_cmap_registry) |
101 | 174 |
|
102 | 175 |
|
103 | 176 | def register_cmap(name=None, cmap=None, *, override_builtin=False): |
|
0 commit comments