DOC Cleaning up mplot3d/surface3d* examples: comments/docstrings, tweaks, and refactoring. [MEP12]

TrishGillett · TrishGillett · commit 885ce29578b7 · 2016-07-05T13:49:24.000-04:00
diff --git a/examples/mplot3d/surface3d_demo.py b/examples/mplot3d/surface3d_demo.py
@@ -1,23 +1,38 @@
+'''
+Demonstrates plotting a 3D surface colored with the coolwarm color map.
+The surface is made opaque by using antialiased=False.
+
+Also demonstrates using the LinearLocator and custom formatting for the
+z axis tick labels.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
+import matplotlib.pyplot as plt
 from matplotlib import cm
 from matplotlib.ticker import LinearLocator, FormatStrFormatter
-import matplotlib.pyplot as plt
 import numpy as np
 
+
 fig = plt.figure()
 ax = fig.gca(projection='3d')
+
+# Make data.
 X = np.arange(-5, 5, 0.25)
 Y = np.arange(-5, 5, 0.25)
 X, Y = np.meshgrid(X, Y)
 R = np.sqrt(X**2 + Y**2)
 Z = np.sin(R)
+
+# Plot the surface.
 surf = ax.plot_surface(X, Y, Z, rstride=1, cstride=1, cmap=cm.coolwarm,
                        linewidth=0, antialiased=False)
-ax.set_zlim(-1.01, 1.01)
 
+# Customize the z axis.
+ax.set_zlim(-1.01, 1.01)
 ax.zaxis.set_major_locator(LinearLocator(10))
 ax.zaxis.set_major_formatter(FormatStrFormatter('%.02f'))
 
+# Add a color bar which maps values to colors.
 fig.colorbar(surf, shrink=0.5, aspect=5)
 
 plt.show()
diff --git a/examples/mplot3d/surface3d_demo2.py b/examples/mplot3d/surface3d_demo2.py
@@ -1,16 +1,23 @@
+'''
+Demonstrates a very basic plot of a 3D surface using a solid color.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
 import matplotlib.pyplot as plt
 import numpy as np
 
+
 fig = plt.figure()
 ax = fig.add_subplot(111, projection='3d')
 
+# Make data
 u = np.linspace(0, 2 * np.pi, 100)
 v = np.linspace(0, np.pi, 100)
-
 x = 10 * np.outer(np.cos(u), np.sin(v))
 y = 10 * np.outer(np.sin(u), np.sin(v))
 z = 10 * np.outer(np.ones(np.size(u)), np.cos(v))
+
+# Plot the surface
 ax.plot_surface(x, y, z, rstride=4, cstride=4, color='b')
 
 plt.show()
diff --git a/examples/mplot3d/surface3d_demo3.py b/examples/mplot3d/surface3d_demo3.py
@@ -1,11 +1,18 @@
+'''
+Demonstrates plotting a 3D surface colored in a checkerboard pattern.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
+import matplotlib.pyplot as plt
 from matplotlib import cm
 from matplotlib.ticker import LinearLocator
-import matplotlib.pyplot as plt
 import numpy as np
 
+
 fig = plt.figure()
 ax = fig.gca(projection='3d')
+
+# Make data.
 X = np.arange(-5, 5, 0.25)
 xlen = len(X)
 Y = np.arange(-5, 5, 0.25)
@@ -14,16 +21,20 @@
 R = np.sqrt(X**2 + Y**2)
 Z = np.sin(R)
 
+# Create an empty array of strings with the same shape as the meshgrid, and
+# populate it with two colors in a checkerboard pattern.
 colortuple = ('y', 'b')
 colors = np.empty(X.shape, dtype=str)
 for y in range(ylen):
     for x in range(xlen):
         colors[x, y] = colortuple[(x + y) % len(colortuple)]
 
+# Plot the surface with face colors taken from the array we made.
 surf = ax.plot_surface(X, Y, Z, rstride=1, cstride=1, facecolors=colors,
                        linewidth=0)
 
-ax.set_zlim3d(-1, 1)
+# Customize the z axis.
+ax.set_zlim(-1, 1)
 ax.w_zaxis.set_major_locator(LinearLocator(6))
 
 plt.show()
diff --git a/examples/mplot3d/surface3d_radial_demo.py b/examples/mplot3d/surface3d_radial_demo.py
@@ -1,26 +1,35 @@
-# By Armin Moser
+'''
+Demonstrates plotting a surface defined in polar coordinates.
+Uses the reversed version of the YlGnBu color map.
+Also demonstrates writing axis labels with latex math mode.
+
+Example contributed by Armin Moser.
+'''
 
 from mpl_toolkits.mplot3d import Axes3D
-import matplotlib
-import numpy as np
-from matplotlib import cm
 from matplotlib import pyplot as plt
-step = 0.04
-maxval = 1.0
+import numpy as np
+
+
 fig = plt.figure()
 ax = fig.add_subplot(111, projection='3d')
 
-# create supporting points in polar coordinates
+# Create the mesh in polar coordinates and compute corresponding Z.
 r = np.linspace(0, 1.25, 50)
 p = np.linspace(0, 2*np.pi, 50)
 R, P = np.meshgrid(r, p)
-# transform them to cartesian system
+Z = ((R**2 - 1)**2)
+
+# Express the mesh in the cartesian system.
 X, Y = R*np.cos(P), R*np.sin(P)
 
-Z = ((R**2 - 1)**2)
-ax.plot_surface(X, Y, Z, rstride=1, cstride=1, cmap=cm.YlGnBu_r)
-ax.set_zlim3d(0, 1)
+# Plot the surface.
+ax.plot_surface(X, Y, Z, rstride=1, cstride=1, cmap=plt.cm.YlGnBu_r)
+
+# Tweak the limits and add latex math labels.
+ax.set_zlim(0, 1)
 ax.set_xlabel(r'$\phi_\mathrm{real}$')
 ax.set_ylabel(r'$\phi_\mathrm{im}$')
 ax.set_zlabel(r'$V(\phi)$')
+
 plt.show()
