From 885a82bbe3adf8d48f69898749d243496a03762c Mon Sep 17 00:00:00 2001
From: Trish Gillett-Kawamoto <discardthree@gmail.com>
Date: Sun, 3 Jul 2016 23:47:55 -0400
Subject: [PATCH 1/6] DOC Change ax.set_xlim3d to ax.set_xlim, etc.

---
 examples/mplot3d/2dcollections3d_demo.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/mplot3d/2dcollections3d_demo.py b/examples/mplot3d/2dcollections3d_demo.py
index 107f0479087d..f1f733ae147e 100644
--- 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')

From 890e88030c40cf86442fa4ff189f69fad6b0437a Mon Sep 17 00:00:00 2001
From: Trish Gillett-Kawamoto <discardthree@gmail.com>
Date: Sun, 3 Jul 2016 23:53:32 -0400
Subject: [PATCH 2/6] DOC Cleaning up mplot3d examples quiver3d_demo,
 rotate_axes3d_demo, scatter3d_demo, subplot3d_demo, and text3d_demo:
 Comments, docstrings and tweaks. [MEP12]

---
 examples/mplot3d/quiver3d_demo.py      |  6 +++++
 examples/mplot3d/rotate_axes3d_demo.py | 12 ++++++++--
 examples/mplot3d/scatter3d_demo.py     | 18 ++++++++++++---
 examples/mplot3d/subplot3d_demo.py     | 32 +++++++++++++++++---------
 examples/mplot3d/text3d_demo.py        | 24 +++++++++++++++----
 5 files changed, 72 insertions(+), 20 deletions(-)

