Skip to content

Fix array alpha to multiply (not replace) existing RGBA alpha#30795

Merged
timhoffm merged 1 commit intomatplotlib:mainfrom
FazeelUsmani:fix-rgb-array-alpha-26092
Mar 2, 2026
Merged

Fix array alpha to multiply (not replace) existing RGBA alpha#30795
timhoffm merged 1 commit intomatplotlib:mainfrom
FazeelUsmani:fix-rgb-array-alpha-26092

Conversation

@FazeelUsmani
Copy link
Copy Markdown
Contributor

@FazeelUsmani FazeelUsmani commented Nov 28, 2025 •
edited
Loading

Closes #26092

This fix makes array alpha behavior consistent with scalar alpha behavior for RGBA images. Now both scalar and array alpha values multiply with the existing alpha channel rather than replacing it.

What is the reasoning for this implementation?

  • For RGB images (no existing alpha): array alpha is used directly as the alpha channel (unchanged behavior)
  • For RGBA images (has existing alpha): array alpha now multiplies with existing alpha (previously it replaced it)

This matches the existing scalar alpha behavior and provides more intuitive compositing.

Example

  import numpy as np
  import matplotlib.pyplot as plt

  # RGBA image with 50% alpha
  rgba = np.zeros((10, 10, 4), dtype=np.float32)
  rgba[:, :, 0] = 1.0  # Red
  rgba[:, :, 3] = 0.5  # 50% alpha

  # Array alpha
  alpha_arr = np.ones((10, 10))
  alpha_arr[:5] = 0.5

  # Before: top=0.5, bottom=1.0 (replaced)
  # After:  top=0.25, bottom=0.5 (multiplied)
  plt.imshow(rgba, alpha=alpha_arr)

PR checklist

  • "closes [Bug]: alpha array-type not working with RGB image in imshow() #26092" is in the body of the PR description
  • new and changed code is tested
  • [N/A] Plotting related features are demonstrated in an example
  • New Features and API Changes are noted with a directive and release note
  • [N/A] Documentation complies with general and docstring guidelines

@rcomer rcomer mentioned this pull request Dec 17, 2025
Closed
2 tasks
rcomer
rcomer reviewed Dec 17, 2025
View reviewed changes
Copy link
Copy Markdown
Member

@rcomer rcomer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @FazeelUsmani - the code change looks right to me. I just have a comment on the changenote.

doc/api/next_api_changes/behavior/28437-CH.rst Outdated
if the image data was a RGB or RBGA image or if :rc:`interpolation_state`
resolved to "rbga".
When passing an array to ``imshow(..., alpha=...)``, the parameter was silently ignored
if the image data was a RGB or RGBA image or if :rc:`interpolation_stage`
Copy link
Copy Markdown
Member

@rcomer rcomer Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not quite right - for RGBA the alpha parameter replaced the image alpha channel. So alpha was not ignored.

Copy link
Copy Markdown
Contributor

@ayshih ayshih Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue here is that @FazeelUsmani edited the API-change note for an old PR (#28437) instead of creating a new note, which is why it is misleading.

Copy link
Copy Markdown
Member

@rcomer rcomer Feb 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah OK. So this is actually correct relative to v3.10.0. Does that mean that this is what we want for the v3.11.0 release notes and therefore this is good to go (after a rebase)? Or should v3.11.0 release notes mention that this changed already at v3.10.1 and we're changing it again?

Copy link
Copy Markdown
Member

@rcomer rcomer Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or should the release note just describe the change relative to current (v3.10.8) behaviour? I went looking for examples and found that the v3.9.1 change also appears in the v3.10.0 notes, but the v3.9.2 change does not.

So we do not have an obvious pattern for whether changes from micro releases get mentioned in the next meso release notes. I think probably the least confusing for the user would be to spell out that this has changed twice. I will push something to that effect tomorrow unless someone says otherwise or beats me to it.

@able-j
Copy link
Copy Markdown

able-j commented Feb 15, 2026

@FazeelUsmani
will you update this PR?

@ayshih ayshih mentioned this pull request Feb 19, 2026
Closed
5 tasks
@timhoffm timhoffm mentioned this pull request Feb 20, 2026
Closed
4 tasks
@rcomer rcomer mentioned this pull request Feb 26, 2026
Closed
@tacaswell tacaswell added this to the v3.11.0 milestone Feb 27, 2026
@rcomer rcomer force-pushed the fix-rgb-array-alpha-26092 branch from 4653910 to cf9037e Compare February 28, 2026 07:50
@rcomer
Copy link
Copy Markdown
Member

rcomer commented Feb 28, 2026

Azure failures are the usual subprocess timeouts.

rcomer
rcomer approved these changes Feb 28, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@rcomer rcomer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My approval is only for the code change, since I modified the doc change.

@timhoffm
Copy link
Copy Markdown
Member

timhoffm commented Mar 2, 2026

I think we should have a test for this.

@rcomer
Copy link
Copy Markdown
Member

rcomer commented Mar 2, 2026

@timhoffm there is an updated test to cover the alpha multiplication. What case still needs covering?

@timhoffm
Copy link
Copy Markdown
Member

timhoffm commented Mar 2, 2026

Sorry, I mis-read.

@timhoffm timhoffm merged commit b83305e into matplotlib:main Mar 2, 2026
37 of 40 checks passed
tonybaloney pushed a commit to tonybaloney/swe-complex-matplotlib that referenced this pull request Mar 19, 2026
Human gold patch for matplotlib__matplotlib-30795
789dd93 
PR: matplotlib#30795
Issue: matplotlib#26092
Base commit: 67ebfc9
Changed lines: 24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@timhoffm timhoffm timhoffm approved these changes

@rcomer rcomer rcomer approved these changes

+1 more reviewer

@ayshih ayshih ayshih left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

topic: images

Projects

None yet

Milestone

v3.11.0

Development

Successfully merging this pull request may close these issues.

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

6 participants

@FazeelUsmani @able-j @rcomer @timhoffm @ayshih @tacaswell