Switch tilt naming back to roll, flip rotation handedness

scottshambaugh · scottshambaugh · commit 21f117780c5f · 2021-11-15T17:36:55.000-07:00
diff --git a/doc/users/next_whats_new/3d_plot_roll_angle.rst b/doc/users/next_whats_new/3d_plot_roll_angle.rst
@@ -1,11 +1,11 @@
-3D plots gained a 3rd "tilt" viewing angle
+3D plots gained a 3rd "roll" viewing angle
 ------------------------------------------
 
-3D plots can now be viewed from any orientation with the addition of a 3rd tilt
+3D plots can now be viewed from any orientation with the addition of a 3rd roll
 angle, which rotates the plot about the viewing axis. Interactive rotation
 using the mouse still only controls elevation and azimuth, meaning that this
 feature is relevant to users who create more complex camera angles
-programmatically. The default tilt angle of 0 is backwards-compatible with
+programmatically. The default roll angle of 0 is backwards-compatible with
 existing 3D plots.
 
 .. plot::
@@ -17,5 +17,5 @@ existing 3D plots.
     ax = fig.add_subplot(projection='3d')
     X, Y, Z = axes3d.get_test_data(0.05)
     ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10)
-    ax.view_init(elev=0, azim=0, tilt=30)
+    ax.view_init(elev=0, azim=0, roll=30)
     plt.show()
diff --git a/examples/mplot3d/2dcollections3d.py b/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, tilt=0)
+ax.view_init(elev=20., azim=-35, roll=0)
 
 plt.show()
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -54,7 +54,7 @@ class Axes3D(Axes):
 
     def __init__(
             self, fig, rect=None, *args,
-            elev=30, azim=-60, tilt=0, sharez=None, proj_type='persp',
+            elev=30, azim=-60, roll=0, sharez=None, proj_type='persp',
             box_aspect=None, computed_zorder=True,
             **kwargs):
         """
@@ -68,8 +68,8 @@ def __init__(
             Elevation viewing angle.
         azim : float, default: -60
             Azimuthal viewing angle.
-        tilt : float, default: 0
-            Tilt viewing angle.
+        roll : float, default: 0
+            Roll viewing angle.
         sharez : Axes3D, optional
             Other axes to share z-limits with.
         proj_type : {'persp', 'ortho'}
@@ -103,7 +103,7 @@ def __init__(
 
         self.initial_azim = azim
         self.initial_elev = elev
-        self.initial_tilt = tilt
+        self.initial_roll = roll
         self.set_proj_type(proj_type)
         self.computed_zorder = computed_zorder
 
@@ -115,7 +115,7 @@ 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_tilt)
+        self.view_init(self.initial_elev, self.initial_azim, self.initial_roll)
 
         self._sharez = sharez
         if sharez is not None:
@@ -979,7 +979,7 @@ def clabel(self, *args, **kwargs):
         """Currently not implemented for 3D axes, and returns *None*."""
         return None
 
-    def view_init(self, elev=None, azim=None, tilt=None, vertical_axis="z"):
+    def view_init(self, elev=None, azim=None, roll=None, vertical_axis="z"):
         """
         Set the elevation and azimuth of the axes in degrees (not radians).
 
@@ -995,8 +995,8 @@ def view_init(self, elev=None, azim=None, tilt=None, vertical_axis="z"):
             The azimuth angle in the horizontal plane in degrees.
             If None then the initial value as specified in the `Axes3D`
             constructor is used.
-        tilt : float, default: None
-            The tilt angle about the viewing direction in degrees.
+        roll : float, default: None
+            The roll angle about the viewing direction in degrees.
             If None then the initial value as specified in the `Axes3D`
             constructor is used.
         vertical_axis : {"z", "x", "y"}, default: "z"
@@ -1015,10 +1015,10 @@ def view_init(self, elev=None, azim=None, tilt=None, vertical_axis="z"):
         else:
             self.azim = azim
 
-        if tilt is None:
-            self.tilt = self.initial_tilt
+        if roll is None:
+            self.roll = self.initial_roll
         else:
