Merge pull request matplotlib#27349 from scottshambaugh/3d_dynamic_masking

[ENH] Implement dynamic clipping to axes limits for 3D plots

Author: QuLogic

doc/missing-references.json

@@ -328,7 +328,7 @@
       "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Barbs:212",
       "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver:251",
       "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Path3DCollection.set:46",
-      "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Poly3DCollection.set:44"
+      "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Poly3DCollection.set:45"
     ],
     "matplotlib.collections._MeshData.set_array": [
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolormesh:164",

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, then
+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()

galleries/users_explain/toolkits/mplot3d.rst

@@ -121,6 +121,8 @@ See `.Axes3D.fill_between` for API documentation.
    :target: /gallery/mplot3d/fillbetween3d.html
    :align: center
 
+.. versionadded:: 3.10
+
 .. _polygon3d:
 
 Polygon plots

lib/matplotlib/text.py

@@ -754,9 +754,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