Change order of mplot3d view angles to match order of rotations

MischaMegens2 · MischaMegens2 · commit 89a4d55199b5 · 2024-07-25T13:19:36.000-07:00
Change order of mplot3d view angles to azim-elev-roll, the order in which rotations occur, but keep the elev, azim positional order in view_init(), for backwards compatibility; use keyword arguments throughout, to avoid confusion:
- in axes3d.py
- in tests
- in documentation
- in examples

Encourage the use of keyword arguments in the documentation for view_init()

Add description of rotation to view_angles.rst (using Euler angles as well as quaternions)

Add next_whats_new\view_angles_keyword_arguments.rst, encouraging keyword arguments,
and explaining the view angles order (with reference)
diff --git a/doc/api/toolkits/mplot3d/view_angles.rst b/doc/api/toolkits/mplot3d/view_angles.rst
@@ -8,7 +8,7 @@ How to define the view angle
 ============================
 
 The position of the viewport "camera" in a 3D plot is defined by three angles:
-*elevation*, *azimuth*, and *roll*. From the resulting position, it always
+*azimuth*, *elevation*, and *roll*. From the resulting position, it always
 points towards the center of the plot box volume. The angle direction is a
 common convention, and is shared with
 `PyVista <https://docs.pyvista.org/api/core/camera.html>`_ and
@@ -28,11 +28,33 @@ 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
 ===================
 
-To look directly at the primary view planes, the required elevation, azimuth,
+To look directly at the primary view planes, the required azimuth, elevation,
 and roll angles are shown in the diagram of an "unfolded" plot below. These are
 further documented in the `.mplot3d.axes3d.Axes3D.view_init` API.
 
diff --git a/doc/users/next_whats_new/view_angles_keyword_arguments.rst b/doc/users/next_whats_new/view_angles_keyword_arguments.rst
@@ -0,0 +1,17 @@
+Explicit view angle keyword arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is recommended to provide the 'view angles' for three-dimensional plots
+(with ``mplot3d``) as keyword arguments
+``.view_init(azim=..., elev=..., roll=..., ...)``
+in this order. This is consistent with the order in which the rotations take
+place [1]; also, it matches the order used in other programs (first azim,
+then elev).
+For backwards compatibility, positional arguments in the old sequence
+(`elev, azim`) will still be accepted. But preferably, use keyword arguments
+to avoid confusion as to which angle is which.
+
+
+[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/2dcollections3d.py b/galleries/examples/mplot3d/2dcollections3d.py
@@ -43,6 +43,6 @@
 
 # Customize the view angle so it's easier to see that the scatter points lie
 # on the plane y=0
-ax.view_init(elev=20., azim=-35, roll=0)
+ax.view_init(elev=20, azim=-35, roll=0)
 
 plt.show()
diff --git a/galleries/examples/mplot3d/box3d.py b/galleries/examples/mplot3d/box3d.py
@@ -68,7 +68,7 @@
 )
 
 # Set zoom and angle view
-ax.view_init(40, -30, 0)
+ax.view_init(elev=40, azim=-30, roll=0)
 ax.set_box_aspect(None, zoom=0.9)
 
 # Colorbar
diff --git a/galleries/examples/mplot3d/rotate_axes3d_sgskip.py b/galleries/examples/mplot3d/rotate_axes3d_sgskip.py
@@ -33,19 +33,19 @@
     angle_norm = (angle + 180) % 360 - 180
 
     # Cycle through a full rotation of elevation, then azimuth, roll, and all
-    elev = azim = roll = 0
+    azim = elev = roll = 0
     if angle <= 360:
         elev = angle_norm
     elif angle <= 360*2:
         azim = angle_norm
     elif angle <= 360*3:
         roll = angle_norm
     else:
-        elev = azim = roll = angle_norm
+        azim = elev = roll = angle_norm
 
     # Update the axis view and title