-            self.tilt = tilt
+            self.roll = roll
 
         self._vertical_axis = _api.check_getitem(
             dict(x=0, y=1, z=2), vertical_axis=vertical_axis
@@ -1058,10 +1058,10 @@ def get_proj(self):
 
         # elev stores the elevation angle in the z plane
         # azim stores the azimuth angle in the x,y plane
-        # tilt stores the tilt angle about the view axis
+        # roll stores the roll angle about the view axis
         elev_rad = np.deg2rad(art3d._norm_angle(self.elev))
         azim_rad = np.deg2rad(art3d._norm_angle(self.azim))
-        tilt_rad = np.deg2rad(art3d._norm_angle(self.tilt))
+        roll_rad = np.deg2rad(art3d._norm_angle(self.roll))
 
         # Coordinates for a point that rotates around the box of data.
         # p0, p1 corresponds to rotating the box only around the
@@ -1091,7 +1091,7 @@ def get_proj(self):
         V = np.zeros(3)
         V[self._vertical_axis] = -1 if abs(elev_rad) > 0.5 * np.pi else 1
 
-        viewM = proj3d.view_transformation(eye, R, V, tilt_rad)
+        viewM = proj3d.view_transformation(eye, R, V, roll_rad)
         projM = self._projection(-self.dist, self.dist)
         M0 = np.dot(viewM, worldM)
         M = np.dot(projM, M0)
@@ -1179,15 +1179,15 @@ def _button_release(self, event):
     def _get_view(self):
         # docstring inherited
         return (self.get_xlim(), self.get_ylim(), self.get_zlim(),
-                self.elev, self.azim, self.tilt)
+                self.elev, self.azim, self.roll)
 
     def _set_view(self, view):
         # docstring inherited
-        xlim, ylim, zlim, elev, azim, tilt = view
+        xlim, ylim, zlim, elev, azim, roll = view
         self.set(xlim=xlim, ylim=ylim, zlim=zlim)
         self.elev = elev
         self.azim = azim
