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

FazeelUsmani · rcomer · commit cf9037e41e0f · 2026-02-28T07:48:34.000Z
diff --git a/doc/api/next_api_changes/behavior/28437-CH.rst b/doc/api/next_api_changes/behavior/28437-CH.rst
@@ -1,8 +1,11 @@
 *alpha* parameter handling on images
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When passing and array to ``imshow(..., alpha=...)``, the parameter was silently ignored
-if the image data was an RGB or RBGA image or if :rc:`image.interpolation_stage`
-resolved to "rbga".
+Prior to Matplotlib 3.10.1, when passing an array to ``imshow(..., alpha=...)``, the
+parameter was silently ignored if the image data was an RGB or RGBA image or if
+:rc:`image.interpolation_stage` resolved to "rbga".
 
-This is now fixed, and the alpha array overwrites any previous transparency information.
+Matplotlib 3.10.1 changed this to apply the alpha array as the alpha channel,
+overwriting any existing transparency information in the image data. Matplotlib v3.11.0
+further fixes the handling for RGBA images: the existing alpha channel is now multiplied
+by the alpha array, consistent with how scalar alpha values are handled.
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -512,8 +512,10 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
                     if A.shape[2] == 3:  # image has no alpha channel
                         A = np.dstack([A, np.ones(A.shape[:2])])
                 elif np.ndim(alpha) > 0:  # Array alpha
-                    # user-specified array alpha overrides the existing alpha channel
-                    A = np.dstack([A[..., :3], alpha])
+                    if A.shape[2] == 3:  # RGB: use array alpha directly
+                        A = np.dstack([A, alpha])
+                    else:  # RGBA: multiply existing alpha by array alpha
+                        A = np.dstack([A[..., :3], A[..., 3] * alpha])
                 else:  # Scalar alpha
                     if A.shape[2] == 3:  # broadcast scalar alpha
                         A = np.dstack([A, np.full(A.shape[:2], alpha, np.float32)])
diff --git a/lib/matplotlib/tests/test_image.py b/lib/matplotlib/tests/test_image.py
@@ -1857,7 +1857,7 @@ def test_interpolation_stage_rgba_respects_alpha_param(fig_test, fig_ref, intp_s
     axs_ref[0][2].imshow(im_rgba, interpolation_stage=intp_stage)
 
     # When the image already has an alpha channel, multiply it by the
-    # scalar alpha param, or replace it by the array alpha param
+    # alpha param (both scalar and array alpha multiply the existing alpha)
     axs_tst[1][0].imshow(im_rgba)
     axs_ref[1][0].imshow(im_rgb, alpha=array_alpha)
     axs_tst[1][1].imshow(im_rgba, interpolation_stage=intp_stage, alpha=scalar_alpha)
@@ -1869,7 +1869,8 @@ def test_interpolation_stage_rgba_respects_alpha_param(fig_test, fig_ref, intp_s
     new_array_alpha = np.random.rand(ny, nx)
     axs_tst[1][2].imshow(im_rgba, interpolation_stage=intp_stage, alpha=new_array_alpha)
     axs_ref[1][2].imshow(
-        np.concatenate(  # combine rgb channels with new array alpha
-            (im_rgb, new_array_alpha.reshape((ny, nx, 1))), axis=-1
+        np.concatenate(  # combine rgb channels with multiplied array alpha
+            (im_rgb, array_alpha.reshape((ny, nx, 1))
+             * new_array_alpha.reshape((ny, nx, 1))), axis=-1
         ), interpolation_stage=intp_stage
     )