diff --git a/examples/mplot3d/quiver3d_demo.py b/examples/mplot3d/quiver3d_demo.py
index 65d02862db8a..c415e836db9d 100644
--- a/examples/mplot3d/quiver3d_demo.py
+++ b/examples/mplot3d/quiver3d_demo.py
@@ -1,3 +1,7 @@
+'''
+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
@@ -5,10 +9,12 @@
 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
index 1c715478a7b7..b269fd8ff768 100644
--- 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
index 64d792bd3613..67845a926d5e 100644
--- 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
index 557f11602fea..64b8f2a8177e 100644
--- a/examples/mplot3d/subplot3d_demo.py
+++ b/examples/mplot3d/subplot3d_demo.py
@@ -1,17 +1,23 @@
-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)
@@ -19,12 +25,16 @@
 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
index 182d6c11dfa2..1f33b411d541 100644
--- 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')

From 13bb60963928849292adb70eac5a877713e7a2da Mon Sep 17 00:00:00 2001
From: Trish Gillett-Kawamoto <discardthree@gmail.com>
Date: Mon, 4 Jul 2016 00:00:35 -0400
Subject: [PATCH 3/6] DOC Cleaning up mplot3d/surface3d* examples:
 comments/docstrings, tweaks, and refactoring. [MEP12]

---
 examples/mplot3d/surface3d_demo.py        | 19 ++++++++++++--
 examples/mplot3d/surface3d_demo2.py       |  9 ++++++-
 examples/mplot3d/surface3d_demo3.py       | 15 +++++++++--
 examples/mplot3d/surface3d_radial_demo.py | 31 +++++++++++++++--------
 4 files changed, 58 insertions(+), 16 deletions(-)

diff --git a/examples/mplot3d/surface3d_demo.py b/examples/mplot3d/surface3d_demo.py
index f5c7c1392e98..5cc576ba1820 100644
--- 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
index 817e7088d5b7..d84529b85be0 100644
--- 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
index 50d10ca4986f..0cf39d12c3cf 100644
--- 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
index d12b02b9963b..f0b896d7be69 100644
--- 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()

From 3243b51f10d619e245ded55975e461ec313eb899 Mon Sep 17 00:00:00 2001
From: Trish Gillett-Kawamoto <discardthree@gmail.com>
Date: Tue, 5 Jul 2016 01:04:49 -0400
Subject: [PATCH 4/6] DOC Cleaning up mplot3d/wire3d* examples:
 comments/docstrings, tweaks, and refactoring. [MEP12]

---
 examples/mplot3d/wire3d_animation_demo.py | 31 ++++++++++++++---------
 examples/mplot3d/wire3d_demo.py           | 10 +++++++-
 examples/mplot3d/wire3d_zero_stride.py    | 18 ++++++++++---
 3 files changed, 43 insertions(+), 16 deletions(-)

diff --git a/examples/mplot3d/wire3d_animation_demo.py b/examples/mplot3d/wire3d_animation_demo.py
index c030d95509ed..e30856775fb1 100644
--- a/examples/mplot3d/wire3d_animation_demo.py
+++ b/examples/mplot3d/wire3d_animation_demo.py
@@ -1,7 +1,9 @@
-from __future__ import print_function
 """
-A very simple 'animation' of a 3D plot
+A very simple 'animation' of a 3D plot.  See also rotate_axes3d_demo.
 """
+
+from __future__ import print_function
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 import numpy as np
@@ -9,30 +11,35 @@
 
 
 def generate(X, Y, phi):
+    '''
+    Generates Z data for the points in the X, Y meshgrid and parameter phi.
+    '''
     R = 1 - np.sqrt(X**2 + Y**2)
     return np.cos(2 * np.pi * X + phi) * R
 
+
 fig = plt.figure()
 ax = fig.add_subplot(111, projection='3d')
 
+# Make the X, Y meshgrid.
 xs = np.linspace(-1, 1, 50)
 ys = np.linspace(-1, 1, 50)
 X, Y = np.meshgrid(xs, ys)
-Z = generate(X, Y, 0.0)
 
+# Set the z axis limits so they aren't recalculated each frame.
+ax.set_zlim(-1, 1)
+
+# Begin plotting.
 wframe = None
 tstart = time.time()
-for phi in np.linspace(0, 360 / 2 / np.pi, 100):
-
-    oldcol = wframe
+for phi in np.linspace(0, 180. / np.pi, 100):
+    # If a line collection is already remove it before drawing.
+    if wframe:
+        ax.collections.remove(wframe)
 
+    # Plot the new wireframe and pause briefly before continuing.
     Z = generate(X, Y, phi)
     wframe = ax.plot_wireframe(X, Y, Z, rstride=2, cstride=2)
-
-    # Remove old line collection before drawing
-    if oldcol is not None:
-        ax.collections.remove(oldcol)
-
     plt.pause(.001)
 
-print('FPS: %f' % (100 / (time.time() - tstart)))
+print('Average FPS: %f' % (100 / (time.time() - tstart)))
diff --git a/examples/mplot3d/wire3d_demo.py b/examples/mplot3d/wire3d_demo.py
index db8601f52171..8c867113bd8d 100644
--- a/examples/mplot3d/wire3d_demo.py
+++ b/examples/mplot3d/wire3d_demo.py
@@ -1,10 +1,18 @@
+'''
+A very basic demonstration of a wireframe 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')
+
+# Grab some test data.
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Plot a basic wireframe.
 ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10)
 
 plt.show()
