Complete rework of 3D depthshading

Remove legacy and inverted depth shade options

Remove depthshade getters

getter

make depthshade_minalpha kwarg only

kwarg order

getter

Update image test failures

Linting

fix masked scatter depth shading

removed depthshade check

fix tests

Fix build warning

Author: scottshambaugh

doc/users/next_whats_new/depthshading_improvement.rst

@@ -1,27 +1,17 @@
-Depth-shading fix and more depth-shading options
---------------------------------------------------------------
-
-New options have been added which allow users to modify the behavior of 
-depth-shading while addressing a visual bug.
+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.
 
-Now, the behavior has been made smooth and predictable, and the user is 
-provided with three new options: whether to invert the shading, setting the
-lowest acceptable alpha value (highest transparency), and whether to use
-the old algorithm.
-
-The default behavior visually matches the old algorithm: items that appear to be
-"deeper" into the screen will become increasingly transparent (up to the now
-user-defined limit). If the inversion option is used then items will start
-at maximum transparency and become gradually opaque with increasing depth.
-
-Note 1: depth-shading applies to Patch3DCollections and Path3DCollections,
-including scatter plots.
+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.
 
-Note 2: "depthshade=True" must still be used to enable depth-shading
+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.
 
 A simple example:
 
@@ -42,9 +32,7 @@ A simple example:
         zs=Z,
         s=S,
         depthshade=True,
-        depthshade_minalpha=0.1,
-        depthshade_inverted=True,
-        depthshade_legacy=True,
+        depthshade_minalpha=0.3,
     )
 
     plt.show()

lib/mpl_toolkits/mplot3d/art3d.py

@@ -18,7 +18,6 @@
     path as mpath)
 from matplotlib.collections import (
     Collection, LineCollection, PolyCollection, PatchCollection, PathCollection)
-from matplotlib.colors import Normalize
 from matplotlib.patches import Patch
 from . import proj3d
 
@@ -649,9 +648,7 @@ def __init__(
         zs=0,
         zdir="z",
         depthshade=True,
-        depthshade_inverted=False,
         depthshade_minalpha=0.3,
-        depthshade_legacy=False,
         axlim_clip=False,
         **kwargs
     ):
