Handle grids one larger than C in gouraud shading

lucaznch · lucaznch · commit 45849df0ba95 · 2026-04-01T17:45:59.000+01:00
Allow pcolormesh to accept X and Y with dimensions one
greater than C when shading='gouraud' by emitting a warning
and automatically converting the grid to match the shape of C.

Add tests and update documentation.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6454,9 +6454,18 @@ def _pcolorargs(self, funcname, *args, shading='auto', **kwargs):
                                 f" see help({funcname})")
         else:    # ['nearest', 'gouraud']:
             if (Nx, Ny) != (ncols, nrows):
-                raise TypeError('Dimensions of C %s are incompatible with'
-                                ' X (%d) and/or Y (%d); see help(%s)' % (
-                                    C.shape, Nx, Ny, funcname))
+                if shading == 'gouraud' and (Nx, Ny) == (ncols + 1, nrows + 1):
+                    _api.warn_external(f"Dimensions of C {C.shape} should"
+                                       f" be the same as X({Nx}) and Y({Ny})"
+                                       f" while using shading='gouraud'."
+                                       f" X and Y will be modified to match"
+                                       f" dimensions of C. see help({funcname})")
+                    # the center of each quad is the average of its four corners
+                    X = 0.25 * (X[:-1, :-1] + X[:-1, 1:] + X[1:, 1:] + X[1:, :-1])
+                    Y = 0.25 * (Y[:-1, :-1] + Y[:-1, 1:] + Y[1:, 1:] + Y[1:, :-1])
+                else:
+                    raise TypeError(f"Dimensions of C {C.shape} are incompatible with"
+                                    f" X ({Nx}) and/or Y ({Ny}); see help({funcname})")
             if shading == 'nearest':
                 # grid is specified at the center, so define corners
                 # at the midpoints between the grid centers and then use the
@@ -6751,11 +6760,16 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             greater than those of *C*, otherwise a ValueError is raised. The
             quadrilateral is colored due to the value at ``C[i, j]``.
 
-            If ``shading='nearest'`` or ``'gouraud'``, the dimensions of *X*
-            and *Y* should be the same as those of *C* (if not, a ValueError
-            will be raised).  For ``'nearest'`` the color ``C[i, j]`` is
-            centered on ``(X[i, j], Y[i, j])``.  For ``'gouraud'``, a smooth
-            interpolation is carried out between the quadrilateral corners.
+            If ``shading='nearest'`` the dimensions of *X* and *Y* should be
+            the same as those of *C*, otherwise a ValueError is raised. The
+            color ``C[i, j]`` is centered on ``(X[i, j], Y[i, j])``.
+
+            If ``shading='gouraud'`` the dimensions of *X* and *Y* should be
+            the same as those of *C*; if they are one greater, a warning is
+            raised and *X* and *Y* will be modified to match the dimensions
+            of *C* by replacing each quadrilateral with a single point at its
+            center; otherwise, a ValueError is raised. A smooth interpolation
+            is carried out between the quadrilateral corners.
 
             If *X* and/or *Y* are 1-D arrays or column vectors they will be
             expanded as needed into the appropriate 2D arrays, making a
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -1596,6 +1596,24 @@ def test_pcolor_log_scale(fig_test, fig_ref):
     ax.set_xscale('log')
 
 
+@check_figures_equal()
+def test_pcolormesh_gouraud_grid_conversion(fig_test, fig_ref):
+    Z = np.arange(6).reshape(2, 3)
+
+    x_test = np.array([0, 2, 8, 12])
+    y_test = np.array([0, 2, 6])
+    ax_test = fig_test.subplots()
+    with pytest.warns(UserWarning,
+                      match='X and Y will be modified'
+                            ' to match dimensions of C'):
+        ax_test.pcolormesh(x_test, y_test, Z, shading='gouraud')
+
+    x_ref = np.array([1, 5, 10])
+    y_ref = np.array([1, 4])
+    ax_ref = fig_ref.subplots()
+    ax_ref.pcolormesh(x_ref, y_ref, Z, shading='gouraud')
+
+
 def test_pcolorargs():
     n = 12
     x = np.linspace(-1.5, 1.5, n)
@@ -1609,9 +1627,13 @@ def test_pcolorargs():
     with pytest.raises(TypeError):
         ax.pcolormesh(X, Y, Z.T)
     with pytest.raises(TypeError):
-        ax.pcolormesh(x, y, Z[:-1, :-1], shading="gouraud")
+        ax.pcolormesh(x, y, Z[:-2, :-2], shading='gouraud')
     with pytest.raises(TypeError):
-        ax.pcolormesh(X, Y, Z[:-1, :-1], shading="gouraud")
+        ax.pcolormesh(X, Y, Z[:-2, :-2], shading='gouraud')
+    with pytest.warns(UserWarning,
+                      match='X and Y will be modified'
+                            ' to match dimensions of C'):
+        ax.pcolormesh(x, y, Z[:-1, :-1], shading='gouraud')
     x[0] = np.nan
     with pytest.raises(ValueError):
         ax.pcolormesh(x, y, Z[:-1, :-1])