diff --git a/examples/mplot3d/wire3d_zero_stride.py b/examples/mplot3d/wire3d_zero_stride.py
index 693a2b1676e4..e42b64437e11 100644
--- a/examples/mplot3d/wire3d_zero_stride.py
+++ b/examples/mplot3d/wire3d_zero_stride.py
@@ -1,12 +1,24 @@
+'''
+Demonstrates that setting rstride or cstride to 0 causes wires to not be
+generated in the corresponding direction.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
-import numpy as np
+
 
 fig, [ax1, ax2] = plt.subplots(2, 1, figsize=(8, 12), subplot_kw={'projection': '3d'})
+
+# Get the test data
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Give the first plot only wireframes of the type y = c
 ax1.plot_wireframe(X, Y, Z, rstride=10, cstride=0)
-ax1.set_title("Column stride 0")
+ax1.set_title("Column (x) stride set to 0")
+
+# Give the second plot only wireframes of the type x = c
 ax2.plot_wireframe(X, Y, Z, rstride=0, cstride=10)
-ax2.set_title("Row stride 0")
+ax2.set_title("Row (y) stride set to 0")
+
 plt.tight_layout()
 plt.show()

From bfbf0ca7cb11210d6c9d6fe405cecd36eebcc508 Mon Sep 17 00:00:00 2001
From: Trish Gillett-Kawamoto <discardthree@gmail.com>
Date: Tue, 5 Jul 2016 01:22:13 -0400
Subject: [PATCH 5/6] DOC Cleaning up mplot3d/tri* examples:
 comments/docstrings, tweaks, and refactoring.  Notably, viewing angles on
 tricontour examples are tweaked and the graphs of trisurf3d_demo2 are made
 into subplots. [MEP12]

---
 examples/mplot3d/tricontour3d_demo.py  | 25 ++++++++-----
 examples/mplot3d/tricontourf3d_demo.py | 28 +++++++++------
 examples/mplot3d/trisurf3d_demo.py     | 22 ++++++------
 examples/mplot3d/trisurf3d_demo2.py    | 49 ++++++++++++++++++--------
 4 files changed, 81 insertions(+), 43 deletions(-)

diff --git a/examples/mplot3d/tricontour3d_demo.py b/examples/mplot3d/tricontour3d_demo.py
index b1c669a62fde..e2f338f5ca19 100644
--- a/examples/mplot3d/tricontour3d_demo.py
+++ b/examples/mplot3d/tricontour3d_demo.py
@@ -1,27 +1,30 @@
 """
 Contour plots of unstructured triangular grids.
+
+The data used is the same as in the second plot of trisurf3d_demo2.
+tricontourf3d_demo shows the filled version of this example.
 """
+
 import matplotlib.pyplot as plt
 from mpl_toolkits.mplot3d import Axes3D
 import matplotlib.tri as tri
 import numpy as np
-import math
 
-# First create the x and y coordinates of the points.
 n_angles = 48
 n_radii = 8
 min_radius = 0.25
-radii = np.linspace(min_radius, 0.95, n_radii)
 
-angles = np.linspace(0, 2*math.pi, n_angles, endpoint=False)
+# Create the mesh in polar coordinates and compute x, y, z.
+radii = np.linspace(min_radius, 0.95, n_radii)
+angles = np.linspace(0, 2*np.pi, n_angles, endpoint=False)
 angles = np.repeat(angles[..., np.newaxis], n_radii, axis=1)
-angles[:, 1::2] += math.pi/n_angles
+angles[:, 1::2] += np.pi/n_angles
 
 x = (radii*np.cos(angles)).flatten()
 y = (radii*np.sin(angles)).flatten()
 z = (np.cos(radii)*np.cos(angles*3.0)).flatten()
 
-# Create a custom triangulation
+# Create a custom triangulation.
 triang = tri.Triangulation(x, y)
 
 # Mask off unwanted triangles.
@@ -30,7 +33,11 @@
 mask = np.where(xmid*xmid + ymid*ymid < min_radius*min_radius, 1, 0)
 triang.set_mask(mask)
 
-plt.figure()
-plt.gca(projection='3d')
-plt.tricontour(triang, z)
+fig = plt.figure()
+ax = fig.gca(projection='3d')
+ax.tricontour(triang, z, cmap=plt.cm.CMRmap)
+
+# Customize the view angle so it's easier to understand the plot.
+ax.view_init(elev=45.)
+
 plt.show()
diff --git a/examples/mplot3d/tricontourf3d_demo.py b/examples/mplot3d/tricontourf3d_demo.py
index 8a157e83da10..b0db73286d3a 100644
--- a/examples/mplot3d/tricontourf3d_demo.py
+++ b/examples/mplot3d/tricontourf3d_demo.py
@@ -1,27 +1,31 @@
 """
-Contour plots of unstructured triangular grids.
+Filled contour plots of unstructured triangular grids.
+
+The data used is the same as in the second plot of trisurf3d_demo2.
+tricontour3d_demo shows the unfilled version of this example.
 """
+
 import matplotlib.pyplot as plt
 from mpl_toolkits.mplot3d import Axes3D
 import matplotlib.tri as tri
 import numpy as np
-import math
 
-# First create the x and y coordinates of the points.
+# First create the x, y, z coordinates of the points.
 n_angles = 48
 n_radii = 8
 min_radius = 0.25
-radii = np.linspace(min_radius, 0.95, n_radii)
 
-angles = np.linspace(0, 2*math.pi, n_angles, endpoint=False)
+# Create the mesh in polar coordinates and compute x, y, z.
+radii = np.linspace(min_radius, 0.95, n_radii)
+angles = np.linspace(0, 2*np.pi, n_angles, endpoint=False)
 angles = np.repeat(angles[..., np.newaxis], n_radii, axis=1)
-angles[:, 1::2] += math.pi/n_angles
+angles[:, 1::2] += np.pi/n_angles
 
 x = (radii*np.cos(angles)).flatten()
 y = (radii*np.sin(angles)).flatten()
 z = (np.cos(radii)*np.cos(angles*3.0)).flatten()
 
-# Create a custom triangulation
+# Create a custom triangulation.
 triang = tri.Triangulation(x, y)
 
 # Mask off unwanted triangles.
@@ -30,7 +34,11 @@
 mask = np.where(xmid*xmid + ymid*ymid < min_radius*min_radius, 1, 0)
 triang.set_mask(mask)
 
-plt.figure()
-plt.gca(projection='3d')
-plt.tricontourf(triang, z)
+fig = plt.figure()
+ax = fig.gca(projection='3d')
+ax.tricontourf(triang, z, cmap=plt.cm.CMRmap)
+
+# Customize the view angle so it's easier to understand the plot.
+ax.view_init(elev=45.)
+
 plt.show()
diff --git a/examples/mplot3d/trisurf3d_demo.py b/examples/mplot3d/trisurf3d_demo.py
index 0d040b076dd8..68305d353674 100644
--- a/examples/mplot3d/trisurf3d_demo.py
+++ b/examples/mplot3d/trisurf3d_demo.py
@@ -1,27 +1,29 @@
+'''
+Plot a 3D surface with a triangular mesh.
+'''
+
 from mpl_toolkits.mplot3d import Axes3D
-from matplotlib import cm
 import matplotlib.pyplot as plt
 import numpy as np
 
-n_angles = 36
+
 n_radii = 8
+n_angles = 36
 
-# An array of radii
-# Does not include radius r=0, this is to eliminate duplicate points
+# Make radii and angles spaces (radius r=0 omitted to eliminate duplication).
 radii = np.linspace(0.125, 1.0, n_radii)
-
-# An array of angles
 angles = np.linspace(0, 2*np.pi, n_angles, endpoint=False)
 
-# Repeat all angles for each radius
+# Repeat all angles for each radius.
 angles = np.repeat(angles[..., np.newaxis], n_radii, axis=1)
 
-# Convert polar (radii, angles) coords to cartesian (x, y) coords
-# (0, 0) is added here. There are no duplicate points in the (x, y) plane
+# Convert polar (radii, angles) coords to cartesian (x, y) coords.
+# (0, 0) is manually added at this stage,  so there will be no duplicate
+# points in the (x, y) plane.
 x = np.append(0, (radii*np.cos(angles)).flatten())
 y = np.append(0, (radii*np.sin(angles)).flatten())
 
-# Pringle surface
+# Compute z to make the pringle surface.
 z = np.sin(-x*y)
 
 fig = plt.figure()
diff --git a/examples/mplot3d/trisurf3d_demo2.py b/examples/mplot3d/trisurf3d_demo2.py
index 5b1a707e0c28..acf7d1c701da 100644
--- a/examples/mplot3d/trisurf3d_demo2.py
+++ b/examples/mplot3d/trisurf3d_demo2.py
@@ -1,11 +1,28 @@
+'''
+Two additional examples of plotting surfaces with triangular mesh.
+
+The first demonstrates use of plot_trisurf's triangles argument, and the
+second sets a Triangulation object's mask and passes the object directly
+to plot_trisurf.
+'''
+
 import numpy as np
 import matplotlib.pyplot as plt
 from mpl_toolkits.mplot3d import Axes3D
 import matplotlib.tri as mtri
 
-# u, v are parameterisation variables
-u = (np.linspace(0, 2.0 * np.pi, endpoint=True, num=50) * np.ones((10, 1))).flatten()
-v = np.repeat(np.linspace(-0.5, 0.5, endpoint=True, num=10), repeats=50).flatten()
+
+fig = plt.figure(figsize=plt.figaspect(0.5))
+
+#============
+# First plot
+#============
+
+# Make a mesh in the space of parameterisation variables u and v
+u = np.linspace(0, 2.0 * np.pi, endpoint=True, num=50)
+v = np.linspace(-0.5, 0.5, endpoint=True, num=10)
+u, v = np.meshgrid(u, v)
+u, v = u.flatten(), v.flatten()
 
 # This is the Mobius mapping, taking a u, v pair and returning an x, y, z
 # triple
@@ -16,16 +33,18 @@
 # Triangulate parameter space to determine the triangles
 tri = mtri.Triangulation(u, v)
 
-fig = plt.figure()
-ax = fig.add_subplot(1, 1, 1, projection='3d')
-
-# The triangles in parameter space determine which x, y, z points are
-# connected by an edge
+# Plot the surface.  The triangles in parameter space determine which x, y, z
+# points are connected by an edge.
+ax = fig.add_subplot(1, 2, 1, projection='3d')
 ax.plot_trisurf(x, y, z, triangles=tri.triangles, cmap=plt.cm.Spectral)
-
 ax.set_zlim(-1, 1)
 
-# First create the x and y coordinates of the points.
+
+#============
+# Second plot
+#============
+
+# Make parameter spaces radii and angles.
 n_angles = 36
 n_radii = 8
 min_radius = 0.25
@@ -35,6 +54,7 @@
 angles = np.repeat(angles[..., np.newaxis], n_radii, axis=1)
 angles[:, 1::2] += np.pi/n_angles
 
+# Map radius, angle pairs to x, y, z points.
 x = (radii*np.cos(angles)).flatten()
 y = (radii*np.sin(angles)).flatten()
 z = (np.cos(radii)*np.cos(angles*3.0)).flatten()
@@ -45,11 +65,12 @@
 # Mask off unwanted triangles.
 xmid = x[triang.triangles].mean(axis=1)
 ymid = y[triang.triangles].mean(axis=1)
-mask = np.where(xmid*xmid + ymid*ymid < min_radius*min_radius, 1, 0)
+mask = np.where(xmid**2 + ymid**2 < min_radius**2, 1, 0)
 triang.set_mask(mask)
 
-# tripcolor plot.
-fig = plt.figure()
-ax = fig.add_subplot(1, 1, 1, projection='3d')
+# Plot the surface.
+ax = fig.add_subplot(1, 2, 2, projection='3d')
 ax.plot_trisurf(triang, z, cmap=plt.cm.CMRmap)
+
+
 plt.show()

From d47dccebc9839294005527ae5ddc77672222551a Mon Sep 17 00:00:00 2001
From: Trish Gillett-Kawamoto <trish.gillett@shopify.com>
Date: Sun, 16 Oct 2016 11:18:58 -0400
Subject: [PATCH 6/6] Add example titles in sphinx-gallery style.

---
 examples/mplot3d/quiver3d_demo.py         | 4 ++++
 examples/mplot3d/rotate_axes3d_demo.py    | 4 ++++
 examples/mplot3d/scatter3d_demo.py        | 4 ++++
 examples/mplot3d/subplot3d_demo.py        | 4 ++++
 examples/mplot3d/surface3d_demo.py        | 4 ++++
 examples/mplot3d/surface3d_demo2.py       | 4 ++++
 examples/mplot3d/surface3d_demo3.py       | 4 ++++
 examples/mplot3d/surface3d_radial_demo.py | 4 ++++
 examples/mplot3d/text3d_demo.py           | 4 ++++
 examples/mplot3d/tricontour3d_demo.py     | 4 ++++
 examples/mplot3d/tricontourf3d_demo.py    | 4 ++++
 examples/mplot3d/trisurf3d_demo.py        | 4 ++++
 examples/mplot3d/trisurf3d_demo2.py       | 4 ++++
 examples/mplot3d/wire3d_animation_demo.py | 4 ++++
 examples/mplot3d/wire3d_demo.py           | 4 ++++
 examples/mplot3d/wire3d_zero_stride.py    | 4 ++++
 16 files changed, 64 insertions(+)

diff --git a/examples/mplot3d/quiver3d_demo.py b/examples/mplot3d/quiver3d_demo.py
index c415e836db9d..16ba7eab0190 100644
--- a/examples/mplot3d/quiver3d_demo.py
+++ b/examples/mplot3d/quiver3d_demo.py
@@ -1,4 +1,8 @@
 '''
