Add ability to roll the camera in 3D plots (matplotlib#21426)

* Add a roll angle for viewing 3D plots

Add roll angle for 3d plot examples

Align rotation of 3D plot by mouse with rolled axes

3D plot roll angle flake8, tests, and whats new

Fix plot flipping at elev>270

Test for 3d plot with elev>270

Normalize the displayed angles for 3d plots when rotating with mouse

Make elev, azim, roll ordering consistent everywhere

Rename roll angle to tilt

Speed up calculations for default tilt=0

Code review updates

Switch tilt naming back to roll, flip rotation handedness

Switch tilt naming back to roll, flip rotation handedness

* Better elev/azim/roll docstrings

Co-authored-by: Scott Shambaugh <[email protected]>

Author: scottshambaugh

doc/users/next_whats_new/3d_plot_roll_angle.rst

@@ -0,0 +1,21 @@
+3D plots gained a 3rd "roll" viewing angle
+------------------------------------------
+
+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 roll angle of 0 is backwards-compatible with
+existing 3D plots.
+
+.. plot::
+    :include-source: true
+    
+    from mpl_toolkits.mplot3d import axes3d
+    import matplotlib.pyplot as plt
+    fig = plt.figure()
+    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, roll=30)
+    plt.show()

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)
+ax.view_init(elev=20., azim=-35, roll=0)
 
 plt.show()

examples/mplot3d/box3d.py

@@ -68,7 +68,7 @@
 )
 
 # Set distance and angle view
-ax.view_init(40, -30)
+ax.view_init(40, -30, 0)
 ax.dist = 11
 
 # Colorbar

examples/mplot3d/rotate_axes3d_sgskip.py

@@ -23,6 +23,6 @@
 
 # rotate the axes and update
 for angle in range(0, 360):
-    ax.view_init(30, angle)
+    ax.view_init(30, angle, 0)
     plt.draw()
     plt.pause(.001)

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -55,7 +55,7 @@ class Axes3D(Axes):
 
     def __init__(
             self, fig, rect=None, *args,
-            azim=-60, elev=30, sharez=None, proj_type='persp',
+            elev=30, azim=-60, roll=0, sharez=None, proj_type='persp',
             box_aspect=None, computed_zorder=True,
             **kwargs):
         """
@@ -65,10 +65,19 @@ def __init__(
             The parent figure.
         rect : (float, float, float, float)
             The ``(left, bottom, width, height)`` axes position.
-        azim : float, default: -60
-            Azimuthal viewing angle.
         elev : float, default: 30
-            Elevation viewing angle.
+            The elevation angle in degrees rotates the camera above and below
+            the x-y plane, with a positive angle corresponding to a location
+            above the plane.
+        azim : float, default: -60
+            The azimuthal angle in degrees rotates the camera about the z axis,
+            with a positive angle corresponding to a right-handed rotation. In
+            other words, a positive azimuth rotates the camera about the origin
+            from its location along the +x axis towards the +y axis.
+        roll : float, default: 0
+            The roll angle in degrees rotates the camera about the viewing
+            axis. A positive angle spins the camera clockwise, causing the
+            scene to rotate counter-clockwise.
         sharez : Axes3D, optional
             Other axes to share z-limits with.
         proj_type : {'persp', 'ortho'}
@@ -102,6 +111,7 @@ def __init__(
 
         self.initial_azim = azim
         self.initial_elev = elev
+        self.initial_roll = roll
         self.set_proj_type(proj_type)
         self.computed_zorder = computed_zorder
 
@@ -113,7 +123,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.view_init(self.initial_elev, self.initial_azim, self.initial_roll)
 
         self._sharez = sharez
         if sharez is not None:
@@ -983,7 +993,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, 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).
 
@@ -992,12 +1002,26 @@ def view_init(self, elev=None, azim=None, vertical_axis="z"):
         Parameters
         ----------
         elev : float, default: None
-            The elevation angle in the vertical plane in degrees.
-            If None then the initial value as specified in the `Axes3D`
+            The elevation angle in degrees rotates the camera above the plane
+            pierced by the vertical axis, with a positive angle corresponding
+            to a location above that plane. For example, with the default
+            vertical axis of 'z', the elevation defines the angle of the camera
+            location above the x-y plane.
+            If None, then the initial value as specified in the `Axes3D`
             constructor is used.
         azim : float, default: None
-            The azimuth angle in the horizontal plane in degrees.
-            If None then the initial value as specified in the `Axes3D`
+            The azimuthal angle in degrees rotates the camera about the
+            vertical axis, with a positive angle corresponding to a
+            right-handed rotation. For example, with the default vertical axis
+            of 'z', a positive azimuth rotates the camera about the origin from
+            its location along the +x axis towards the +y axis.
+            If None, then the initial value as specified in the `Axes3D`
+            constructor is used.
+        roll : float, default: None
+            The roll angle in degrees rotates the camera about the viewing
+            axis. A positive angle spins the camera clockwise, causing the
+            scene to rotate counter-clockwise.
+            If None, then the initial value as specified in the `Axes3D`
             constructor is used.
         vertical_axis : {"z", "x", "y"}, default: "z"
             The axis to align vertically. *azim* rotates about this axis.
@@ -1015,6 +1039,11 @@ def view_init(self, elev=None, azim=None, vertical_axis="z"):
         else:
             self.azim = azim
 
+        if roll is None:
+            self.roll = self.initial_roll
+        else:
+            self.roll = roll
+
         self._vertical_axis = _api.check_getitem(
             dict(x=0, y=1, z=2), vertical_axis=vertical_axis
         )
@@ -1053,8 +1082,10 @@ def get_proj(self):
 
         # elev stores the elevation angle in the z plane
         # azim stores the azimuth angle in the x,y plane
-        elev_rad = np.deg2rad(self.elev)
-        azim_rad = np.deg2rad(self.azim)
+        # 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))
+        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
@@ -1084,7 +1115,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)
+        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)
@@ -1172,14 +1203,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.elev, self.azim, self.roll)
 
     def _set_view(self, view):
         # docstring inherited
-        xlim, ylim, zlim, elev, azim = view
+        xlim, ylim, zlim, elev, azim, roll = view
         self.set(xlim=xlim, ylim=ylim, zlim=zlim)
         self.elev = elev
         self.azim = azim
+        self.roll = roll
 
     def format_zdata(self, z):
         """
