matplotlib · efiring · Oct 16, 2016 · Jul 4, 2016 · Jul 4, 2016 · Jul 4, 2016
diff --git a/examples/mplot3d/2dcollections3d_demo.py b/examples/mplot3d/2dcollections3d_demo.py
@@ -28,9 +28,9 @@
 
 # Make legend, set axes limits and labels
 ax.legend()
-ax.set_xlim3d(0, 1)
-ax.set_ylim3d(0, 1)
-ax.set_zlim3d(0, 1)
+ax.set_xlim(0, 1)
+ax.set_ylim(0, 1)
+ax.set_zlim(0, 1)
 ax.set_xlabel('X')
 ax.set_ylabel('Y')
 ax.set_zlabel('Z')

diff --git a/examples/mplot3d/quiver3d_demo.py b/examples/mplot3d/quiver3d_demo.py
@@ -1,14 +1,24 @@
+'''
+==============
+3D quiver plot
+==============
+
+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,25 @@
+'''
+==================
+Rotating a 3D plot
+==================
+
+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,34 @@
-import numpy as np
+'''
+==============
+3D scatterplot
+==============
+
+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,44 @@
-from mpl_toolkits.mplot3d.axes3d import Axes3D
-import matplotlib.pyplot as plt
+'''
+====================
+3D plots as subplots
+====================
 
+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/surface3d_demo.py b/examples/mplot3d/surface3d_demo.py
@@ -1,23 +1,42 @@
+'''
+======================
+3D surface (color map)
+======================
+
+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,27 @@
+'''
+========================
+3D surface (solid color)
+========================
+
+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,22 @@
+'''
+=========================
+3D surface (checkerboard)
+=========================
+
+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 +25,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,39 @@
-# By Armin Moser
+'''
+=================================
+3D surface with polar coordinates
+=================================
+
+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()
diff --git a/examples/mplot3d/text3d_demo.py b/examples/mplot3d/text3d_demo.py
@@ -1,9 +1,25 @@
+'''
+======================
+Text annotations in 3D
+======================
+
+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 +29,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')