+==============
+3D quiver plot
+==============
+
 Demonstrates plotting directional arrows at points on a 3d meshgrid.
 '''
 
diff --git a/examples/mplot3d/rotate_axes3d_demo.py b/examples/mplot3d/rotate_axes3d_demo.py
index b269fd8ff768..aa12f3ce9a9a 100644
--- a/examples/mplot3d/rotate_axes3d_demo.py
+++ b/examples/mplot3d/rotate_axes3d_demo.py
@@ -1,4 +1,8 @@
 '''
+==================
+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.
diff --git a/examples/mplot3d/scatter3d_demo.py b/examples/mplot3d/scatter3d_demo.py
index 67845a926d5e..21f4932b80a2 100644
--- a/examples/mplot3d/scatter3d_demo.py
+++ b/examples/mplot3d/scatter3d_demo.py
@@ -1,4 +1,8 @@
 '''
+==============
+3D scatterplot
+==============
+
 Demonstration of a basic scatterplot in 3D.
 '''
 
diff --git a/examples/mplot3d/subplot3d_demo.py b/examples/mplot3d/subplot3d_demo.py
index 64b8f2a8177e..9ece9f7ddc02 100644
--- a/examples/mplot3d/subplot3d_demo.py
+++ b/examples/mplot3d/subplot3d_demo.py
@@ -1,4 +1,8 @@
 '''
+====================
+3D plots as subplots
+====================
+
 Demonstrate including 3D plots as subplots.
 '''
 
