Implement dynamic clipping to axes box for 3D plots

Make axlim_clip flag keyword only

Updates

test image

test image restore

Author: scottshambaugh

doc/users/next_whats_new/3d_clip_to_axis_limits.rst

@@ -0,0 +1,30 @@
+Data in 3D plots can now be dynamically clipped to the axes view limits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All 3D plotting functions now support the *axlim_clip* keyword argument, which
+will clip the data to the axes view limits, hiding all data outside those
+bounds. This clipping will be dynamically applied in real time while panning
+and zooming.
+
+Please note that if one vertex of a line segment or 3D patch is clipped, the
+entire segment or patch will be hidden. Not being able to show partial lines
+or patches such that they are "smoothly" cut off at the boundaries of the view
+box is a limitation of the current renderer.
+
+.. plot::
+    :include-source: true
+    :alt: Example of default behavior (left) and axlim_clip=True (right)
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
+    np.random.seed(1)
+    xyz = np.random.rand(25, 3)
+
+    # Note that when a line has one vertex outside the view limits, the entire
+    # line is hidden. The same is true for 3D patches (not shown).
+    ax.plot(xyz[:, 0], xyz[:, 1], xyz[:, 2], '-o')
+    ax.plot(xyz[:, 0], xyz[:, 1], xyz[:, 2], '--*', axlim_clip=True)
+    ax.set(xlim=(0.25, 0.75), ylim=(0, 1), zlim=(0, 1))
+    ax.legend(['axlim_clip=False (default)', 'axlim_clip=True'])

galleries/examples/mplot3d/axlim_clip.py

@@ -0,0 +1,31 @@
+"""
+=====================================
+Clip the data to the axes view limits
+=====================================
+
+Demonstrate clipping of line and marker data to the axes view limits. The
+``axlim_clip`` keyword argument can be used in any of the 3D plotting
+functions.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
+
+# Generate the random data
+np.random.seed(1)
+xyz = np.random.rand(25, 3)
+
+# Default behavior is axlim_clip=False
+ax.plot(xyz[:, 0], xyz[:, 1], xyz[:, 2], '-o')
+
+# When axlim_clip=True, note that when a line segment has one vertex outside
+# the view limits, the entire line is hidden. The same is true for 3D patches
+# if one of their vertices is outside the limits (not shown).
+ax.plot(xyz[:, 0], xyz[:, 1], xyz[:, 2], '--*', axlim_clip=True)
+
+ax.set(xlim=(0.25, 0.75), ylim=(0, 1), zlim=(-1, 1))
+ax.legend(['axlim_clip=False (default)', 'axlim_clip=True'])
+
+plt.show()

lib/matplotlib/collections.py

@@ -339,7 +339,7 @@ def _prepare_points(self):
             # This might have changed an ndarray into a masked array.
             offset_trf = offset_trf.get_affine()
 
-        if isinstance(offsets, np.ma.MaskedArray):
+        if np.ma.isMaskedArray(offsets):
             offsets = offsets.filled(np.nan)
             # Changing from a masked array to nan-filled ndarray
             # is probably most efficient at this point.

lib/matplotlib/text.py

@@ -753,9 +753,16 @@ def draw(self, renderer):
 
             # don't use self.get_position here, which refers to text
             # position in Text:
-            posx = float(self.convert_xunits(self._x))
-            posy = float(self.convert_yunits(self._y))
+            x, y = self._x, self._y
+            if np.ma.is_masked(x):
+                x = np.nan
+            if np.ma.is_masked(y):
+                y = np.nan
+            posx = float(self.convert_xunits(x))
+            posy = float(self.convert_yunits(y))
             posx, posy = trans.transform((posx, posy))
+            if np.isnan(posx) or np.isnan(posy):
+                return  # don't throw a warning here
             if not np.isfinite(posx) or not np.isfinite(posy):
                 _log.warning("posx and posy should be finite values")
                 return