-    ax.view_init(elev, azim, roll)
-    plt.title('Elevation: %d°, Azimuth: %d°, Roll: %d°' % (elev, azim, roll))
+    ax.view_init(elev=elev, azim=azim, roll=roll)
+    plt.title('Azimuth: %d°, Elevation: %d°, Roll: %d°' % (azim, elev, roll))
 
     plt.draw()
     plt.pause(.001)
diff --git a/galleries/examples/mplot3d/view_planes_3d.py b/galleries/examples/mplot3d/view_planes_3d.py
@@ -4,7 +4,7 @@
 ======================
 
 This example generates an "unfolded" 3D plot that shows each of the primary 3D
-view planes. The elevation, azimuth, and roll angles required for each view are
+view planes. The azimuth, elevation, and roll angles required for each view are
 labeled. You could print out this image and fold it into a box where each plane
 forms a side of the box.
 """
@@ -16,13 +16,13 @@ def annotate_axes(ax, text, fontsize=18):
     ax.text(x=0.5, y=0.5, z=0.5, s=text,
             va="center", ha="center", fontsize=fontsize, color="black")
 
-# (plane, (elev, azim, roll))
-views = [('XY',   (90, -90, 0)),
-         ('XZ',    (0, -90, 0)),
-         ('YZ',    (0,   0, 0)),
-         ('-XY', (-90,  90, 0)),
-         ('-XZ',   (0,  90, 0)),
-         ('-YZ',   (0, 180, 0))]
+# (plane, (azim, elev, roll))
+views = [('XY',   (-90,  90, 0)),
+         ('XZ',   (-90,   0, 0)),
+         ('YZ',     (0,   0, 0)),
+         ('-XY',   (90, -90, 0)),
+         ('-XZ',   (90,   0, 0)),
+         ('-YZ',   (180,  0, 0))]
 
 layout = [['XY',  '.',   'L',   '.'],
           ['XZ', 'YZ', '-XZ', '-YZ'],
@@ -34,10 +34,10 @@ def annotate_axes(ax, text, fontsize=18):
     axd[plane].set_ylabel('y')
     axd[plane].set_zlabel('z')
     axd[plane].set_proj_type('ortho')
-    axd[plane].view_init(elev=angles[0], azim=angles[1], roll=angles[2])
+    axd[plane].view_init(elev=angles[1], azim=angles[0], 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'):
@@ -50,7 +50,8 @@ def annotate_axes(ax, text, fontsize=18):
     axd[plane].set_xticklabels([])
     axd[plane].set_xlabel('')
 
-label = 'mplot3d primary view planes\n' + 'ax.view_init(elev, azim, roll)'
+label = 'mplot3d primary view planes\n' + \
+    'ax.view_init(elev=elev, azim=azim, roll=roll)'
 annotate_axes(axd['L'], label, fontsize=18)
 axd['L'].set_axis_off()
 
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -139,7 +139,11 @@ def __init__(
 
         # inhibit autoscale_view until the axes are defined
         # they can't be defined until Axes.__init__ has been called
-        self.view_init(self.initial_elev, self.initial_azim, self.initial_roll)
+        self.view_init(
+            elev=self.initial_elev,
+            azim=self.initial_azim,
+            roll=self.initial_roll,
+        )
 
         self._sharez = sharez
         if sharez is not None:
@@ -1094,25 +1098,37 @@ def clabel(self, *args, **kwargs):
     def view_init(self, elev=None, azim=None, roll=None, vertical_axis="z",
                   share=False):
         """
-        Set the elevation and azimuth of the Axes in degrees (not radians).
+        Set the azimuth, elevation, and roll of the Axes, in degrees (not radians).
 
         This can be used to rotate the Axes programmatically.
 
-        To look normal to the primary planes, the following elevation and
-        azimuth angles can be used. A roll angle of 0, 90, 180, or 270 deg
-        will rotate these views while keeping the axes at right angles.
+        To look normal to the primary planes, the following azimuth and
+        elevation angles can be used:
 
         ==========   ====  ====
-        view plane   elev  azim
+        view plane   azim  elev
         ==========   ====  ====