diff --git a/examples/mplot3d/surface3d_demo.py b/examples/mplot3d/surface3d_demo.py
index 5cc576ba1820..9ed6b0f75aea 100644
--- a/examples/mplot3d/surface3d_demo.py
+++ b/examples/mplot3d/surface3d_demo.py
@@ -1,4 +1,8 @@
 '''
+======================
+3D surface (color map)
+======================
+
 Demonstrates plotting a 3D surface colored with the coolwarm color map.
 The surface is made opaque by using antialiased=False.
 
diff --git a/examples/mplot3d/surface3d_demo2.py b/examples/mplot3d/surface3d_demo2.py
index d84529b85be0..8135f059eef1 100644
--- a/examples/mplot3d/surface3d_demo2.py
+++ b/examples/mplot3d/surface3d_demo2.py
@@ -1,4 +1,8 @@
 '''
+========================
+3D surface (solid color)
+========================
+
 Demonstrates a very basic plot of a 3D surface using a solid color.
 '''
 
diff --git a/examples/mplot3d/surface3d_demo3.py b/examples/mplot3d/surface3d_demo3.py
index 0cf39d12c3cf..370a5a4a2958 100644
--- a/examples/mplot3d/surface3d_demo3.py
+++ b/examples/mplot3d/surface3d_demo3.py
@@ -1,4 +1,8 @@
 '''