-        self.tilt = tilt
+        self.roll = roll
 
     def format_zdata(self, z):
         """
@@ -1216,10 +1216,10 @@ def format_coord(self, xd, yd):
             # ignore xd and yd and display angles instead
             norm_elev = art3d._norm_angle(self.elev)
             norm_azim = art3d._norm_angle(self.azim)
-            norm_tilt = art3d._norm_angle(self.tilt)
+            norm_roll = art3d._norm_angle(self.roll)
             return (f"elevation={norm_elev:.0f}\N{DEGREE SIGN}, "
                     f"azimuth={norm_azim:.0f}\N{DEGREE SIGN}, "
-                    f"tilt={norm_tilt:.0f}\N{DEGREE SIGN}"
+                    f"roll={norm_roll:.0f}\N{DEGREE SIGN}"
                     ).replace("-", "\N{MINUS SIGN}")
 
         # nearest edge
@@ -1273,9 +1273,9 @@ def _on_move(self, event):
             if dx == 0 and dy == 0:
                 return
 
-            tilt = np.deg2rad(self.tilt)
-            delev = -(dy/h)*180*np.cos(tilt) - (dx/w)*180*np.sin(tilt)
-            dazim = +(dy/h)*180*np.sin(tilt) - (dx/w)*180*np.cos(tilt)
+            roll = np.deg2rad(self.roll)
+            delev = -(dy/h)*180*np.cos(roll) + (dx/w)*180*np.sin(roll)
+            dazim = -(dy/h)*180*np.sin(roll) - (dx/w)*180*np.cos(roll)
             self.elev = self.elev + delev
             self.azim = self.azim + dazim
             self.get_proj()
@@ -3273,10 +3273,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 tilt.
-        with cbook._setattr_cm(self, elev=0, azim=0, tilt=0):
+        # consistency, this uses a fixed elevation, azimuth, and roll.
+        with cbook._setattr_cm(self, elev=0, azim=0, roll=0):
             invM = np.linalg.inv(self.get_proj())
-        # elev=azim=tilt=0 produces the Y-Z plane, so quiversize in 2D 'x' is
+        # elev=azim=roll=0 produces the Y-Z plane, so quiversize in 2D 'x' is
         # 'y' in 3D, hence the 1 index.
         quiversize = np.dot(invM, np.array([quiversize, 0, 0, 0]))[1]
         # Quivers use a fixed 15-degree arrow head, so scale up the length so
diff --git a/lib/mpl_toolkits/mplot3d/proj3d.py b/lib/mpl_toolkits/mplot3d/proj3d.py
@@ -68,18 +68,19 @@ def rotation_about_vector(v, angle):
     return R
 
 
-def view_transformation(E, R, V, tilt):
+def view_transformation(E, R, V, roll):
     n = (E - R)
     n = n/np.linalg.norm(n)
     u = np.cross(V, n)
     u = u/np.linalg.norm(u)
     v = np.cross(n, u)  # Will be a unit vector
 
-    # Save some computation for the default tilt=0
-    if tilt != 0:
-        Rtilt = rotation_about_vector(n, tilt)
-        u = np.dot(Rtilt, u)
-        v = np.dot(Rtilt, v)
+    # Save some computation for the default roll=0
+    if roll != 0:
+        # A positive rotation of the camera is a negative rotation of the world
+        Rroll = rotation_about_vector(n, -roll)
+        u = np.dot(Rroll, u)
+        v = np.dot(Rroll, v)
 
     Mr = np.eye(4)
     Mt = np.eye(4)
diff --git a/lib/mpl_toolkits/tests/baseline_images/test_mplot3d/bar3d_shaded.png b/lib/mpl_toolkits/tests/baseline_images/test_mplot3d/bar3d_shaded.png
diff --git a/lib/mpl_toolkits/tests/test_mplot3d.py b/lib/mpl_toolkits/tests/test_mplot3d.py
@@ -68,9 +68,9 @@ def test_bar3d_shaded():
         1, len(views),
         subplot_kw=dict(projection='3d')
     )
-    for ax, (elev, azim, tilt) in zip(axs, views):
+    for ax, (elev, azim, roll) in zip(axs, views):
         ax.bar3d(x2d, y2d, x2d * 0, 1, 1, z, shade=True)
-        ax.view_init(elev=elev, azim=azim, tilt=tilt)
+        ax.view_init(elev=elev, azim=azim, roll=roll)
     fig.canvas.draw()
 
 
@@ -387,10 +387,10 @@ def test_marker_draw_order_data_reversed(fig_test, fig_ref, azim):
     color = ['b', 'y']
     ax = fig_test.add_subplot(projection='3d')
     ax.scatter(x, y, z, s=3500, c=color)
-    ax.view_init(elev=0, azim=azim, tilt=0)
+    ax.view_init(elev=0, azim=azim, roll=0)
     ax = fig_ref.add_subplot(projection='3d')
     ax.scatter(x[::-1], y[::-1], z[::-1], s=3500, c=color[::-1])
-    ax.view_init(elev=0, azim=azim, tilt=0)
+    ax.view_init(elev=0, azim=azim, roll=0)
 
 
 @check_figures_equal(extensions=['png'])
@@ -410,11 +410,11 @@ def test_marker_draw_order_view_rotated(fig_test, fig_ref):
     # axis are not exactly invariant under 180 degree rotation -> deactivate
     ax.set_axis_off()
     ax.scatter(x, y, z, s=3500, c=color)
-    ax.view_init(elev=0, azim=azim, tilt=0)
+    ax.view_init(elev=0, azim=azim, roll=0)
     ax = fig_ref.add_subplot(projection='3d')
     ax.set_axis_off()
     ax.scatter(x, y, z, s=3500, c=color[::-1])  # color reversed
-    ax.view_init(elev=0, azim=azim - 180, tilt=0)  # view rotated by 180 deg
+    ax.view_init(elev=0, azim=azim - 180, roll=0)  # view rotated by 180 deg
 
 
 @mpl3d_image_comparison(['plot_3d_from_2d.png'], tol=0.015)
@@ -860,8 +860,8 @@ def _test_proj_make_M():
     E = np.array([1000, -1000, 2000])
     R = np.array([100, 100, 100])
     V = np.array([0, 0, 1])
-    tilt = 0
-    viewM = proj3d.view_transformation(E, R, V, tilt)
+    roll = 0
+    viewM = proj3d.view_transformation(E, R, V, roll)
     perspM = proj3d.persp_transformation(100, -100)
     M = np.dot(perspM, viewM)
     return M
@@ -926,8 +926,8 @@ def test_proj_axes_cube_ortho():
     E = np.array([200, 100, 100])
     R = np.array([0, 0, 0])
     V = np.array([0, 0, 1])
-    tilt = 0
-    viewM = proj3d.view_transformation(E, R, V, tilt)
+    roll = 0
+    viewM = proj3d.view_transformation(E, R, V, roll)
     orthoM = proj3d.ortho_transformation(-1, 1)
     M = np.dot(orthoM, viewM)
 
@@ -1046,7 +1046,7 @@ def test_axes3d_isometric():
     for s, e in combinations(np.array(list(product(r, r, r))), 2):
         if abs(s - e).sum() == r[1] - r[0]:
             ax.plot3D(*zip(s, e), c='k')
-    ax.view_init(elev=np.degrees(np.arctan(1. / np.sqrt(2))), azim=-45, tilt=0)
+    ax.view_init(elev=np.degrees(np.arctan(1. / np.sqrt(2))), azim=-45, roll=0)
     ax.grid(True)
 
 
@@ -1598,7 +1598,7 @@ def test_computed_zorder():
                 linestyle='--',
                 color='green',
                 zorder=4)
-        ax.view_init(elev=20, azim=-20, tilt=0)
+        ax.view_init(elev=20, azim=-20, roll=0)
         ax.axis('off')
 
 
@@ -1685,7 +1685,7 @@ def test_view_init_vertical_axis(
     """
     rtol = 2e-06
     ax = plt.subplot(1, 1, 1, projection="3d")
-    ax.view_init(elev=0, azim=0, tilt=0, vertical_axis=vertical_axis)
+    ax.view_init(elev=0, azim=0, roll=0, vertical_axis=vertical_axis)
     ax.figure.canvas.draw()
 
     # Assert the projection matrix:
