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

scottshambaugh · scottshambaugh · commit 6750726eb78c · 2024-06-16T07:53:06.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
@@ -1985,15 +1985,16 @@ def fill_between(self, x1, y1, z1, x2, y2, z2, *,
             the *True* position remain unfilled due to the adjacent *False*
             values.
 
-        mode : {'auto', 'quad', 'polygon'}, default: 'auto'
-            The fill mode, where 'auto' maps 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).
+        mode : {'quad', 'polygon', 'auto'}, default: 'auto'
+            The fill mode. One of:
+            - 'quad':  A separate quadrilateral polygon is created for each
+              pair of subsequent points in the two lines.
+            - 'polygon': The two lines are connected to form a single polygon.
+              This is faster and can render more cleanly for simple shapes
+              (e.g. for filling between two lines that lie within a plane).
+            - 'auto': If the lines are in a plane parallel to a coordinate axis
+              (one of *x*, *y*, *z* for both lines are constant and equal),
+              'polygon' is used. Otherwise, 'quad' is used.
 
         **kwargs
             All other keyword arguments are passed on to `.Poly3DCollection`.
@@ -2005,11 +2006,16 @@ 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 == x1[0]) and np.all(x2 == x1[0]))
+                 or (np.all(y1 == y1[0]) and np.all(y2 == y1[0]))
+                 or (np.all(z1 == z1[0]) and np.all(z2 == z1[0]))):
+                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')
