__call__ is now documented, probably thanks to #20081.

I'm not sure what you mean about 3D images. If you know it's greyscale, just pass one channel to the colour mapping. Matplotlib can't know this is what you want.

Yes, this has been discussed elsewhere as well - we don't want to guess if the image is grayscale or not. I'll close...

we don't want to guess if the image is grayscale or not

Um, but you do, here:

If I use to_rgba on a 3D grayscale image (e.g. shape (100, 100, 100)), a ValueError is raised, because you are guessing that I'm giving you a 2D RGB(A) array.

That is correct. We don't accept 3-d arrays unless the third dimension has length 3 or 4, in which case we interpret as rgb(a). If we accepted other 3D arrays how would we know if a (100,100,3) array was rgb or three (100,100) greyscale arrays?

I just think the code is in a weird place where 1D, 2D, 4D, 5D, and 27D arrays work fine, but 3D arrays are special-cased in case the user happens to have passed in a 2D RGB(A) array.

To enable full nD support, you could add a guess_rgba=True kwarg that would keep the existing guessing, but that users could disable.

But anyway, this issue is from a long time ago, and I can see that there's backwards compatibility concerns, so 🤷. I wouldn't be using it in the near term, it's just the special casing that bugs me, as a frequent user of 3D grayscale images. =)

I see, you are correct that higher dim arrays are not explicitly forbidden in the code. If it would be useful to folks, I don't see a reason to not skip the check if guess_rgba=False.

This is really just a one-liner at this point though: rgba = cmap(norm(x), alpha=alpha)