Change order of mplot3d view angles to match order of rotations

MischaMegens2 · MischaMegens2 · commit 431bed4ee20d · 2024-06-22T21:28:22.000-07:00
- Change order of mplot3d view angles to azim-elev-roll, the order in which rotations occur: - in axes3d.py - in tests - in documentation - in examples - Add description of rotation to view_angles.rst - Put in ref. to https://github.com/moble/quaternion/wiki/Euler-angles-are-horrible - Update view_init() documentation - Add doc\api\next_api_changes\deprecations warning that Axes3D.view_init preferably should be used with keyword arguments - Add next_whats_new\view_angles_order.rst explaining the new view angles order
diff --git a/doc/api/next_api_changes/deprecations/xxxxx-MM.rst b/doc/api/next_api_changes/deprecations/xxxxx-MM.rst
@@ -0,0 +1,8 @@
+``Axes3D.view_init``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... preferably should be used with keyword arguments, azim=, elev=, roll=,
+in this order (i.e., the order in which the rotations are applied).
+
+For backwards compatibility, positional arguments in the old sequence
+(first elev, then azim) will still be accepted
+(but a deprecation warning will be given).
diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst
@@ -53,7 +53,7 @@ the toolbar pan and zoom buttons are not used.
    In addition, help and patches would be greatly appreciated!
 
 
-`axes3d.Axes3D` (fig[, rect, elev, azim, roll, ...])    3D Axes object.
+`axes3d.Axes3D` (fig[, rect, azim, elev, roll, ...])    3D Axes object.
 
 
 .. module:: mpl_toolkits.mplot3d.axis3d
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
@@ -26,13 +26,26 @@ as well as roll, and all three angles can be set programmatically::
 
     import matplotlib.pyplot as plt
     ax = plt.figure().add_subplot(projection='3d')
-    ax.view_init(elev=30, azim=45, roll=15)
+    ax.view_init(azim=45, elev=30, roll=15)
+
+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):
+
+     *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.)
 
 
 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_order.rst b/doc/users/next_whats_new/view_angles_order.rst
@@ -0,0 +1,17 @@
+Order of view angles
+~~~~~~~~~~~~~~~~~~~~
+
+The order of the 'view angles' for three-dimensional plots (with ``mplot3d``)
+has been changed to ``azim=, elev=, roll=``. This is consistent with the order
+in which the rotations take place [1]. It is suggested to use keyword arguments
+(in this order) for the angles, so there will be no confusion as to which angle
+is which (even if the order would be different).
+
+
+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
+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(azim=-35, elev=20., 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(azim=-30, elev=40, 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(azim=azim, elev=elev, 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,7 +34,7 @@ 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(azim=angles[0], elev=angles[1], roll=angles[2])
     axd[plane].set_box_aspect(None, zoom=1.25)
 
     label = f'{plane}\n{angles}'
@@ -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(azim=azim, elev=elev, 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
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_art3d.py b/lib/mpl_toolkits/mplot3d/tests/test_art3d.py
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(azim=-30, elev=40, roll=0)`
`72`	`72`	`ax.set_box_aspect(None, zoom=0.9)`
`73`	`73`
`74`	`74`	`# Colorbar`