MNT: slightly re-organize code and clarify docstrings

tacaswell · tacaswell · commit 5a6411dff49b · 2021-03-30T23:09:19.000-04:00
diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py
@@ -546,9 +546,16 @@ def set_3d_properties(self, zs, zdir):
             xs = []
             ys = []
         self._offsets3d = juggle_axes(xs, ys, np.atleast_1d(zs), zdir)
-        # grab the current sizes as-is
         # In the base draw methods we access the attributes directly which
-        # means we can not buffer the shuffling on the way out.
+        # means we can not resolve the shuffling in the getter methods like
+        # we do for the edge and face colors.
+        #
+        # This means we need to carry around a cache of the unsorted sizes and
+        # widths (postfixed with 3d) and in `do_3d_projection` set the
+        # depth-sorted version of that data into the private state used by the
+        # base collection class in its draw method.
+        #
+        # grab the current sizes and linewidths to preserve them
         self._sizes3d = self._sizes
         self._linewidths3d = self._linewidths
         xs, ys, zs = self._offsets3d
@@ -617,30 +624,26 @@ def do_3d_projection(self, renderer=None):
 
         return np.min(vzs) if vzs.size else np.nan
 
-    def get_facecolor(self):
-        bc = super().get_facecolor()
-        fcs = (
-            _zalpha(bc, self._vzs)
+    def _maybe_depth_shade_and_sort_colors(self, color_array):
+        color_array = (
+            _zalpha(color_array, self._vzs)
             if self._vzs is not None and self._depthshade
-            else bc
+            else color_array
         )
-        if len(fcs) > 1:
-            fcs = fcs[self._z_markers_idx]
-        return mcolors.to_rgba_array(fcs, self._alpha)
+        if len(color_array) > 1:
+            color_array = color_array[self._z_markers_idx]
+        return mcolors.to_rgba_array(color_array, self._alpha)
+
+    def get_facecolor(self):
+        return self._maybe_depth_shade_and_sort_colors(super().get_facecolor())
 
     def get_edgecolor(self):
+        # We need this check here to make sure we do not double-apply the based
+        # depth alpha shading when the edge color is "face" which means the
+        # edge colour should be identical to the face colour.
         if cbook._str_equal(self._edgecolors, 'face'):
             return self.get_facecolor()
-
-        bc = super().get_edgecolor()
-        ecs = (
-            _zalpha(bc, self._vzs)
-            if self._vzs is not None and self._depthshade
-            else bc
-        )
-        if len(ecs) > 1:
-            ecs = ecs[self._z_markers_idx]
-        return mcolors.to_rgba_array(ecs, self._alpha)
+        return self._maybe_depth_shade_and_sort_colors(super().get_edgecolor())
 
 
 def patch_collection_2d_to_3d(col, zs=0, zdir='z', depthshade=True):
