Consistent azim-elev-roll order with minimal changes

MischaMegens2 · MischaMegens2 · commit e9991b36dfce · 2024-08-01T21:46:46.000-07:00
Implement changes requested for PR #28395: - remove incohesive section from view_angles.rst - move some of the information to .mplot3d.axes3d.Axes3D.view_init - remove redundant kwargs as in .view_init(elev=elev, azim=azim, roll=roll) - cleanup test_axes3d_primary_views() - remove outdated next_whats_new item
diff --git a/doc/api/toolkits/mplot3d/view_angles.rst b/doc/api/toolkits/mplot3d/view_angles.rst
@@ -28,28 +28,6 @@ as well as roll, and all three angles can be set programmatically::
     ax = plt.figure().add_subplot(projection='3d')
     ax.view_init(elev=30, azim=45, roll=15)
 
-Rotation of the plot
-====================
-
-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)
-
-(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_keyword_arguments.rst b/doc/users/next_whats_new/view_angles_keyword_arguments.rst
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1119,15 +1119,44 @@ def view_init(self, elev=None, azim=None, roll=None, vertical_axis="z",
         A roll angle of 0, 90, 180, or 270 degrees will rotate these views
         while keeping the axes at right angles.
 
-        It is recommended to provide these parameter as keyword arguments:
+        The *azim*, *elev*, *roll* angles correspond to rotations of the scene
+        observed by a stationary camera, as follows (assuming a default vertical
+        axis of 'z'). 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).
+
+        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)
+
+        (with angles given in radians instead of degrees). That is, the angles
+        are a kind of `Tait-Bryan angles
+        <https://en.wikipedia.org/wiki/Euler_angles#Tait%E2%80%93Bryan_angles>`_:
+        −z, +y', +x", rather than classic `Euler angles
+        <https://en.wikipedia.org/wiki/Euler_angles>`_.
+
+        To avoid confusion, it makes sense to provide the view angles as keyword
+        arguments:
         ``.view_init(azim=-60, elev=30, roll=0, ...)``
-        in this order (i.e., the order in which the rotations actually are
-        applied).
+        This specific order is consistent with the order in which the rotations
+        actually are applied. Moreover, this particular order appears to be most
+        common, see :ghissue:`28353`, and it is consistent with the ordering in
+        `matplotlib.colors.LightSource`.
+
         For backwards compatibility, positional arguments in the old sequence
-        (first elev, then azim) will still be accepted; unfortunately,
-        this order does not match the actual order of the applied rotations,
-        and it differs from that used in other programs (`azim, elev`).
-        It would be nice if the sensible ordering could take over eventually.
+        (first ``elev``, then ``azim``) will still be accepted; but preferably,
+        use keyword arguments, to avoid confusion as to which angle is which.
+        Unfortunately, the order of the positional arguments does not match
+        the actual order of the applied rotations, and it differs from that
+        used in other programs (``azim, elev``). It would be nice if the sensible
+        (keyword) ordering could take over eventually.
+
 
         Parameters
         ----------
@@ -1599,13 +1628,8 @@ def _on_move(self, event):
             elev = np.rad2deg(elev)
             roll = np.rad2deg(roll)
             vertical_axis = self._axis_names[self._vertical_axis]
-            self.view_init(
-                elev=elev,
-                azim=azim,
-                roll=roll,
-                vertical_axis=vertical_axis,
-                share=True,
-            )
+            self.view_init(elev, azim, roll, vertical_axis=vertical_axis,
+                           share=True)
             self.stale = True
 
         # Pan
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
@@ -127,12 +127,12 @@ def test_axes3d_primary_views():
     # When viewing primary planes, draw the two visible axes so they intersect
     # at their low values
     fig, axs = plt.subplots(2, 3, subplot_kw={'projection': '3d'})
-    for i, ax in enumerate(axs.flat):
+    for ax, (azim, elev, roll) in zip(axs.flat, views):
         ax.set_xlabel('x')
         ax.set_ylabel('y')
         ax.set_zlabel('z')
         ax.set_proj_type('ortho')
-        ax.view_init(elev=views[i][1], azim=views[i][0], roll=views[i][2])
+        ax.view_init(elev, azim, roll)
     plt.tight_layout()
 
 
@@ -176,7 +176,7 @@ def test_bar3d_shaded():
     )
     for ax, (azim, elev, roll) in zip(axs, views):
         ax.bar3d(x2d, y2d, x2d * 0, 1, 1, z, shade=True)
-        ax.view_init(elev=elev, azim=azim, roll=roll)
+        ax.view_init(elev, azim, roll)
     fig.canvas.draw()
 
 
@@ -1832,11 +1832,11 @@ def test_shared_view(fig_test, fig_ref):
     ax2 = fig_test.add_subplot(132, projection="3d", shareview=ax1)
     ax3 = fig_test.add_subplot(133, projection="3d")
     ax3.shareview(ax1)
-    ax2.view_init(elev=elev, azim=azim, roll=roll, share=True)
+    ax2.view_init(elev, azim, roll, share=True)
 
     for subplot_num in (131, 132, 133):
         ax = fig_ref.add_subplot(subplot_num, projection="3d")
-        ax.view_init(elev=elev, azim=azim, roll=roll)
+        ax.view_init(elev, azim, roll)
 
 
 def test_shared_axes_retick():