@@ -1206,8 +1238,12 @@ def format_coord(self, xd, yd):
 
         if self.button_pressed in self._rotate_btn:
             # ignore xd and yd and display angles instead
-            return (f"azimuth={self.azim:.0f}\N{DEGREE SIGN}, "
-                    f"elevation={self.elev:.0f}\N{DEGREE SIGN}"
+            norm_elev = art3d._norm_angle(self.elev)
+            norm_azim = art3d._norm_angle(self.azim)
+            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"roll={norm_roll:.0f}\N{DEGREE SIGN}"
                     ).replace("-", "\N{MINUS SIGN}")
 
         # nearest edge
@@ -1260,8 +1296,12 @@ def _on_move(self, event):
             # get the x and y pixel coords
             if dx == 0 and dy == 0:
                 return
-            self.elev = art3d._norm_angle(self.elev - (dy/h)*180)
-            self.azim = art3d._norm_angle(self.azim - (dx/w)*180)
+
+            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()
             self.stale = True
             self.figure.canvas.draw_idle()
@@ -1274,7 +1314,8 @@ def _on_move(self, event):
             minx, maxx, miny, maxy, minz, maxz = self.get_w_lims()
             dx = 1-((w - dx)/w)
             dy = 1-((h - dy)/h)
-            elev, azim = np.deg2rad(self.elev), np.deg2rad(self.azim)
+            elev = np.deg2rad(self.elev)
+            azim = np.deg2rad(self.azim)
             # project xv, yv, zv -> xw, yw, zw
             dxx = (maxx-minx)*(dy*np.sin(elev)*np.cos(azim) + dx*np.sin(azim))
             dyy = (maxy-miny)*(-dx*np.cos(azim) + dy*np.sin(elev)*np.sin(azim))
@@ -3256,11 +3297,11 @@ 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 azimuth and elevation.
-        with cbook._setattr_cm(self, azim=0, elev=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())
-        # azim=elev=0 produces the Y-Z plane, so quiversize in 2D 'x' is 'y' in
-        # 3D, hence the 1 index.
+        # 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
         # that the size corresponds to the base. In other words, this constant

lib/mpl_toolkits/mplot3d/proj3d.py

@@ -51,34 +51,41 @@ def world_transformation(xmin, xmax,
                      [0,    0,    0,    1]])
 
 
-def view_transformation(E, R, V):
+def rotation_about_vector(v, angle):
+    """
+    Produce a rotation matrix for an angle in radians about a vector.
+    """
+    vx, vy, vz = v / np.linalg.norm(v)
+    s = np.sin(angle)
+    c = np.cos(angle)
+    t = 2*np.sin(angle/2)**2  # more numerically stable than t = 1-c
+
+    R = np.array([
+        [t*vx*vx + c,    t*vx*vy - vz*s, t*vx*vz + vy*s],
+        [t*vy*vx + vz*s, t*vy*vy + c,    t*vy*vz - vx*s],
+        [t*vz*vx - vy*s, t*vz*vy + vx*s, t*vz*vz + c]])
+
+    return R
+
+
+def view_transformation(E, R, V, roll):
     n = (E - R)
-    ## new
-#    n /= np.linalg.norm(n)
-#    u = np.cross(V, n)
-#    u /= np.linalg.norm(u)
-#    v = np.cross(n, u)
-#    Mr = np.diag([1.] * 4)
-#    Mt = np.diag([1.] * 4)
-#    Mr[:3,:3] = u, v, n
-#    Mt[:3,-1] = -E
-    ## end new
-
-    ## old
-    n = n / np.linalg.norm(n)
+    n = n/np.linalg.norm(n)
     u = np.cross(V, n)
-    u = u / np.linalg.norm(u)
-    v = np.cross(n, u)
-    Mr = [[u[0], u[1], u[2], 0],
-          [v[0], v[1], v[2], 0],
-          [n[0], n[1], n[2], 0],
-          [0,    0,    0,    1]]
-    #
-    Mt = [[1, 0, 0, -E[0]],
-          [0, 1, 0, -E[1]],
-          [0, 0, 1, -E[2]],
-          [0, 0, 0, 1]]
-    ## end old
+    u = u/np.linalg.norm(u)
+    v = np.cross(n, u)  # Will be a unit vector
+
+    # 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)
+    Mr[:3, :3] = [u, v, n]
+    Mt[:3, -1] = -E
 
     return np.dot(Mr, Mt)