Document contour3d and contourf3d examples

TrishGillett · TrishGillett · commit 173c3bf4cde6 · 2016-04-15T10:27:11.000-04:00
diff --git a/examples/mplot3d/contour3d_demo.py b/examples/mplot3d/contour3d_demo.py
@@ -1,11 +1,21 @@
+'''
+Demonstrates plotting contour (level) curves in 3D.
+
+This is like a contour plot in 2D except that the f(x,y)=c curve is plotted
+on the plane z=c.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
-ax = fig.add_subplot(111, projection='3d')
+ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Plot contour curves
 cset = ax.contour(X, Y, Z, cmap=cm.coolwarm)
+
 ax.clabel(cset, fontsize=9, inline=1)
 
 plt.show()
diff --git a/examples/mplot3d/contour3d_demo2.py b/examples/mplot3d/contour3d_demo2.py
@@ -1,11 +1,20 @@
+'''
+Demonstrates plotting contour (level) curves in 3D using the extend3d option.
+
+This modification of the contour3d_demo example uses extend3d=True to
+extend the curves vertically into 'ribbons'.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
 cset = ax.contour(X, Y, Z, extend3d=True, cmap=cm.coolwarm)
+
 ax.clabel(cset, fontsize=9, inline=1)
 
 plt.show()
diff --git a/examples/mplot3d/contour3d_demo3.py b/examples/mplot3d/contour3d_demo3.py
@@ -1,20 +1,34 @@
+'''
+Demonstrates displaying a 3D surface while also projecting contour 'profiles'
+onto the 'walls' of the graph.
+
+See contourf3d_demo2 for the filled version.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Plot the 3D surface
 ax.plot_surface(X, Y, Z, rstride=8, cstride=8, alpha=0.3)
-cset = ax.contour(X, Y, Z, zdir='z', offset=-100, cmap=cm.coolwarm)
+
+# Plot projections of the contours for each dimension.  By choosing offsets
+# that match the appropriate axes limits, the projected contours will sit on
+# the 'walls' of the graph
 cset = ax.contour(X, Y, Z, zdir='x', offset=-40, cmap=cm.coolwarm)
 cset = ax.contour(X, Y, Z, zdir='y', offset=40, cmap=cm.coolwarm)
+cset = ax.contour(X, Y, Z, zdir='z', offset=-100, cmap=cm.coolwarm)
 
-ax.set_xlabel('X')
 ax.set_xlim(-40, 40)
-ax.set_ylabel('Y')
 ax.set_ylim(-40, 40)
-ax.set_zlabel('Z')
 ax.set_zlim(-100, 100)
 
+ax.set_xlabel('X')
+ax.set_ylabel('Y')
+ax.set_zlabel('Z')
+
 plt.show()
diff --git a/examples/mplot3d/contourf3d_demo.py b/examples/mplot3d/contourf3d_demo.py
@@ -1,11 +1,21 @@
+'''
+contourf differs from contour in that it creates filled contours, ie.
+a discrete number of colours are used to shade the domain.
+
+This is like a contourf plot in 2D except that the shaded region corresponding
+to the level c is graphed on the plane z=c.
+'''
+
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
 from matplotlib import cm
 
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
 cset = ax.contourf(X, Y, Z, cmap=cm.coolwarm)
+
 ax.clabel(cset, fontsize=9, inline=1)
 
 plt.show()
diff --git a/examples/mplot3d/contourf3d_demo2.py b/examples/mplot3d/contourf3d_demo2.py
@@ -1,7 +1,9 @@
-"""
-.. versionadded:: 1.1.0
-   This demo depends on new features added to contourf3d.
-"""
+'''
+Demonstrates displaying a 3D surface while also projecting filled contour
+'profiles' onto the 'walls' of the graph.
+
+See contourf3d_demo2 for the unfilled version.
+'''
 
 from mpl_toolkits.mplot3d import axes3d
 import matplotlib.pyplot as plt
@@ -10,16 +12,23 @@
 fig = plt.figure()
 ax = fig.gca(projection='3d')
 X, Y, Z = axes3d.get_test_data(0.05)
+
+# Plot the 3D surface
 ax.plot_surface(X, Y, Z, rstride=8, cstride=8, alpha=0.3)
+
+# Plot projections of the contours for each dimension.  By choosing offsets
+# that match the appropriate axes limits, the projected contours will sit on
+# the 'walls' of the graph
 cset = ax.contourf(X, Y, Z, zdir='z', offset=-100, cmap=cm.coolwarm)
 cset = ax.contourf(X, Y, Z, zdir='x', offset=-40, cmap=cm.coolwarm)
 cset = ax.contourf(X, Y, Z, zdir='y', offset=40, cmap=cm.coolwarm)
 
-ax.set_xlabel('X')
 ax.set_xlim(-40, 40)
-ax.set_ylabel('Y')
 ax.set_ylim(-40, 40)
-ax.set_zlabel('Z')
 ax.set_zlim(-100, 100)
 
+ax.set_xlabel('X')
+ax.set_ylabel('Y')
+ax.set_zlabel('Z')
+
 plt.show()
