Update view_angles documentation

MischaMegens2 · MischaMegens2 · commit 5c17e597c7a8 · 2024-06-22T21:28:23.000-07:00
- clarify rotations in view_angles.rst using Euler angles (connection with quaternion still mentioned but less prominently)
- fix reference in whats_new\view_angles_order.rst
- add keywords in plot annotation in view_planes_3d.py example (and documentation)
diff --git a/doc/api/toolkits/mplot3d/view_angles.rst b/doc/api/toolkits/mplot3d/view_angles.rst
@@ -31,15 +31,24 @@ as well as roll, and all three angles can be set programmatically::
 Rotation of the plot
 ====================
 
-The angles relate to the (intrinsic) rotation of the plot via the
-quaternion (with angles here given in radians instead of degrees):
+The *azim*, *elev*, *roll* rotation order corresponds to rotation of the scene
+observed by a stationary camera. First, a left-handed rotation about the z axis is
+applied (*azim*), then a right-handed rotation about the (camera) y axis (*elev*), then a
+right-handed rotation about the (camera) x axis (*roll*). Here, the z, y, and x axis are fixed
+axes (not the axes that rotate together with the original scene).
+
+This can also be thought of as orbiting a camera around a fixed scene, by reversing
+the order of operations. First the camera is rotated about the scene's +x axis
+(*roll*), then the +y axis (*elev*), then the −z axis (*azim*).
+
+If you would like to make the connection with quaternions (because
+`Euler angles are horrible <https://github.com/moble/quaternion/wiki/Euler-angles-are-horrible>`_):
+the *azim*, *elev*, *roll* angles relate to the (intrinsic) rotation of the plot via:
 
      *q* = exp( +roll **x̂** / 2) exp( +elev **ŷ** / 2) exp( −azim **ẑ** / 2)
 
-i.e., the angles are a kind of Tait-Bryan angles, −z, +y', +x", rather than
-classic Euler angles. (If you want to do anything significant with three-dimensional
-rotations, you are `well advised <https://github.com/moble/quaternion/wiki/Euler-angles-are-horrible>`_
-to stay clear of Tait-Bryan and Euler angles, and to use quaternions instead.)
+(with angles given in radians instead of degrees). That is, the angles are a kind of
+Tait-Bryan angles: −z, +y', +x", rather than classic Euler angles.
 
 
 Primary view planes
diff --git a/doc/users/next_whats_new/view_angles_order.rst b/doc/users/next_whats_new/view_angles_order.rst
@@ -12,6 +12,6 @@ For backward compatibility, the old ``elev``, ``azim`` etc. positional arguments
 will still be accepted (but it is not recommended).
 
 
-[1]: See :doc: `/api/toolkits/mplot3d/view_angles` for details. Also, this particular
+[1]: See :doc:`/api/toolkits/mplot3d/view_angles` for details. Also, this particular
 order appears to be most common; and it is consistent with the ordering in
 matplotlib's colors.py - see also :ghissue:`28353`.
diff --git a/galleries/examples/mplot3d/view_planes_3d.py b/galleries/examples/mplot3d/view_planes_3d.py
@@ -37,7 +37,7 @@ def annotate_axes(ax, text, fontsize=18):
     axd[plane].view_init(azim=angles[0], elev=angles[1], roll=angles[2])
     axd[plane].set_box_aspect(None, zoom=1.25)
 
-    label = f'{plane}\n{angles}'
+    label = f'{plane}\nazim={angles[0]}\nelev={angles[1]}\nroll={angles[2]}'
     annotate_axes(axd[plane], label, fontsize=14)
 
 for plane in ('XY', '-XY'):
