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

LangQi99 · LangQi99 · commit 5821ca4147a1 · 2025-09-08T00:46:30.000+08:00
diff --git a/galleries/examples/images_contours_and_fields/image_alpha_parameter_demo.py b/galleries/examples/images_contours_and_fields/image_alpha_parameter_demo.py
@@ -0,0 +1,80 @@
+"""
+==========================================
+Alpha parameter behavior with different image types
+==========================================
+
+Demonstrate how the alpha parameter interacts with different image data types
+(2D arrays, RGB, RGBA) and colormaps in matplotlib's imshow function.
+
+This example shows the behavior of the alpha parameter when applied to:
+- 2D scalar data with default colormap
+- 2D scalar data with custom alpha-aware colormap
+- RGB images
+- RGBA images with existing alpha channels
+
+The alpha parameter can be:
+- None (default, no transparency)
+- A scalar float (uniform transparency)
+- A 2D array (per-pixel transparency)
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from matplotlib.colors import ListedColormap
+
+# Fixing random state for reproducibility
+np.random.seed(19680801)
+
+fig, axs = plt.subplots(3, 4, figsize=(12, 10), layout="compressed")
+
+# Set red background to make transparency visible
+for ax in axs.flat:
+    ax.set(facecolor="red", xticks=[], yticks=[])
+
+# Create test data
+mapped = np.array([[0.1, 1.0], [1.0, 0.1]])
+rgb = np.repeat(mapped[:, :, np.newaxis], 3, axis=2)
+rgba = np.concatenate(
+    [
+        rgb,
+        [
+            [[1.0], [0.9]],
+            [[0.8], [0.7]],
+        ],
+    ],
+    axis=2,
+)
+
+alpha_scalar = 0.5
+alpha_2d = np.full_like(mapped, alpha_scalar)
+
+# Create a colormap with built-in alpha
+cmap_with_alpha = ListedColormap(
+    np.concatenate(
+        [plt.cm.viridis.colors, np.full((len(plt.cm.viridis.colors), 1), alpha_scalar)],
+        axis=1,
+    ),
+)
+
+# Test different alpha parameter combinations
+for ax, alpha, alpha_type in zip(axs, [None, alpha_scalar, alpha_2d],
+                                ["None", "scalar", "array"]):
+    # 2D data with default colormap
+    ax[0].imshow(mapped, alpha=alpha)
+    ax[0].set_title(f"2D data, alpha={alpha_type}")
+
+    # 2D data with alpha-aware colormap
+    ax[1].imshow(mapped, cmap=cmap_with_alpha, alpha=alpha)
+    ax[1].set_title(f"2D with alpha cmap, alpha={alpha_type}")
+
+    # RGB image
+    ax[2].imshow(rgb, alpha=alpha)
+    ax[2].set_title(f"RGB image, alpha={alpha_type}")
+
+    # RGBA image (existing alpha channel)
+    ax[3].imshow(rgba, alpha=alpha)
+    ax[3].set_title(f"RGBA image, alpha={alpha_type}")
+
+plt.suptitle("Alpha parameter behavior with different image types", fontsize=14)
+plt.show()
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:  # image has no alpha channel
+                        A = np.dstack([A, alpha])
+                    else:  # blend with existing alpha channel
+                        A = np.dstack([A[..., :3], A[..., 3:] * alpha[..., np.newaxis]])
                 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
@@ -1809,19 +1809,21 @@ 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
+    # scalar alpha param, or blend it with the array alpha param
     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)
     axs_ref[1][1].imshow(
-        np.concatenate(  # combine rgb channels with scaled array alpha
-            (im_rgb, scalar_alpha * array_alpha.reshape((ny, nx, 1))), axis=-1
-        ), interpolation_stage=intp_stage
-    )
+        np.concatenate(
+            (im_rgb,
+             (scalar_alpha * array_alpha).reshape((ny, nx, 1))),
+            axis=-1),
+        interpolation_stage=intp_stage)
     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
-        ), interpolation_stage=intp_stage
-    )
+        np.concatenate(
+            (im_rgb,
+             (array_alpha * new_array_alpha).reshape((ny, nx, 1))),
+            axis=-1),
+        interpolation_stage=intp_stage)
