Add lightsource parameter to bar3d (matplotlib#15099)

* Add lightsource parameter to bar3d

Bar3d now allows the user to define the user to define the origin of the lightsource.

* Copy lightsource parameter documentation 

Uses `plot_trisurface`'s documentation for `bar3d`'s lightsource parameter.

* Removed redundant #'s for flake8 complicancy

Failed Travis CI test for flake8.

* Changed indentation for flake8 compliancy

Fixed over- and under-indentation.

* Remove whitespace in blank line

* Add test for bar3d lightsource

Compares the computed colors of the bar tops with the user-defined colors.

* Add support for lightsource parameter in bar3d

* Extend line length in rst

* Fix rst formatting

* Fix rst formatting

* Add test description

* Update test description

Make the comment more obvious

* Fix typo

Author: fourpoints

doc/users/next_whats_new/bar3d_lightsource.rst

@@ -0,0 +1,5 @@
+bar3d gained support for the ``lightsource`` parameter
+------------------------------------------------------
+
+bar3d now supports lighting from different angles when the *shade* parameter is
+True.

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -488,7 +488,7 @@ def autoscale(self, enable=True, axis='both', tight=None):
             else:
                 scalez = False
         self.autoscale_view(tight=tight, scalex=scalex, scaley=scaley,
-                                         scalez=scalez)
+                            scalez=scalez)
 
     def auto_scale_xyz(self, X, Y, Z=None, had_data=None):
         # This updates the bounding boxes as to keep a record as to what the
@@ -505,7 +505,7 @@ def auto_scale_xyz(self, X, Y, Z=None, had_data=None):
         self.autoscale_view()
 
     def autoscale_view(self, tight=None, scalex=True, scaley=True,
-                             scalez=True):
+                       scalez=True):
         """
         Autoscale the view limits using the data limits.
         See :meth:`matplotlib.axes.Axes.autoscale_view` for documentation.
@@ -631,7 +631,7 @@ def set_xlim3d(self, left=None, right=None, emit=True, auto=False,
             for other in self._shared_x_axes.get_siblings(self):
                 if other is not self:
                     other.set_xlim(self.xy_viewLim.intervalx,
-                                            emit=False, auto=auto)
+                                   emit=False, auto=auto)
                     if other.figure != self.figure:
                         other.figure.canvas.draw_idle()
         self.stale = True
@@ -692,7 +692,7 @@ def set_ylim3d(self, bottom=None, top=None, emit=True, auto=False,
             for other in self._shared_y_axes.get_siblings(self):
                 if other is not self:
                     other.set_ylim(self.xy_viewLim.intervaly,
-                                            emit=False, auto=auto)
+                                   emit=False, auto=auto)
                     if other.figure != self.figure:
                         other.figure.canvas.draw_idle()
         self.stale = True
@@ -753,7 +753,7 @@ def set_zlim3d(self, bottom=None, top=None, emit=True, auto=False,
             for other in self._shared_z_axes.get_siblings(self):
                 if other is not self:
                     other.set_zlim(self.zz_viewLim.intervalx,
-                                            emit=False, auto=auto)
+                                   emit=False, auto=auto)
                     if other.figure != self.figure:
                         other.figure.canvas.draw_idle()
         self.stale = True
@@ -1241,7 +1241,7 @@ def get_zlabel(self):
         label = self.zaxis.get_label()
         return label.get_text()
 
-    #### Axes rectangle characteristics
+    # Axes rectangle characteristics
 
     def get_frame_on(self):
         """
@@ -1344,7 +1344,7 @@ def tick_params(self, axis='both', **kwargs):
             zkw.pop('labelbottom', None)
             self.zaxis.set_tick_params(**zkw)
 
-    ### data limits, ticks, tick labels, and formatting
+    # data limits, ticks, tick labels, and formatting
 
     def invert_zaxis(self):
         """
@@ -1820,9 +1820,9 @@ def plot_wireframe(self, X, Y, Z, *args, **kwargs):
         tzlines = [tZ[i] for i in cii]
 
         lines = ([list(zip(xl, yl, zl))
-                  for xl, yl, zl in zip(xlines, ylines, zlines)]
-                + [list(zip(xl, yl, zl))
-                   for xl, yl, zl in zip(txlines, tylines, tzlines)])
+                 for xl, yl, zl in zip(xlines, ylines, zlines)]
+                 + [list(zip(xl, yl, zl))
+                 for xl, yl, zl in zip(txlines, tylines, tzlines)])
 
         linec = art3d.Line3DCollection(lines, *args, **kwargs)
         self.add_collection(linec)
@@ -2333,7 +2333,7 @@ def bar(self, left, height, zs=0, zdir='z', *args, **kwargs):
         return patches
 
     def bar3d(self, x, y, z, dx, dy, dz, color=None,
-              zsort='average', shade=True, *args, **kwargs):
+              zsort='average', shade=True, lightsource=None, *args, **kwargs):
         """Generate a 3D barplot.
 
         This method creates three dimensional barplot where the width,
@@ -2376,6 +2376,9 @@ def bar3d(self, x, y, z, dx, dy, dz, color=None,
             When true, this shades the dark sides of the bars (relative
             to the plot's source of light).
 
+        lightsource : `~matplotlib.colors.LightSource`
+            The lightsource to use when *shade* is True.
+
         **kwargs
             Any additional keyword arguments are passed onto
             `~.art3d.Poly3DCollection`.
@@ -2474,7 +2477,7 @@ def bar3d(self, x, y, z, dx, dy, dz, color=None,
 
         if shade:
             normals = self._generate_normals(polys)
-            sfacecolors = self._shade_colors(facecolors, normals)
+            sfacecolors = self._shade_colors(facecolors, normals, lightsource)
         else:
             sfacecolors = facecolors
 

lib/mpl_toolkits/tests/test_mplot3d.py

@@ -4,6 +4,7 @@
 import matplotlib as mpl
 from matplotlib import cm
 from matplotlib import path as mpath
+from matplotlib import colors as mcolors
 from matplotlib.testing.decorators import image_comparison, check_figures_equal
 from matplotlib.cbook.deprecation import MatplotlibDeprecationWarning
 from matplotlib.collections import LineCollection, PolyCollection
@@ -64,6 +65,33 @@ def test_bar3d_notshaded():
     fig.canvas.draw()
 
 
+def test_bar3d_lightsource():
+    fig = plt.figure()
+    ax = fig.add_subplot(1, 1, 1, projection="3d")
+
+    ls = mcolors.LightSource(azdeg=0, altdeg=90)
+
+    length, width = 3, 4
+    area = length * width
+
+    x, y = np.meshgrid(np.arange(length), np.arange(width))
+    x = x.ravel()
+    y = y.ravel()
+    dz = x + y
+
+    color = [cm.coolwarm(i/area) for i in range(area)]
+
+    collection = ax.bar3d(x=x, y=y, z=0,
+                          dx=1, dy=1, dz=dz,
+                          color=color, shade=True, lightsource=ls)
+
+    # Testing that the custom 90° lightsource produces different shading on
+    # the top facecolors compared to the default, and that those colors are
+    # precisely the colors from the colormap, due to the illumination parallel
+    # to the z-axis.
+    np.testing.assert_array_equal(color, collection._facecolors3d[1::6])
+
+
 @image_comparison(['contour3d.png'], remove_text=True, style='mpl20')
 def test_contour3d():
     fig = plt.figure()