I vote leave it in cm for now, but since there's HTML colorbar reprs now (#17888) can you use this to print the list of colormaps?

You mean as ColormapRegistry.__repr_html__? In principle yes. - I'm always a bit cautious on long reprs.

I hear but like I have that page of the docs printed out cause of how often I look up the colormaps.

guess I'm not particularly following the use-case for this versus just get_cmap? If we just want a list of colormaps, why can't we just store that as a flat list and give the user access to it? I'm not following why we need a mapping.

This is motivated in the discussion #16991 (review).

The idea is to have a more concise colormap mangement and API. The current state is a bit ad-hoc. You have a private (formerly public) dict and functions get_cmap, register_cmap working on that. By making the dict private, users lost access to the keys.

You could store the names in a flat list, but that would be redundant to the keys of the private dict and needs synchronization. Also, users could manipulate that list - though I'm not too concerned about this.

The whole construct is conceptually a mapping. So why not make it one? Collecting everything into one class makes it easier to manage everything consistently. It makes it also easier to move the user-facing actions out of cm. While to be thought about in more detail, I can imagine that the colormaps can be accessed in the future from the top-level module such as:

import matplotlib as mpl
mpl.colormaps.register(my_colormap)
cmap = mpl.colormaps['jet']

OK, so this is just a first step to this class being a new interface for the colormap registry. Because right now, if I use cmap_register this class will no longer return the new colormap, right? I guess I think at the very least it should return the current state of the registry, not the state at import.

I'd prefer not having to import cm to get this list. I always import pyplot, so I'd be fine with it there, but I understand the aesthetic problem with "we discourage pyplot, except for these 4 things we still think are useful".

OK, so this is just a first step to this class being a new interface for the colormap registry.

Correct.

Because right now, if I use cmap_register this class will no longer return the new colormap, right? I guess I think at the very least it should return the current state of the registry, not the state at import.

It does. The internal self._cmaps is a reference to the same object as _cmap_registry:

In [9]: cm.colormaps._cmaps is cm._cmap_registry
Out[9]: True

Thus, the object plays nicely with the existing functions. (Whether or not we deprecate and remove them or just discourage their use is still to be decided.)

I'd prefer not having to import cm to get this list. I always import pyplot, so I'd be fine with it there, but I understand the aesthetic problem with "we discourage pyplot, except for these 4 things we still think are useful".