@@ -670,40 +667,21 @@ def __init__(
         give the appearance of depth (default is *True*).
         This is typically desired in scatter plots.
 
-        *depthshade_inverted* sets whether to reverse the order of
-        depth-shading transparency.
-
         *depthshade_minalpha* sets the minimum alpha value applied by
         depth-shading.
-
-        *depthshade_legacy* sets whether to use the legacy algorithm
-        for depth-shading.
         """
         self._depthshade = depthshade
-        self._depthshade_inverted = depthshade_inverted
         self._depthshade_minalpha = depthshade_minalpha
-        self._depthshade_legacy = depthshade_legacy
         super().__init__(*args, **kwargs)
         self.set_3d_properties(zs, zdir, axlim_clip)
 
     def get_depthshade(self):
         return self._depthshade
 
-    def get_depthshade_inverted(self):
-        return self._depthshade_inverted
-
-    def get_depthshade_minalpha(self):
-        return self._depthshade_minalpha
-
-    def get_depthshade_legacy(self):
-        return self._depthshade_legacy
-
     def set_depthshade(
         self,
         depthshade,
-        depthshade_inverted=False,
         depthshade_minalpha=0.3,
-        depthshade_legacy=False,
     ):
         """
         Set whether depth shading is performed on collection members.
@@ -713,17 +691,11 @@ def set_depthshade(
         depthshade : bool
             Whether to shade the patches in order to give the appearance of
             depth.
-        depthshade_inverted : bool
-            Whether to reverse order of depth-shading transparency.
         depthshade_minalpha : float
             Sets the minimum alpha value used by depth-shading.
-        depthshade_legacy : bool
-            Whtether to use the legacy algorithm for depth-shading.
         """
         self._depthshade = depthshade
-        self._depthshade_inverted = depthshade_inverted
         self._depthshade_minalpha = depthshade_minalpha
-        self._depthshade_legacy = depthshade_legacy
         self.stale = True
 
     def set_sort_zpos(self, val):
@@ -787,9 +759,7 @@ def _maybe_depth_shade_and_sort_colors(self, color_array):
             _zalpha(
                 color_array,
                 self._vzs,
-                inverted=self._depthshade_inverted,
                 min_alpha=self._depthshade_minalpha,
-                legacy=self._depthshade_legacy,
             )
             if self._vzs is not None and self._depthshade
             else color_array
@@ -813,13 +783,24 @@ def get_edgecolor(self):
 def _get_data_scale(X, Y, Z):
     """
     Estimate the scale of the 3D data for use in depth shading
+
+    Parameters
+    ----------
+    X, Y, Z : masked arrays
+        The data to estimate the scale of.
     """
-    # Account for empty datasets. Assume that X Y and Z have equal lengths
-    if len(X) == 0:
+    # Account for empty datasets. Assume that X Y and Z have the same number
+    # of elements.
+    if not np.ma.count(X):
         return 0
 
     # Estimate the scale using the RSS of the ranges of the dimensions
-    return np.sqrt(np.ptp(X) ** 2 + np.ptp(Y) ** 2 + np.ptp(Z) ** 2)
+    # Note that we don't use np.ma.ptp() because we otherwise get a build
+    # warning about handing empty arrays.
+    ptp_x = X.max() - X.min()
+    ptp_y = Y.max() - Y.min()
+    ptp_z = Z.max() - Z.min()
+    return np.sqrt(ptp_x ** 2 + ptp_y ** 2 + ptp_z ** 2)
 
 
 class Path3DCollection(PathCollection):
@@ -833,9 +814,7 @@ def __init__(
         zs=0,
         zdir="z",
         depthshade=True,
-        depthshade_inverted=False,
         depthshade_minalpha=0.3,
-        depthshade_legacy=False,
         axlim_clip=False,
         **kwargs
     ):
@@ -854,19 +833,11 @@ def __init__(
         give the appearance of depth (default is *True*).
         This is typically desired in scatter plots.
 
-        *depthshade_inverted* sets whether to reverse the order of
-        depth-shading transparency.
-
         *depthshade_minalpha* sets the minimum alpha value applied by
         depth-shading.
-
-        *depthshade_legacy* sets whether to use the legacy algorithm
-        for depth-shading.
         """
         self._depthshade = depthshade
-        self._depthshade_inverted = depthshade_inverted
         self._depthshade_minalpha = depthshade_minalpha
-        self._depthshade_legacy = depthshade_legacy
         self._in_draw = False
         super().__init__(*args, **kwargs)
         self.set_3d_properties(zs, zdir, axlim_clip)
@@ -945,21 +916,10 @@ def set_linewidth(self, lw):
     def get_depthshade(self):
         return self._depthshade
 
-    def get_depthshade_inverted(self):
-        return self._depthshade_inverted
-
-    def get_depthshade_minalpha(self):
-        return self._depthshade_minalpha
-
-    def get_depthshade_legacy(self):
-        return self._depthshade_legacy
-
     def set_depthshade(
         self,
         depthshade,
-        depthshade_inverted=False,
         depthshade_minalpha=0.3,
-        depthshade_legacy=False,
     ):
         """
         Set whether depth shading is performed on collection members.
@@ -969,17 +929,11 @@ def set_depthshade(
         depthshade : bool
             Whether to shade the patches in order to give the appearance of
             depth.
-        depthshade_inverted : bool
-            Whether to reverse order of depth-shading transparency.
         depthshade_minalpha : float
             Sets the minimum alpha value used by depth-shading.
-        depthshade_legacy : bool
-            Whtether to use the legacy algorithm for depth-shading.
         """
         self._depthshade = depthshade
-        self._depthshade_inverted = depthshade_inverted
         self._depthshade_minalpha = depthshade_minalpha
-        self._depthshade_legacy = depthshade_legacy
         self.stale = True
 
     def do_3d_projection(self):
@@ -1048,9 +1002,7 @@ def _maybe_depth_shade_and_sort_colors(self, color_array):
             color_array = _zalpha(
                 color_array,
                 self._vzs,
-                inverted=self._depthshade_inverted,
                 min_alpha=self._depthshade_minalpha,
-                legacy=self._depthshade_legacy,
                 _data_scale=self._data_scale,
             )
 
@@ -1078,10 +1030,9 @@ def patch_collection_2d_to_3d(
     zs=0,
     zdir="z",
     depthshade=True,
-    depthshade_inverted=False,
-    depthshade_minalpha=0.3,
-    depthshade_legacy=False,
     axlim_clip=False,
+    *args,
+    depthshade_minalpha=0.3
 ):
     """
     Convert a `.PatchCollection` into a `.Patch3DCollection` object
@@ -1100,25 +1051,18 @@ def patch_collection_2d_to_3d(
         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_invert
-        Whether to reverse order of depth-shading transparency. Default: *False*.
     depthshade_minalpha
         Sets the minimum alpha value used by depth-shading. Default: 0.3.
-    depthshade_legacy
-        Whether to use the legacy algorithm for depth-shading. Default: *False*.
     axlim_clip : bool, default: False
         Whether to hide patches with a vertex outside the axes view limits.
-
     """
     if isinstance(col, PathCollection):
         col.__class__ = Path3DCollection
         col._offset_zordered = None
     elif isinstance(col, PatchCollection):
         col.__class__ = Patch3DCollection
     col._depthshade = depthshade
-    col._depthshade_inverted = depthshade_inverted
     col._depthshade_minalpha = depthshade_minalpha
-    col._depthshade_legacy = depthshade_legacy
     col._in_draw = False
     col.set_3d_properties(zs, zdir, axlim_clip)
 
@@ -1502,9 +1446,7 @@ def rotate_axes(xs, ys, zs, zdir):
 def _zalpha(
     colors,
     zs,
-    inverted=False,
     min_alpha=0.3,
-    legacy=False,
     _data_scale=None,
 ):
     """Modify the alphas of the color list according to depth."""
@@ -1515,49 +1457,17 @@ def _zalpha(
     # Alpha values beyond the range 0-1 inclusive make no sense, so clip them
     min_alpha = np.clip(min_alpha, 0, 1)
 
-    if _data_scale is None or legacy:
-        # Revert to "legacy mode" if the new method of calculating
-        # _data_scale fails, or if the user asks for it
-
-        # This only works well if the points for *zs* are well-spaced in
-        # all three dimensions. Otherwise, at certain orientations the
-        # min and max zs are very close together.
-        # Should really normalize against the viewing depth.
-
-        # Normalize the z-depths to the range 0 - 1
-        norm = Normalize(np.min(zs), np.max(zs))
-
-        # Generate alpha multipliers using the normalized z-depths so that
-        # closer points are opaque and the furthest points are still visible,
-        # but transparent
-        if inverted:
-            sats = norm(zs) * (1 - min_alpha) + min_alpha
-        else:
-            sats = 1 - norm(zs) * (1 - min_alpha)
+    if _data_scale is None or _data_scale == 0:
+        # Don't scale the alpha values since we have no valid data scale for reference
+        sats = np.ones_like(zs)
 
     else:
-        # Improved normalization using a scale value derived from the XYZ 
-        # limits of the plot
-
-        if _data_scale == 0:
-            # Don't scale the alpha values since we have no valid
-            # data scale for reference
-            sats = np.ones_like(zs)
-
-        else:
-            if inverted:
-                # Deeper points have an increasingly solid appearance
-                sats = np.clip(1 - (np.max(zs) - zs) / _data_scale, min_alpha, 1)
-            else:
-                # This is the mode that most closely matches the legacy behavior
-
-                # Deeper points have an increasingly transparent appearance
-                sats = np.clip(1 - (zs - np.min(zs)) / _data_scale, min_alpha, 1)
+        # Deeper points have an increasingly transparent appearance
+        sats = np.clip(1 - (zs - np.min(zs)) / _data_scale, min_alpha, 1)
 
     rgba = np.broadcast_to(mcolors.to_rgba_array(colors), (len(zs), 4))
 
-    # Change the alpha values of the colors using the generated alpha
-    # multipliers
+    # Change the alpha values of the colors using the generated alpha multipliers
     return np.column_stack([rgba[:, :3], rgba[:, 3] * sats])
 
 

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -2908,10 +2908,8 @@ def add_collection3d(self, col, zs=0, zdir='z', autolim=True, *,
                                      "edgecolors", "c", "facecolor",
                                      "facecolors", "color"])
     def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True,
-                depthshade_inverted=False,
+                *args,
                 depthshade_minalpha=0.3,
-                depthshade_legacy=False,
-                *args, 
                 axlim_clip=False,
                 **kwargs):
         """
@@ -2950,15 +2948,9 @@ def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True,
             depth. Each call to ``scatter()`` will perform its depthshading
             independently.
 
-        depthshade_inverted : bool, default: False
-            Whether to reverse the order of depth-shading transparency.
-
         depthshade_minalpha : float, default: 0.3
             The lowest alpha value applied by depth-shading.
 
-        depthshade_legacy : bool, default: False
-            Whether to use the legacy algorithm for depth-shading.
-
         axlim_clip : bool, default: False
             Whether to hide the scatter points outside the axes view limits.
 
@@ -2997,12 +2989,9 @@ def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True,
             zs=zs,
             zdir=zdir,
             depthshade=depthshade,
-            depthshade_inverted=depthshade_inverted,
             depthshade_minalpha=depthshade_minalpha,
-            depthshade_legacy=depthshade_legacy,
             axlim_clip=axlim_clip,
-       )
-
+        )
         if self._zmargin < 0.05 and xs.size > 0:
             self.set_zmargin(0.05)