update based on feedback from @timhoffm

trygvrad · trygvrad · commit b30a297096c2 · 2026-04-23T23:13:43.000+02:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6175,7 +6175,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
             - (M, N): an image with scalar data. The values are mapped to
               colors using normalization and a colormap. See parameters *norm*,
               *cmap*, *vmin*, *vmax*.
-            - (v, M, N): if coupled with a cmap that supports v scalars
+            - (K, M, N): if coupled with a cmap that supports K scalars
             - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
             - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
               i.e. including transparency.
@@ -6538,10 +6538,10 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
 
         Parameters
         ----------
-        C : 2D (M, N) or 3D (v, M, N) array-like
+        C : 2D (M, N) or 3D (K, M, N) array-like
             The color-mapped values.  Color-mapping is controlled by *cmap*,
             *norm*, *vmin*, and *vmax*. 3D arrays are supported only if the
-            cmap supports v channels.
+            cmap supports K channels.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -6750,7 +6750,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             - (M, N) or M*N: a mesh with scalar data. The values are mapped to
               colors using normalization and a colormap. See parameters *norm*,
               *cmap*, *vmin*, *vmax*.
-            - (v, M, N): if coupled with a cmap that supports v scalars
+            - (K, M, N): if coupled with a cmap that supports K scalars
             - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
             - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
               i.e. including transparency.
@@ -8874,6 +8874,9 @@ def matshow(self, Z, **kwargs):
 
         """
         Z = np.asanyarray(Z)
+        if Z.ndim != 2:
+            if Z.ndim != 3 or Z.shape[2] not in (1, 3, 4):
+                raise TypeError(f"Invalid shape {Z.shape} for image data")
         kw = {'origin': 'upper',
               'interpolation': 'nearest',
               'aspect': 'equal',          # (already the imshow default)
diff --git a/lib/matplotlib/colorizer.py b/lib/matplotlib/colorizer.py
@@ -277,6 +277,11 @@ def set_clim(self, vmin=None, vmax=None):
     def get_clim(self):
         """
         Return the values (min, max) that are mapped to the colormap limits.
+
+        This function always returns min and max as tuples to ensure type consistency
+        when working with both scalar and multivariate color mapping.
+        See also `.ColorizingArtist.get_clim()` which returns scalars but is unavailable
+        for multivariate color mapping.
         """
         if self.norm.n_components == 1:
             return (self.norm.vmin, ), (self.norm.vmax, )
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -1606,14 +1606,14 @@ def with_extremes(self, *, bad=None, under=None, over=None):
 
         Parameters
         ----------
-        bad: :mpltype:`color`, default: None
+        bad : :mpltype:`color`, default: None
             If Matplotlib color, the bad value is set accordingly in the copy
 
-        under tuple of :mpltype:`color`, default: None
+        under : tuple of :mpltype:`color`, default: None
             If tuple, the 'under' value of each component is set with the values
             from the tuple.
 
-        over tuple of :mpltype:`color`, default: None
+        over : tuple of :mpltype:`color`, default: None
             If tuple, the 'over' value of each component is set with the values
             from the tuple.
 
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -283,8 +283,8 @@ def __init__(self, ax,
         self.set_interpolation(interpolation)
         if isinstance(self.norm, mcolors.MultiNorm):
             if interpolation_stage not in [None, 'data', 'auto']:
-                raise ValueError("when using multiple color channels 'data' "
-                                 "is the only valid interpolation_stage, not "
+                raise ValueError("when using multivariate color mapping 'data' "
+                                 "is the only valid interpolation_stage, but got "
                                  f"{interpolation_stage}")
             self.set_interpolation_stage('data')
         else:
@@ -485,7 +485,7 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
                     norms = self.norm.norms
                     dtypes = [A.dtype.fields[f][0] for f in A.dtype.fields]
 
-                def get_scaled_dt(A):
+                def get_scaled_dtype(A):
                     # gets the scaled dtype
                     if A.dtype.kind == 'f':  # Float dtype: scale to same dtype.
                         scaled_dtype = np.dtype('f8' if A.dtype.itemsize > 4 else 'f4')
@@ -501,7 +501,9 @@ def get_scaled_dt(A):
 
                     return scaled_dtype
 
-                A_resampled = [_resample(self, a.astype(get_scaled_dt(a)), out_shape, t)
+                A_resampled = [_resample(self,
+                                         a.astype(get_scaled_dtype(a)),
+                                         out_shape, t)
                                for a in arrs]
 
                 # if using NoNorm, cast back to the original datatype
diff --git a/lib/matplotlib/tests/baseline_images/test_axes/bivariate_visualizations.png b/lib/matplotlib/tests/baseline_images/test_axes/bivariate_visualizations.png
diff --git a/lib/matplotlib/tests/baseline_images/test_axes/multivariate_visualizations.png b/lib/matplotlib/tests/baseline_images/test_axes/multivariate_visualizations.png
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -10368,22 +10368,35 @@ def test_errorbar_uses_rcparams():
         assert_allclose(barcol.get_linewidths(), 1.75)
 
 
+def test_matshow_not_multivariate():
+    """
+    matshow() currently does not support multivariate/bivariate colormaps.
+    This test is to ensure coverage for the if-statement that checks for this.
+
+    This test should be removed if matshow() is updated to support
+    multivariate/bivariate colormaps.
+    """
+    fig, axes = plt.subplots()
+    arr = np.arange(24).reshape((-1, 4, 2))
+    with pytest.raises(TypeError, match="Invalid shape"):
+        axes.matshow(arr)
+
+
 @image_comparison(["bivariate_visualizations.png"], style='mpl20')
 def test_bivariate_visualizations():
     x_0 = np.arange(25, dtype='float32').reshape(5, 5) % 5
     x_1 = np.arange(25, dtype='float32').reshape(5, 5).T % 5
 
-    fig, axes = plt.subplots(1, 6, figsize=(10, 2))
+    fig, axes = plt.subplots(1, 5, figsize=(8, 2))
 
     axes[0].imshow((x_0, x_1), cmap='BiPeak', interpolation='nearest')
-    axes[1].matshow((x_0, x_1), cmap='BiPeak')
-    axes[2].pcolor((x_0, x_1), cmap='BiPeak')
-    axes[3].pcolormesh((x_0, x_1), cmap='BiPeak')
+    axes[1].pcolor((x_0, x_1), cmap='BiPeak')
+    axes[2].pcolormesh((x_0, x_1), cmap='BiPeak')
 
     x = np.arange(5)
     y = np.arange(5)
     X, Y = np.meshgrid(x, y)
-    axes[4].pcolormesh(X, Y, (x_0, x_1), cmap='BiPeak')
+    axes[3].pcolormesh(X, Y, (x_0, x_1), cmap='BiPeak')
 
     patches = [
         mpl.patches.Wedge((.3, .7), .1, 0, 360),             # Full circle
@@ -10395,7 +10408,7 @@ def test_bivariate_visualizations():
     colors_1 = np.arange(len(patches)) % 2
     p = mpl.collections.PatchCollection(patches, cmap='BiPeak', alpha=0.5)
     p.set_array((colors_0, colors_1))
-    axes[5].add_collection(p)
+    axes[4].add_collection(p)
     remove_ticks_and_titles(fig)
 
 
@@ -10405,17 +10418,16 @@ def test_multivariate_visualizations():
     x_1 = np.arange(25, dtype='float32').reshape(5, 5).T % 5
     x_2 = np.arange(25, dtype='float32').reshape(5, 5) % 6
 
-    fig, axes = plt.subplots(1, 6, figsize=(10, 2))
+    fig, axes = plt.subplots(1, 5, figsize=(8, 2))
 
     axes[0].imshow((x_0, x_1, x_2), cmap='3VarAddA')
-    axes[1].matshow((x_0, x_1, x_2), cmap='3VarAddA')
-    axes[2].pcolor((x_0, x_1, x_2), cmap='3VarAddA')
-    axes[3].pcolormesh((x_0, x_1, x_2), cmap='3VarAddA')
+    axes[1].pcolor((x_0, x_1, x_2), cmap='3VarAddA')
+    axes[2].pcolormesh((x_0, x_1, x_2), cmap='3VarAddA')
 
     x = np.arange(5)
     y = np.arange(5)
     X, Y = np.meshgrid(x, y)
-    axes[4].pcolormesh(X, Y, (x_0, x_1, x_2), cmap='3VarAddA')
+    axes[3].pcolormesh(X, Y, (x_0, x_1, x_2), cmap='3VarAddA')
 
     patches = [
         mpl.patches.Wedge((.3, .7), .1, 0, 360),             # Full circle
@@ -10428,7 +10440,7 @@ def test_multivariate_visualizations():
     colors_2 = np.arange(len(patches)) % 3
     p = mpl.collections.PatchCollection(patches, cmap='3VarAddA', alpha=0.5)
     p.set_array((colors_0, colors_1, colors_2))
-    axes[5].add_collection(p)
+    axes[4].add_collection(p)
     remove_ticks_and_titles(fig)
 
 
