Support pixel-by-pixel alpha in imshow. by tillahoffmann · Pull Request #14889 · matplotlib/matplotlib · GitHub

PR Summary

This PR supports pixel-by-pixel alpha channels in imshow and is a replacement for #8183.

PR Checklist

Has Pytest style unit tests
Code is Flake 8 compliant
New features are documented, with examples if plot related
- Likely too minor a change to need a dedicated example?
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
- Not a major new feature.
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way
- No API changes.

This is important/asked for enough that I'd consider it a major feature, so docs would be a plus.

@story645, there are some doc updates here. What sort of additional documentation do you have in mind? A further extension of the docstring or an example similar to https://github.com/matplotlib/matplotlib/blob/master/examples/images_contours_and_fields/image_masked.py? If an example, do you have a preference for adding this to an existing example or creating a dedicated one?

Adding to an existing example would be great, or as a new one in the color section of the examples.

It looks like we could update this example with the new implementation. In particular, the following no longer applies:

While imshow makes it easy to visualize a 2-D matrix as an image, it doesn't easily let you add transparency to the output.

Happy for me to rewrite while keeping the generated images the same?

that'd be perfect, thanks!

More detailed documentations will be nice. It is still a bit difficult to understand just by reading the source codes.

@ruidazeng, what information would you like to see specifically?

@jklymak, @story645, any additional thoughts on this?

@tillahoffmann I'm happy with the docs, thanks!

the docs of np.isscalar basically tell you to not use this function, and suggests np.ndim(alpha) == 0 instead: https://docs.scipy.org/doc/numpy/reference/generated/numpy.isscalar.html

also, should this unset any previously set array_alpha?

Thanks for the pointer regarding np.isscalar. Yes, the _array_alpha should also be unset. Having said that, maybe the implementation proposed in tillahoffmann#1 is preferable because it also addresses @jklymak's #14889 (comment) above.

I think I prefer the approach of tillahoffmann#1, yes this means that the type of get_alpha() changed but that seems better than lying as to the alpha value.
OTOH, tillahoffmann#1 also has a change to composite_images and that change appears to not take array_alpha into account? (Try with two overlapping images that use array alpha, and save to pdf to check.)
It may be fine to just disable software compositing in that case if it's too complicated, and draw the two images separately.

I have dropped This parameter is ignored for RGBA input data. because it appears to be respected by the released matplotlib==3.1.1.

Thanks @tillahoffmann !

I restarted the appveyor CI which looks like it had a worker fail. Given that azure passed, I don't think that this is a windows related bug.

Is there a reason to allow vectorized alpha only for images, and not just every ScalarMappable?

This appears to just return 1 for alpha-arrays. IMHO this needs documentation: What's the purpose of this function and why this kind of handling of alpha-arrays?

Added a description.

Co-Authored-By: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

…o arrayalpha2

Is there a reason to allow vectorized alpha only for images, and not just every ScalarMappable?

Hm, yes, good point. @ImportanceOfBeingErnest, are you suggesting adding the handling of alpha arrays here?

matplotlib/lib/matplotlib/cm.py

Line 178 in bec9259

def to_rgba(self, x, alpha=None, bytes=False, norm=True):

Yes, naively I would think one could have ScalarMappable._alpha which can be a scalar or of the same shape as ScalarMappable._A. However there might be problems because alpha is usually a property of the artist, not the mixin. But if there are no problems, having every ScalarMappable being able to profit from vectorized alphas would be nice. E.g. there are many cases where you cannot use imshow so sooner or later people would ask to have it implemented for pcolor-like functions as well.

If the intention is to broaden to all ScalarMappables this should move to 3.3. I don't think we have a clear enough view and enough testing time to bring such a major change into 3.2.

Are there any possible problems with merging this as is for imshow only and think on a generalization later?

On the other hand it would be a pity to delay it if it turns out that a more general solution is not desireable. I think the real question is: Does the implementation as shown here prevent a more general solution in the future (in the sense of needing to deprecate newly introduced stuff again etc.)?

We can always tag the current approach as experimental (as we did for constrained_layout).

I believe the approach proposed by @ImportanceOfBeingErnest is certainly preferable over the implementation in this PR, but I don't think we'd have to break any interface in the future if we wanted to support vector-alpha at the level of the ScalarMappable mix-in.

I am in favor of merging this now and addressing generalizing it in 3.3. It is better to get useful, but incomplete code out rather than wait for perfect general solutions.

This does not add any public API other than allowing imshow to take a greater range of inputs.

This also connects to #8738

tillahoffmann force-pushed the arrayalpha2 branch from 19fa770 to 6bbc3c2 Compare July 25, 2019 16:09

jklymak reviewed Jul 25, 2019

View reviewed changes

Comment thread lib/matplotlib/image.py Outdated

story645 added the topic: color/alpha label Jul 25, 2019

jklymak added this to the v3.2.0 milestone Jul 25, 2019

ruidazeng reviewed Jul 26, 2019

View reviewed changes

anntzer reviewed Aug 7, 2019

View reviewed changes

Comment thread lib/matplotlib/axes/_axes.py Outdated

