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

doc/api/next_api_changes/behavior/28437-CH.rst

@@ -1,8 +1,10 @@
 *alpha* parameter handling on images
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When passing and array to ``imshow(..., alpha=...)``, the parameter was silently ignored
-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`
+resolved to "rgba".
 
-This is now fixed, and the alpha array overwrites any previous transparency information.
+This is now fixed. For RGB images, the alpha array is used directly as the alpha channel.
+For RGBA images, the alpha array is multiplied with the existing alpha channel, consistent
+with how scalar alpha values are handled.

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)])

lib/matplotlib/tests/test_image.py

@@ -1841,7 +1841,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)
@@ -1853,7 +1853,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
     )