DOC: Add what's new for stem3d, and tweak example.

QuLogic · QuLogic · commit f25fe9007ac6 · 2020-09-03T01:17:47.000-04:00
diff --git a/doc/users/next_whats_new/stem3d.rst b/doc/users/next_whats_new/stem3d.rst
@@ -0,0 +1,24 @@
+Stem plots in 3D Axes
+---------------------
+
+Stem plots are now supported on 3D Axes. Much like 2D stems,
+`~.axes3d.Axes3D.stem3D` supports plotting the stems in various orientations:
+
+.. plot::
+
+    theta = np.linspace(0, 2*np.pi)
+    x = np.cos(theta - np.pi/2)
+    y = np.sin(theta - np.pi/2)
+    z = theta
+    directions = ['z', 'x', 'y']
+    names = [r'$\theta$', r'$\cos\theta$', r'$\sin\theta$']
+
+    fig, axs = plt.subplots(1, 3, figsize=(8, 4),
+                            constrained_layout=True,
+                            subplot_kw={'projection': '3d'})
+    for ax, zdir, name in zip(axs, directions, names):
+        ax.stem(x, y, z, orientation=zdir)
+        ax.set_title(name)
+    fig.suptitle(r'A parametric circle: $(x, y) = (\cos\theta, \sin\theta)$')
+
+See also the :doc:`/gallery/mplot3d/stem3d_demo` demo.
diff --git a/examples/mplot3d/stem3d_demo.py b/examples/mplot3d/stem3d_demo.py
@@ -11,8 +11,8 @@
 import numpy as np
 
 theta = np.linspace(0, 2*np.pi)
-x = np.cos(theta)
-y = np.sin(theta)
+x = np.cos(theta - np.pi/2)
+y = np.sin(theta - np.pi/2)
 z = theta
 
 fig, ax = plt.subplots(subplot_kw=dict(projection='3d'))
@@ -34,3 +34,18 @@
 markerline.set_markerfacecolor('none')
 
 plt.show()
+
+#############################################################################
+#
+# The orientation of the stems and baseline can be changed using *orientation*.
+# This determines in which direction the stems are projected from the head
+# points, towards the *bottom* baseline.
+#
+# For examples, by setting ``orientation='x'``, the stems are projected along
+# the *x*-direction, and the baseline is in the *yz*-plane.
+
+fig, ax = plt.subplots(subplot_kw=dict(projection='3d'))
+markerline, stemlines, baseline = ax.stem(x, y, z, bottom=-1, orientation='x')
+ax.set(xlabel='x', ylabel='y', zlabel='z')
+
+plt.show()
