matplotlib · scottshambaugh · Jan 30, 2025 · May 21, 2022 · Nov 29, 2023 · Dec 13, 2024
diff --git a/doc/users/next_whats_new/depthshading_improvement.rst b/doc/users/next_whats_new/depthshading_improvement.rst
@@ -0,0 +1,41 @@
+3D depth-shading fix
+--------------------
+
+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. Depth-shading is an option for Patch3DCollections and
+Path3DCollections, including 3D scatter plots.
+
+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:
+
+.. plot::
+    :include-source: true
+    :alt: A 3D scatter plot with depth-shading enabled.
+
+    import matplotlib.pyplot as plt
+
+    fig = plt.figure()
+    ax = fig.add_subplot(projection="3d")
+
+    X = [i for i in range(10)]
+    Y = [i for i in range(10)]
+    Z = [i for i in range(10)]
+    S = [(i + 1) * 400 for i in range(10)]
+
+    ax.scatter(
+        xs=X,
+        ys=Y,
+        zs=Z,
+        s=S,
+        depthshade=True,
+        depthshade_minalpha=0.3,
+    )
+
+    plt.show()
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
@@ -1133,6 +1133,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,