DOC Cleaning up mplot3d examples quiver3d_demo, rotate_axes3d_demo, scatter3d_demo, subplot3d_demo, and text3d_demo: Comments, docstrings and tweaks. [MEP12]

TrishGillett · TrishGillett · commit 890e88030c40 · 2016-10-16T11:19:51.000-04:00
diff --git a/examples/mplot3d/quiver3d_demo.py b/examples/mplot3d/quiver3d_demo.py
@@ -1,14 +1,20 @@
+'''
+Demonstrates plotting directional arrows at points on a 3d meshgrid.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 import numpy as np
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 
+# Make the grid
 x, y, z = np.meshgrid(np.arange(-0.8, 1, 0.2),
                       np.arange(-0.8, 1, 0.2),
                       np.arange(-0.8, 1, 0.8))
 
+# Make the direction data for the arrows
 u = np.sin(np.pi * x) * np.cos(np.pi * y) * np.cos(np.pi * z)
 v = -np.cos(np.pi * x) * np.sin(np.pi * y) * np.cos(np.pi * z)
 w = (np.sqrt(2.0 / 3.0) * np.cos(np.pi * x) * np.cos(np.pi * y) *
diff --git a/examples/mplot3d/rotate_axes3d_demo.py b/examples/mplot3d/rotate_axes3d_demo.py
@@ -1,13 +1,21 @@
+'''
+A very simple animation of a rotating 3D plot.
+
+See wire3d_animation_demo for another simple example of animating a 3D plot.
+'''
+
 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')
+
+# load some test data for demonstration and plot a wireframe
 X, Y, Z = axes3d.get_test_data(0.1)
 ax.plot_wireframe(X, Y, Z, rstride=5, cstride=5)
 
+# rotate the axes and update
 for angle in range(0, 360):
     ax.view_init(30, angle)
     plt.draw()
+    plt.pause(.001)
diff --git a/examples/mplot3d/scatter3d_demo.py b/examples/mplot3d/scatter3d_demo.py
@@ -1,18 +1,30 @@
-import numpy as np
+'''
+Demonstration of a basic scatterplot in 3D.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
 import matplotlib.pyplot as plt
+import numpy as np
 
 
 def randrange(n, vmin, vmax):
+    '''
+    Helper function to make an array of random numbers having shape (n, )
+    with each number distributed Uniform(vmin, vmax).
+    '''
     return (vmax - vmin)*np.random.rand(n) + vmin
 
 fig = plt.figure()
 ax = fig.add_subplot(111, projection='3d')
+
 n = 100
-for c, m, zl, zh in [('r', 'o', -50, -25), ('b', '^', -30, -5)]:
+
+# For each set of style and range settings, plot n random points in the box
+# defined by x in [23, 32], y in [0, 100], z in [zlow, zhigh].
+for c, m, zlow, zhigh in [('r', 'o', -50, -25), ('b', '^', -30, -5)]:
     xs = randrange(n, 23, 32)
     ys = randrange(n, 0, 100)
-    zs = randrange(n, zl, zh)
+    zs = randrange(n, zlow, zhigh)
     ax.scatter(xs, ys, zs, c=c, marker=m)
 
 ax.set_xlabel('X Label')
diff --git a/examples/mplot3d/subplot3d_demo.py b/examples/mplot3d/subplot3d_demo.py
@@ -1,30 +1,40 @@
-from mpl_toolkits.mplot3d.axes3d import Axes3D
-import matplotlib.pyplot as plt
-
+'''
+Demonstrate including 3D plots as subplots.
+'''
 
-# imports specific to the plots in this example
-import numpy as np
+import matplotlib.pyplot as plt
+from mpl_toolkits.mplot3d.axes3d import Axes3D, get_test_data
 from matplotlib import cm
-from mpl_toolkits.mplot3d.axes3d import get_test_data
+import numpy as np
 
-# Twice as wide as it is tall.
+
+# set up a figure twice as wide as it is tall
 fig = plt.figure(figsize=plt.figaspect(0.5))
 
-#---- First subplot
+#===============
+#  First subplot
+#===============
+# set up the axes for the first plot
 ax = fig.add_subplot(1, 2, 1, projection='3d')
+
+# plot a 3D surface like in the example mplot3d/surface3d_demo
 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)
 surf = ax.plot_surface(X, Y, Z, rstride=1, cstride=1, cmap=cm.coolwarm,
                        linewidth=0, antialiased=False)
-ax.set_zlim3d(-1.01, 1.01)
-
+ax.set_zlim(-1.01, 1.01)
 fig.colorbar(surf, shrink=0.5, aspect=10)
 
-#---- Second subplot
+#===============
+# Second subplot
+#===============
+# set up the axes for the second plot
 ax = fig.add_subplot(1, 2, 2, projection='3d')
+
+# plot a 3D wireframe like in the example mplot3d/wire3d_demo
 X, Y, Z = get_test_data(0.05)
 ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10)
 
diff --git a/examples/mplot3d/text3d_demo.py b/examples/mplot3d/text3d_demo.py
@@ -1,9 +1,21 @@
+'''
+Demonstrates the placement of text annotations on a 3D plot.
+
+Functionality shown:
+- Using the text function with three types of 'zdir' values: None,
+  an axis name (ex. 'x'), or a direction tuple (ex. (1, 1, 0)).
+- Using the text function with the color keyword.
+- Using the text2D function to place text on a fixed position on the ax object.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
 import matplotlib.pyplot as plt
 
+
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 
+# Demo 1: zdir
 zdirs = (None, 'x', 'y', 'z', (1, 1, 0), (1, 1, 1))
 xs = (1, 4, 4, 9, 4, 1)
 ys = (2, 5, 8, 10, 1, 2)
@@ -13,13 +25,17 @@
     label = '(%d, %d, %d), dir=%s' % (x, y, z, zdir)
     ax.text(x, y, z, label, zdir)
 
+# Demo 2: color
 ax.text(9, 0, 0, "red", color='red')
-ax.text2D(0.05, 0.95, "2D Text", transform=ax.transAxes)
 
-ax.set_xlim3d(0, 10)
-ax.set_ylim3d(0, 10)
-ax.set_zlim3d(0, 10)
+# Demo 3: text2D
+# Placement 0, 0 would be the bottom left, 1, 1 would be the top right.
+ax.text2D(0.05, 0.95, "2D Text", transform=ax.transAxes)
 
+# Tweaking display region and labels
+ax.set_xlim(0, 10)
+ax.set_ylim(0, 10)
+ax.set_zlim(0, 10)
 ax.set_xlabel('X axis')
 ax.set_ylabel('Y axis')
 ax.set_zlabel('Z axis')
