Make axes3d.depthshade and axes3d.depthshade_minalpha rcparams

scottshambaugh · scottshambaugh · commit e353a99b9ad3 · 2025-01-28T10:43:08.000-07:00
diff --git a/doc/users/next_whats_new/depthshading_improvement.rst b/doc/users/next_whats_new/depthshading_improvement.rst
@@ -1,17 +1,17 @@
 3D depth-shading fix
 --------------------
 
-Previously, a slightly buggy method of estimating the "depth" of plotted
-items could lead to sudden and unexpected changes in transparency as the
-plot orientation changed.
+Previously, a slightly buggy method of estimating the visual "depth" of 3D
+items could lead to sudden and unexpected changes in transparency as the plot
+orientation changed.
 
 Now, the behavior has been made smooth and predictable. A new parameter
 ``depthshade_minalpha`` has also been added to allow users to set the minimum
-transparency level.
+transparency level. Depth-shading is an option for Patch3DCollections and
+Path3DCollections, including 3D scatter plots.
 
-Depth-shading is an option for Patch3DCollections and Path3DCollections,
-including 3D scatter plots. Depth-shading is still off by default, and
-``depthshade=True`` must still be used to enable it.
+The default values for ``depthshade`` and ``depthshade_minalpha`` are now also
+controlled via rcParams, with values of ``True`` and ``0.3`` respectively.
 
 A simple example:
 
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -439,6 +439,9 @@
 #axes3d.yaxis.panecolor:    (0.90, 0.90, 0.90, 0.5)  # background pane on 3D axes
 #axes3d.zaxis.panecolor:    (0.925, 0.925, 0.925, 0.5)  # background pane on 3D axes
 
+#axes3d.depthshade: True  # depth shade for 3D scatter plots
+#axes3d.depthshade_minalpha: 0.3  # minimum alpha value for depth shading
+
 #axes3d.mouserotationstyle: arcball  # {azel, trackball, sphere, arcball}
                             # See also https://matplotlib.org/stable/api/toolkits/mplot3d/view_angles.html#rotation-with-mouse
 #axes3d.trackballsize: 0.667  # trackball diameter, in units of the Axes bbox
diff --git a/lib/matplotlib/mpl-data/stylelib/classic.mplstyle b/lib/matplotlib/mpl-data/stylelib/classic.mplstyle
@@ -225,6 +225,8 @@ axes.spines.top     : True
 polaraxes.grid      : True    # display grid on polar axes
 axes3d.grid         : True    # display grid on 3D axes
 axes3d.automargin   : False   # automatically add margin when manually setting 3D axis limits
+axes3d.depthshade   : False   # depth shade for 3D scatter plots
+axes3d.depthshade_minalpha : 0.3  # minimum alpha value for depth shading
 
 date.autoformatter.year   : %Y
 date.autoformatter.month  : %b %Y
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1125,6 +1125,9 @@ def _convert_validator_spec(key, conv):
     "axes3d.yaxis.panecolor":    validate_color,  # 3d background pane
     "axes3d.zaxis.panecolor":    validate_color,  # 3d background pane
 
+    "axes3d.depthshade": validate_bool,  # depth shade for 3D scatter plots
+    "axes3d.depthshade_minalpha": validate_float,  # min alpha value for depth shading
+
     "axes3d.mouserotationstyle": ["azel", "trackball", "sphere", "arcball"],
     "axes3d.trackballsize": validate_float,
     "axes3d.trackballborder": validate_float,
diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py
@@ -15,7 +15,7 @@
 
 from matplotlib import (
     _api, artist, cbook, colors as mcolors, lines, text as mtext,
-    path as mpath)
+    path as mpath, rcParams)
 from matplotlib.collections import (
     Collection, LineCollection, PolyCollection, PatchCollection, PathCollection)
 from matplotlib.patches import Patch
@@ -631,8 +631,8 @@ def __init__(
         *args,
         zs=0,
         zdir="z",
-        depthshade=True,
-        depthshade_minalpha=0.3,
+        depthshade=None,
+        depthshade_minalpha=None,
         axlim_clip=False,
         **kwargs
     ):