-        XY           90    -90
-        XZ           0     -90
-        YZ           0     0
-        -XY          -90   90
-        -XZ          0     90
-        -YZ          0     180
+         XY          -90    90
+         XZ          -90     0
+         YZ            0     0
+        -XY           90   -90
+        -XZ           90     0
+        -YZ          180     0
         ==========   ====  ====
 
+        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:
+        ``.view_init(azim=-60, elev=30, roll=0, ...)``
+        in this order (i.e., the order in which the rotations actually are
+        applied).
+        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.
+
         Parameters
         ----------
         elev : float, default: None
@@ -1145,10 +1161,10 @@ def view_init(self, elev=None, azim=None, roll=None, vertical_axis="z",
 
         self._dist = 10  # The camera distance from origin. Behaves like zoom
 
-        if elev is None:
-            elev = self.initial_elev
         if azim is None:
             azim = self.initial_azim
+        if elev is None:
+            elev = self.initial_elev
         if roll is None:
             roll = self.initial_roll
         vertical_axis = _api.check_getitem(
@@ -1163,8 +1179,8 @@ def view_init(self, elev=None, azim=None, roll=None, vertical_axis="z",
             axes = [self]
 
         for ax in axes:
-            ax.elev = elev
             ax.azim = azim
+            ax.elev = elev
             ax.roll = roll
             ax._vertical_axis = vertical_axis
 
@@ -1229,15 +1245,15 @@ def get_proj(self):
         # Look into the middle of the world coordinates:
         R = 0.5 * box_aspect
 
-        # elev: elevation angle in the z plane.
         # azim: azimuth angle in the xy plane.
+        # elev: elevation angle in the z plane.
         # Coordinates for a point that rotates around the box of data.
         # p0, p1 corresponds to rotating the box only around the vertical axis.
         # p2 corresponds to rotating the box only around the horizontal axis.
-        elev_rad = np.deg2rad(self.elev)
         azim_rad = np.deg2rad(self.azim)
-        p0 = np.cos(elev_rad) * np.cos(azim_rad)
-        p1 = np.cos(elev_rad) * np.sin(azim_rad)
+        elev_rad = np.deg2rad(self.elev)
+        p0 = np.cos(azim_rad) * np.cos(elev_rad)
+        p1 = np.sin(azim_rad) * np.cos(elev_rad)
         p2 = np.sin(elev_rad)
 
         # When changing vertical axis the coordinates changes as well.
@@ -1339,8 +1355,13 @@ def shareview(self, other):
         self._shared_axes["view"].join(self, other)
         self._shareview = other
         vertical_axis = self._axis_names[other._vertical_axis]
-        self.view_init(elev=other.elev, azim=other.azim, roll=other.roll,
-                       vertical_axis=vertical_axis, share=True)
+        self.view_init(
+            elev=other.elev,
+            azim=other.azim,
+            roll=other.roll,
+            vertical_axis=vertical_axis,
+            share=True,
+        )
 
     def clear(self):
         # docstring inherited.
@@ -1392,8 +1413,8 @@ def _set_view(self, view):
         # docstring inherited
         props, (elev, azim, roll) = view
         self.set(**props)
-        self.elev = elev
         self.azim = azim
+        self.elev = elev
         self.roll = roll
 
     def format_zdata(self, z):
@@ -1430,11 +1451,11 @@ def _rotation_coords(self):
         """
         Return the rotation angles as a string.
         """
-        norm_elev = art3d._norm_angle(self.elev)
         norm_azim = art3d._norm_angle(self.azim)
+        norm_elev = art3d._norm_angle(self.elev)
         norm_roll = art3d._norm_angle(self.roll)
-        coords = (f"elevation={norm_elev:.0f}\N{DEGREE SIGN}, "
-                  f"azimuth={norm_azim:.0f}\N{DEGREE SIGN}, "
+        coords = (f"azimuth={norm_azim:.0f}\N{DEGREE SIGN}, "
+                  f"elevation={norm_elev:.0f}\N{DEGREE SIGN}, "
                   f"roll={norm_roll:.0f}\N{DEGREE SIGN}"
                   ).replace("-", "\N{MINUS SIGN}")
         return coords
@@ -1561,10 +1582,10 @@ def _on_move(self, event):
                 return
 
             # Convert to quaternion
-            elev = np.deg2rad(self.elev)
             azim = np.deg2rad(self.azim)
+            elev = np.deg2rad(self.elev)
             roll = np.deg2rad(self.roll)
-            q = _Quaternion.from_cardan_angles(elev, azim, roll)
+            q = _Quaternion.from_cardan_angles(azim, elev, roll)
 
             # Update quaternion - a variation on Ken Shoemake's ARCBALL
             current_vec = self._arcball(self._sx/w, self._sy/h)
@@ -1573,7 +1594,7 @@ def _on_move(self, event):
             q = dq * q
 
             # Convert to elev, azim, roll
-            elev, azim, roll = q.as_cardan_angles()
+            azim, elev, roll = q.as_cardan_angles()
             azim = np.rad2deg(azim)
             elev = np.rad2deg(elev)
             roll = np.rad2deg(roll)
@@ -3662,10 +3683,10 @@ def _extract_errs(err, data, lomask, himask):
         quiversize = np.mean(np.diff(quiversize, axis=0))
         # quiversize is now in Axes coordinates, and to convert back to data
         # coordinates, we need to run it through the inverse 3D transform. For
-        # consistency, this uses a fixed elevation, azimuth, and roll.
+        # consistency, this uses a fixed azimuth, elevation, and roll.
         with cbook._setattr_cm(self, elev=0, azim=0, roll=0):
             invM = np.linalg.inv(self.get_proj())
-        # elev=azim=roll=0 produces the Y-Z plane, so quiversize in 2D 'x' is
+        # azim=elev=roll=0 produces the Y-Z plane, so quiversize in 2D 'x' is
         # 'y' in 3D, hence the 1 index.
         quiversize = np.dot(invM, [quiversize, 0, 0, 0])[1]
         # Quivers use a fixed 15-degree arrow head, so scale up the length so
@@ -4000,7 +4021,7 @@ def rotate_from_to(cls, r1, r2):
         return q
 
     @classmethod
-    def from_cardan_angles(cls, elev, azim, roll):
+    def from_cardan_angles(cls, azim, elev, roll):
         """
         Converts the angles to a quaternion
             q = exp((roll/2)*e_x)*exp((elev/2)*e_y)*exp((-azim/2)*e_z)
@@ -4027,4 +4048,4 @@ def as_cardan_angles(self):
         azim = np.arctan2(2*(-qw*qz+qx*qy), qw*qw+qx*qx-qy*qy-qz*qz)
         elev = np.arcsin( 2*( qw*qy+qz*qx)/(qw*qw+qx*qx+qy*qy+qz*qz))  # noqa E201
         roll = np.arctan2(2*( qw*qx-qy*qz), qw*qw-qx*qx-qy*qy+qz*qz)   # noqa E201
-        return elev, azim, roll
+        return azim, elev, roll
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_art3d.py b/lib/mpl_toolkits/mplot3d/tests/test_art3d.py
@@ -10,9 +10,9 @@ def test_scatter_3d_projection_conservation():
     fig = plt.figure()
     ax = fig.add_subplot(projection='3d')
     # fix axes3d projection
-    ax.roll = 0
-    ax.elev = 0
     ax.azim = -45
+    ax.elev = 0
+    ax.roll = 0
     ax.stale = True
 
     x = [0, 1, 2, 3, 4]
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py

Original file line number	Diff line number	Diff line change
`@@ -68,7 +68,7 @@`
`68`	`68`	`)`
`69`	`69`
`70`	`70`	`# Set zoom and angle view`
`71`		`-ax.view_init(40, -30, 0)`
	`71`	`+ax.view_init(elev=40, azim=-30, roll=0)`
`72`	`72`	`ax.set_box_aspect(None, zoom=0.9)`
`73`	`73`
`74`	`74`	`# Colorbar`