anntzer reviewed Aug 7, 2019

View reviewed changes

Comment thread lib/matplotlib/tests/test_image.py Outdated

tacaswell added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Aug 19, 2019

tillahoffmann added 7 commits September 4, 2019 14:33

Support pixel-by-pixel alpha in imshow.

8a5261d

Update imshow transparency example.

7a0ae2c

Ensure get_alpha and set_alpha are consistent.

d1a69c3

Fix docstring format.

b126ba6

Use np.ndim insteady of np.isscalar.

95a4b41

Use check_figures_equal.

fc64a19

Remove incorrect statement from docstring.

5a263e9

tillahoffmann force-pushed the arrayalpha2 branch from cecb420 to 5a263e9 Compare September 4, 2019 13:42

tillahoffmann commented Sep 4, 2019

View reviewed changes

tacaswell approved these changes Sep 5, 2019

View reviewed changes

timhoffm reviewed Sep 8, 2019

View reviewed changes

tillahoffmann and others added 3 commits September 9, 2019 10:04

Drop default value from docstring of imshow.

dff7562

Co-Authored-By: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Add docstring to _get_scalar_alpha.

c778bd9

Merge branch 'arrayalpha2' of github.com:tillahoffmann/matplotlib int…

bec9259

…o arrayalpha2

dopplershift approved these changes Sep 10, 2019

View reviewed changes

dopplershift merged commit db7847f into matplotlib:master Sep 10, 2019

ImportanceOfBeingErnest mentioned this pull request Mar 11, 2020

issue with transparency in imshow #16730

Closed

story645 mentioned this pull request Dec 9, 2022

[ENH]: set facecolor and edgecolor alpha separately #24681

Closed

tacaswell mentioned this pull request Jun 8, 2023

[Bug]: alpha array-type not working with RGB image in imshow() #26092

Closed

                       alpha : float
                       """
-                      martist.Artist.set_alpha(self, alpha)
+                      if np.isscalar(alpha):

-                      alpha : scalar, optional
+                      alpha : scalar or array_like, optional, default: None
                           The alpha blending value, between 0 (transparent) and 1 (opaque).
-                          This parameter is ignored for RGBA input data.

+                      self.stale = True
                       self._imcache = None
+                  def _get_scalar_alpha(self):

Support pixel-by-pixel alpha in imshow. by tillahoffmann · Pull Request #14889 · matplotlib/matplotlib · GitHub

Repository navigation

Support pixel-by-pixel alpha in imshow. - #14889

Support pixel-by-pixel alpha in imshow.#14889dopplershift merged 10 commits intomatplotlib:mastermatplotlib/matplotlib:masterfrom tillahoffmann:arrayalpha2tillahoffmann/matplotlib:arrayalpha2Copy head branch name to clipboard

Conversation

tillahoffmann commented Jul 25, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

story645 commented Jul 25, 2019

Uh oh!

tillahoffmann commented Jul 25, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

story645 commented Jul 25, 2019

Uh oh!

tillahoffmann commented Jul 25, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

story645 commented Jul 25, 2019

Uh oh!

Uh oh!

ruidazeng left a comment

Choose a reason for hiding this comment

Uh oh!

tillahoffmann commented Jul 26, 2019

Uh oh!

tillahoffmann commented Aug 2, 2019

Uh oh!

story645 commented Aug 4, 2019

Uh oh!

anntzer Aug 7, 2019

Choose a reason for hiding this comment

Uh oh!

anntzer Aug 7, 2019

Choose a reason for hiding this comment

Uh oh!

tillahoffmann Aug 9, 2019

Choose a reason for hiding this comment

Uh oh!

anntzer Aug 10, 2019

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tillahoffmann Sep 4, 2019

Choose a reason for hiding this comment

Uh oh!

tacaswell left a comment

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Sep 5, 2019

Uh oh!

ImportanceOfBeingErnest commented Sep 8, 2019

Uh oh!

Uh oh!

timhoffm Sep 8, 2019

Choose a reason for hiding this comment

Uh oh!

tillahoffmann Sep 9, 2019

Choose a reason for hiding this comment

Uh oh!

tillahoffmann commented Sep 9, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ImportanceOfBeingErnest commented Sep 9, 2019

Uh oh!

timhoffm commented Sep 9, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ImportanceOfBeingErnest commented Sep 9, 2019

Uh oh!

anntzer commented Sep 9, 2019

Uh oh!

tillahoffmann commented Sep 9, 2019

Uh oh!

tacaswell commented Sep 10, 2019

Uh oh!

Reviewers

Support pixel-by-pixel alpha in imshow.#14889
dopplershift merged 10 commits into
matplotlib:masterfrom
tillahoffmann:arrayalpha2

tillahoffmann commented Jul 25, 2019 •
edited
Loading

tillahoffmann commented Jul 25, 2019 •
edited
Loading

tillahoffmann commented Jul 25, 2019 •
edited
Loading

tillahoffmann commented Sep 9, 2019 •
edited
Loading

timhoffm commented Sep 9, 2019 •
edited
Loading