3D fill_between auto mode maps to polygon when all points lie on a x, y, or z plane

scottshambaugh · scottshambaugh · commit bf8cde74e9a3 · 2024-06-15T19:41:00.000-06:00
diff --git a/galleries/examples/mplot3d/fillunder3d.py b/galleries/examples/mplot3d/fillunder3d.py
@@ -24,11 +24,8 @@
 
 for i, l in enumerate(lambdas):
     # Note fill_between can take coordinates as length N vectors, or scalars
-    # mode='polygon' is set for faster and cleaner rendering for this shape on
-    # a single plane.
     ax.fill_between(x, l, l**x * np.exp(-l) / gamma(x + 1),
                     x, l, 0,
-                    mode='polygon',
                     facecolors=facecolors[i], alpha=.7)
 
 ax.set(xlim=(0, 10), ylim=(1, 9), zlim=(0, 0.35),
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1986,14 +1986,17 @@ def fill_between(self, x1, y1, z1, x2, y2, z2, *,
             values.
 
         mode : {'auto', 'quad', 'polygon'}, default: 'auto'
-            The fill mode, where 'auto' maps to 'quad'.
+            The fill mode.
+            If 'auto' and all the coordinates for the x, y, or z input pairs
+            are the same, then the points lie on a plane and 'polygon' is used.
+            Otherwise, 'auto' defaults to 'quad'.
             If 'quad', then a separate quadrilateral polygon is created for
             each pair of subsequent points in the 1st and 2nd lines. This is
             more flexible, but may be slower and result in rendering artifacts.
-            If 'polygon', then the 1st and 2nd lines are connected to form a single
-            polygon, which may be faster and render more cleanly for simple
-            shapes (eg, for filling between two lines that lie on a single
-            plane).
+            If 'polygon', then the 1st and 2nd lines are connected to form a
+            single polygon, which may be faster and render more cleanly for
+            simple shapes (eg, for filling between two lines that lie on a
+            single plane).
 
         **kwargs
             All other keyword arguments are passed on to `.Poly3DCollection`.
@@ -2005,11 +2008,14 @@ def fill_between(self, x1, y1, z1, x2, y2, z2, *,
 
         """
         _api.check_in_list(['auto', 'quad', 'polygon'], mode=mode)
-        if mode == 'auto':
-            mode = 'quad'
 
         had_data = self.has_data()
         x1, y1, z1, x2, y2, z2 = cbook._broadcast_with_masks(x1, y1, z1, x2, y2, z2)
+        if mode == 'auto':
+            if np.all(x1 == x2) or np.all(y1 == y2) or np.all(z1 == z2):
+                mode = 'polygon'
+            else:
+                mode = 'quad'
 
         if where is None:
             where = True
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
@@ -610,8 +610,10 @@ def test_fill_between_quad():
 
     where = (theta < np.pi/2) | (theta > 3*np.pi/2)
 
+    # Since none of x1 == x2, y1 == y2, or z1 == z2 is True, the fill_between
+    # mode will map to 'quad'
     ax.fill_between(x1, y1, z1, x2, y2, z2,
-                    where=where, alpha=0.5, edgecolor='k')
+                    where=where, mode='auto', alpha=0.5, edgecolor='k')
 
 
 @mpl3d_image_comparison(['fill_between_polygon.png'], style='mpl20')
@@ -628,8 +630,9 @@ def test_fill_between_polygon():
 
     where = (theta < np.pi/2) | (theta > 3*np.pi/2)
 
+    # Since x1 == x2 and y1 == y2, the fill_between mode will be 'polygon'
     ax.fill_between(x1, y1, z1, x2, y2, z2,
-                    where=where, mode='polygon', edgecolor='k')
+                    where=where, mode='auto', edgecolor='k')
 
 
 @mpl3d_image_comparison(['surface3d.png'], style='mpl20')