@@ -654,6 +654,10 @@ def __init__(
         *depthshade_minalpha* sets the minimum alpha value applied by
         depth-shading.
         """
+        if depthshade is None:
+            depthshade = rcParams['axes3d.depthshade']
+        if depthshade_minalpha is None:
+            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
         self._depthshade = depthshade
         self._depthshade_minalpha = depthshade_minalpha
         super().__init__(*args, **kwargs)
@@ -665,7 +669,7 @@ def get_depthshade(self):
     def set_depthshade(
         self,
         depthshade,
-        depthshade_minalpha=0.3,
+        depthshade_minalpha=None,
     ):
         """
         Set whether depth shading is performed on collection members.
@@ -675,9 +679,12 @@ def set_depthshade(
         depthshade : bool
             Whether to shade the patches in order to give the appearance of
             depth.
-        depthshade_minalpha : float
+        depthshade_minalpha : float, default: None
             Sets the minimum alpha value used by depth-shading.
+            If None, use the value from rcParams['axes3d.depthshade_minalpha'].
         """
+        if depthshade_minalpha is None:
+            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
         self._depthshade = depthshade
         self._depthshade_minalpha = depthshade_minalpha
         self.stale = True
@@ -793,8 +800,8 @@ def __init__(
         *args,
         zs=0,
         zdir="z",
-        depthshade=True,
-        depthshade_minalpha=0.3,
+        depthshade=None,
+        depthshade_minalpha=None,
         axlim_clip=False,
         **kwargs
     ):
@@ -816,6 +823,10 @@ def __init__(
         *depthshade_minalpha* sets the minimum alpha value applied by
         depth-shading.
         """
+        if depthshade is None:
+            depthshade = rcParams['axes3d.depthshade']
+        if depthshade_minalpha is None:
+            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
         self._depthshade = depthshade
         self._depthshade_minalpha = depthshade_minalpha
         self._in_draw = False
@@ -899,7 +910,7 @@ def get_depthshade(self):
     def set_depthshade(
         self,
         depthshade,
-        depthshade_minalpha=0.3,
+        depthshade_minalpha=None,
     ):
         """
         Set whether depth shading is performed on collection members.
@@ -912,6 +923,8 @@ def set_depthshade(
         depthshade_minalpha : float
             Sets the minimum alpha value used by depth-shading.
         """
+        if depthshade_minalpha is None:
+            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
         self._depthshade = depthshade
         self._depthshade_minalpha = depthshade_minalpha
         self.stale = True
@@ -1002,10 +1015,10 @@ def patch_collection_2d_to_3d(
     col,
     zs=0,
     zdir="z",
-    depthshade=True,
+    depthshade=None,
     axlim_clip=False,
     *args,
-    depthshade_minalpha=0.3
+    depthshade_minalpha=None,
 ):
     """
     Convert a `.PatchCollection` into a `.Patch3DCollection` object
@@ -1022,10 +1035,12 @@ def patch_collection_2d_to_3d(
     zdir : {'x', 'y', 'z'}
         The axis in which to place the patches. Default: "z".
         See `.get_dir_vector` for a description of the values.
-    depthshade
-        Whether to shade the patches to give a sense of depth. Default: *True*.
-    depthshade_minalpha
-        Sets the minimum alpha value used by depth-shading. Default: 0.3.
+    depthshade : bool, default: None
+        Whether to shade the patches to give a sense of depth.
+        If None, use the value from rcParams['axes3d.depthshade'].
+    depthshade_minalpha : float, default: None
+        Sets the minimum alpha value used by depth-shading.
+        If None, use the value from rcParams['axes3d.depthshade_minalpha'].
     axlim_clip : bool, default: False
         Whether to hide patches with a vertex outside the axes view limits.
     """
@@ -1034,6 +1049,10 @@ def patch_collection_2d_to_3d(
         col._offset_zordered = None
     elif isinstance(col, PatchCollection):
         col.__class__ = Patch3DCollection
+    if depthshade is None:
+        depthshade = rcParams['axes3d.depthshade']
+    if depthshade_minalpha is None:
+        depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
     col._depthshade = depthshade
     col._depthshade_minalpha = depthshade_minalpha
     col._in_draw = False
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -2904,9 +2904,9 @@ def add_collection3d(self, col, zs=0, zdir='z', autolim=True, *,
     @_preprocess_data(replace_names=["xs", "ys", "zs", "s",
                                      "edgecolors", "c", "facecolor",
                                      "facecolors", "color"])
-    def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True,
+    def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=None,
                 *args,
-                depthshade_minalpha=0.3,
+                depthshade_minalpha=None,
                 axlim_clip=False,
                 **kwargs):
         """
@@ -2940,14 +2940,15 @@ def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True,
             - A 2D array in which the rows are RGB or RGBA.
 
             For more details see the *c* argument of `~.axes.Axes.scatter`.
-        depthshade : bool, default: True
+        depthshade : bool, default: None
             Whether to shade the scatter markers to give the appearance of
             depth. Each call to ``scatter()`` will perform its depthshading
             independently.
+            If None, use the value from rcParams['axes3d.depthshade'].
 
-        depthshade_minalpha : float, default: 0.3
+        depthshade_minalpha : float, default: None
             The lowest alpha value applied by depth-shading.
-
+            If None, use the value from rcParams['axes3d.depthshade_minalpha'].
         axlim_clip : bool, default: False
             Whether to hide the scatter points outside the axes view limits.
 
@@ -2975,6 +2976,10 @@ def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True,
             )
         if kwargs.get("color") is not None:
             kwargs['color'] = color
+        if depthshade is None:
+            depthshade = mpl.rcParams['axes3d.depthshade']
+        if depthshade_minalpha is None:
+            depthshade_minalpha = mpl.rcParams['axes3d.depthshade_minalpha']
 
         # For xs and ys, 2D scatter() will do the copying.
         if np.may_share_memory(zs_orig, zs):  # Avoid unnecessary copies.