Agreed. There should be no need for the user to import cm. The nice thing with an object is that we can easily reference it from anywhere. We can instantiate it in cm but do from matplotlib.cm import colormaps in matplotlib and pyplot (or we directly instantiate it in matplotlib and only import in pyplot.

👍 I like this. I think it makes it clear what is going on and allows for flexibility moving forward.

What would you think about adding a register() method directly to this class? It seems like people would want to add/write directly to this registry.
mpl.colormaps.register(my_new_cmap)
mpl.cm.register_cmap() could just dispatch directly to that method then.

Or even allow people to set the colormaps just like a dict, but raise on name collisions?
mpl.colormaps['viridis'] = my_new_cmap -> raise

@greglucas That's exactly the plan. I'm not completely decided on register() vs. dict-setitem, which is why it's not yet in the PR. I tend towards an explicit register() because we likely won't have a full mutable mapping functionality (or semantic, e.g. concerning overwriting existing keys).

@timhoffm, is there anything here you want help with or feedback on? I'd like to see this get in for the 3.5 release if possible.

Note: I've added register(..., force=False).

It is currently not possible to override builtin colormaps via the ColormapRegistry API. That's intentional. I'm questioning the need for such an operation. For now, people can still use cm.register_cmap(..., override_builtin=True) if really needed (or overwrite ColormapRegistry._cmaps).

To make mpl.colormaps work, I had to do a late import of cm because that depends on rcParams to be set up. I intend to clean this all up later. But that requires reorganization of the rcParams code, which would be too much for 3.5. Nevertheless, I'd like to get the colormaps API into 3.5. Hence the workaround.

It took me a while to find this information in the docs pages.

Docs certainly need adaption. However, I first want to make sure that the API is agreed on before starting to change the docs.
Also technically, we could have this in 3.5 without further doc changes. It's properly announce and the old way is not deprecated (only discouraged). It would also be ok to change the docs in 3.5.1 if we don't manage that for 3.5.

This seems fine to me. I feel that we will still have some confusion, as the colormap registry is ephemeral, so why have so much public interface to it. If I need to create the colormap at startup, I'd just use it directly. So I think the added docs will be helpful to guide folks and make it clear what is happening here.

My sense is that long term we want to deprecate mpl.cm.register_colormap and friends? There will have to be some period in the middle where we support both so if that is the plan I'm not worried about the confusion factor.

Getting a bit over my skis, having these in a nice object at least opens a path putting filter(...) methods on it that will return a new one with just the color maps of interest (e.g. ask only for perceptually uniform or diverging color maps...assuming we tag them with enough information) which would be super useful for a UI.

I do not think we are going to get this done in the next few weeks, I propose bumping it to 3.6.

I forget where we stand on deprecating the global colormap mutability and whether this PR is something that needs to get in for that?

This PR mentions that we missed the intermediate state and extended the deprecation period: #19766, but I'm not clear if we ever added the intermediate state in 3.5 or not? i.e. is there an action item to add/change the way we get colormaps/warn about it?

xref: #19609 for a discussion about mpl.cm.{cmap_name}.

Overall goal

The registry is a more natural structure for managing colormaps. We have data and corresponding functions that are tightly related. IMHO it's a much nicer API for the user and easier to extend. And we get rid of some API quirks in the functions like get_cmap(.. lut=...) or the parameter order register_cmap(name, cmap) where name is optional.

Target state

• the matplotlib.cm colormap functions should eventually be removed.
• I'm open for discussion if we keep the pyplot functions or replace them with the registry as well.

Transition path

While I would like to eventually remove the matplotlib.cm functions, I propose a prolonged transition path because they are quite fundamental functions also used in third party libraries:

• For 3.5: introduce the registry as is in this PR; discourage the cm functions. This is to see if we have missed something important in the design and get user feedback. - Maybe we should declare the registry experimental.
• For 3.6: Introduce a pending deprecation. This is the time where all downstream libraries should start switching to using the registry.
• For 3.7 (or later): Deprecate the cm functions.
• For 3.9 (or later): Remove the cm functions.

I strongly advocate to introduce this PR in 3.5. If everything goes well, we don't need modifications (only extensions) to the registry, which means that downstream libraries would have 3.5 as a minimum dependency when they switch to the registry.

On read-only colormaps

The registry colormap access already returns copies of the colormaps and by that implements the change to get_cmap, which is scheduled to take effect in 3.6 (#19766). He can be quicker here, because the new API does not have to maintain backward compatibility for the deprecation period.
Other than that, the registry is independent of cmap mutability.

My objection is a little more fundamental; I'm not sure why we need a registry at all, so rather than hoisting it to the top level I would tend to discourage passing colormaps by string.

The ship on not supporting colormaps-by-string sailed long ago and I think deprecating that in any meaningful way is out of the question. If we are going to support it, I would rather support it with a nice object which can be both more discover-able and inspect-able than the current state.

One other thought (that I don't think is a great idea because it would add another way to do something) is that you could override __getattr__ on this Registry and allow access to the built-ins that way so that
matplotlib.colormaps.viridis is the same as matplotlib.colormaps['viridis']. That may help with moving matplotlib.cm.viridis and friends over to this new location.

Thanks for the proposal. It’s always good to add ideas to the solution space. However, I agree that this is not a great idea 😀. As you mentioned, this is just another way to achieve the same thing. And worse: it dilutes the mapping concept. The registry is a simple mapping: name -> Colormap, which is canonically associated with item access. The attributes would pollute the register namespace and introduce an unnecessary asymmetry between built in and third party color maps. I think that matplotlib.cm.viridis was an design flaw in the first place. I don't want to replicate this to the registry. OTOH the future of these cm functions is a separate discussion and possibly targeted at 3.6.

Let's merge. Someone can always add an unregister later.