+=========================
+3D surface (checkerboard)
+=========================
+
 Demonstrates plotting a 3D surface colored in a checkerboard pattern.
 '''
 
diff --git a/examples/mplot3d/surface3d_radial_demo.py b/examples/mplot3d/surface3d_radial_demo.py
index f0b896d7be69..c18a4d4dec2b 100644
--- a/examples/mplot3d/surface3d_radial_demo.py
+++ b/examples/mplot3d/surface3d_radial_demo.py
@@ -1,4 +1,8 @@
 '''
+=================================
+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.
diff --git a/examples/mplot3d/text3d_demo.py b/examples/mplot3d/text3d_demo.py
index 1f33b411d541..6b1963e2a43b 100644
--- a/examples/mplot3d/text3d_demo.py
+++ b/examples/mplot3d/text3d_demo.py
@@ -1,4 +1,8 @@
 '''
+======================
+Text annotations in 3D
+======================
+
 Demonstrates the placement of text annotations on a 3D plot.
 
 Functionality shown:
diff --git a/examples/mplot3d/tricontour3d_demo.py b/examples/mplot3d/tricontour3d_demo.py
index e2f338f5ca19..f78ff63c8532 100644
--- a/examples/mplot3d/tricontour3d_demo.py
+++ b/examples/mplot3d/tricontour3d_demo.py
@@ -1,4 +1,8 @@
 """
+==========================
+Triangular 3D contour plot
+==========================
+
 Contour plots of unstructured triangular grids.
 
 The data used is the same as in the second plot of trisurf3d_demo2.
diff --git a/examples/mplot3d/tricontourf3d_demo.py b/examples/mplot3d/tricontourf3d_demo.py
index b0db73286d3a..27513f2bd5cd 100644
--- a/examples/mplot3d/tricontourf3d_demo.py
+++ b/examples/mplot3d/tricontourf3d_demo.py
@@ -1,4 +1,8 @@
 """
+=================================
+Triangular 3D filled contour plot
+=================================
+
 Filled contour plots of unstructured triangular grids.
 
 The data used is the same as in the second plot of trisurf3d_demo2.
diff --git a/examples/mplot3d/trisurf3d_demo.py b/examples/mplot3d/trisurf3d_demo.py
index 68305d353674..192d4eb8aa06 100644
--- a/examples/mplot3d/trisurf3d_demo.py
+++ b/examples/mplot3d/trisurf3d_demo.py
@@ -1,4 +1,8 @@
 '''
+======================
+Triangular 3D surfaces
+======================
+
 Plot a 3D surface with a triangular mesh.
 '''
 
diff --git a/examples/mplot3d/trisurf3d_demo2.py b/examples/mplot3d/trisurf3d_demo2.py
index acf7d1c701da..3a6677c76c01 100644
--- a/examples/mplot3d/trisurf3d_demo2.py
+++ b/examples/mplot3d/trisurf3d_demo2.py
@@ -1,4 +1,8 @@
 '''
+===========================
+More triangular 3D surfaces
+===========================
+
 Two additional examples of plotting surfaces with triangular mesh.
 
 The first demonstrates use of plot_trisurf's triangles argument, and the
diff --git a/examples/mplot3d/wire3d_animation_demo.py b/examples/mplot3d/wire3d_animation_demo.py
index e30856775fb1..1083f006436f 100644
--- a/examples/mplot3d/wire3d_animation_demo.py
+++ b/examples/mplot3d/wire3d_animation_demo.py
@@ -1,4 +1,8 @@
 """
+==========================
+Rotating 3D wireframe plot
+==========================
+
 A very simple 'animation' of a 3D plot.  See also rotate_axes3d_demo.
 """
 
diff --git a/examples/mplot3d/wire3d_demo.py b/examples/mplot3d/wire3d_demo.py
index 8c867113bd8d..cd91cc57ac2f 100644
--- a/examples/mplot3d/wire3d_demo.py
+++ b/examples/mplot3d/wire3d_demo.py
@@ -1,4 +1,8 @@
 '''
+=================
+3D wireframe plot
+=================
+
 A very basic demonstration of a wireframe plot.
 '''
 
diff --git a/examples/mplot3d/wire3d_zero_stride.py b/examples/mplot3d/wire3d_zero_stride.py
index e42b64437e11..0eac7b70385f 100644
--- a/examples/mplot3d/wire3d_zero_stride.py
+++ b/examples/mplot3d/wire3d_zero_stride.py
@@ -1,4 +1,8 @@
 '''
+===================================
+3D wireframe plots in one direction
+===================================
+
 Demonstrates that setting rstride or cstride to 0 causes wires to not be
 generated in the corresponding direction.
 '''