Make mplot3d mouse rotation style adjustable

MischaMegens2 · MischaMegens2 · commit 077ba10c5427 · 2024-09-18T22:46:15.000-07:00
Addresses Issue matplotlib#28408 - matplotlibrc: add axes3d.mouserotationstyle and axes3d.trackballsize - lib/matplotlib/rcsetup.py: add validation for axes3d.mouserotationstyle and axes3d.trackballsize - axes3d.py: implement various mouse rotation styles - update test_axes3d.py::test_rotate() - view_angles.rst: add documentation for the mouse rotation styles - update next_whats_new/mouse_rotation.rst
diff --git a/doc/api/toolkits/mplot3d/view_angles.rst b/doc/api/toolkits/mplot3d/view_angles.rst
@@ -38,3 +38,119 @@ further documented in the `.mplot3d.axes3d.Axes3D.view_init` API.
 
 .. plot:: gallery/mplot3d/view_planes_3d.py
    :align: center
+
+
+Rotation with mouse
+===================
+
+3D plots can be reoriented by dragging the mouse.
+There are various ways to accomplish this; the style of mouse rotation
+can be specified by setting ``rcParams.axes3d.mouserotationstyle``, see
+:doc:`/users/explain/customizing`.
+
+Originally (with ``mouserotationstyle: azel``), the 2D mouse position
+corresponded directly to azimuth and elevation; this is also how it is done
+in `MATLAB <https://www.mathworks.com/help/matlab/ref/view.html>`_.
+This approach works fine for polar plots, where the *z* axis is special;
+however, it leads to a kind of 'gimbal lock' when looking down the *z* axis:
+the plot reacts differently to mouse movement, dependent on the particular
+orientation at hand. Also, 'roll' cannot be controlled.
+
+As an alternative, there are various mouse rotation styles where the mouse
+manipulates a 'trackball'. In its simplest form (``mouserotationstyle: trackball``),
+the trackball rotates around an in-plane axis perpendicular to the mouse motion
+(it is as if there is a plate laying on the trackball; the plate itself is fixed
+in orientation, but you can drag the plate with the mouse, thus rotating the ball).
+This is more natural to work with than the ``azel`` style; however,
+the plot cannot be easily rotated around the viewing direction - one has to
+drag the mouse in circles with a handedness opposite to the desired rotation.
+
+A different variety of trackball rotates along the shortest arc on the virtual
+sphere (``mouserotationstyle: arcball``); it is a variation on Ken Shoemake's
+ARCBALL [Shoemake1992]_. Rotating around the viewing direction is straightforward
+with it. Shoemake's original arcball is also available
+(``mouserotationstyle: Shoemake``); it is free of hysteresis, i.e.,
+returning mouse to the original position returns the figure to its original
+orientation, the rotation is independent of the details of the path the mouse
+took. However, Shoemake's arcball rotates at twice the angular rate of the
+mouse movement (it is quite noticeable, especially when adjusting roll).
+So it is a trade-off.
+
+Shoemake's arcball has an abrupt edge; this is remedied in Holroyd's arcball
+(``mouserotationstyle: Holroyd``).
+
+Henriksen et al. [Henriksen2002]_ provide an overview.
+
+In summary:
+
+.. list-table::
+   :width: 100%
+   :widths: 30 20 20 20 35
+
+   * - Style
+     - traditional [1]_
+     - incl. roll [2]_
+     - uniform [3]_
+     - path independent [4]_
+   * - azel
+     - ✔️
+     - ❌
+     - ❌
+     - ✔️
+   * - trackball
+     - ❌
+     - ～
+     - ✔️
+     - ❌
+   * - arcball
+     - ❌
+     - ✔️
+     - ✔️
+     - ❌
+   * - Shoemake
+     - ❌
+     - ✔️
+     - ✔️
+     - ✔️
+   * - Holroyd
+     - ❌
+     - ✔️
+     - ✔️
+     - ✔️
+
+
+.. [1] The way it was historically; this is also MATLAB's style
+.. [2] Mouse controls roll too (not only azimuth and elevation)
+.. [3] Figure reacts the same way to mouse movements, regardless of orientation (no difference between 'poles' and 'equator')
+.. [4] Returning mouse to original position returns figure to original orientation (no hysteresis: rotation is independent of the details of the path the mouse took)
+
+Try it out by adding a file ``matplotlibrc`` to folder ``matplotlib\galleries\examples\mplot3d``,
+with contents::
+
+    axes3d.mouserotationstyle: arcball
+
+(or any of the other styles), and run a suitable example, e.g.::
+
+    python surfaced3d.py
+
+(If eternal compatibility with the horrors of the past is less of a consideration
+for you, then it is likely that you would want to go with ``arcball``, ``Shoemake``,
+or ``Holroyd``.)
+
+The size of the trackball or arcball can be adjusted by setting
+``rcParams.axes3d.trackballsize``, in units of the Axes bounding box;
+i.e., to make the trackball span the whole bounding box, set it to 1.
+A size of ca. 2/3 appears to work reasonably well.
+
+----
+
+.. [Shoemake1992] Ken Shoemake, "ARCBALL: A user interface for specifying
+  three-dimensional rotation using a mouse", in Proceedings of Graphics
+  Interface '92, 1992, pp. 151-156, https://doi.org/10.20380/GI1992.18
+
+.. [Henriksen2002] Knud Henriksen, Jon Sporring, Kasper Hornbæk,
+  "Virtual Trackballs Revisited", in Proceedings of DSAGM'2002:
+  http://www.diku.dk/~kash/papers/DSAGM2002_henriksen.pdf;
+  and in IEEE Transactions on Visualization
+  and Computer Graphics, Volume 10, Issue 2, March-April 2004, pp. 206-216,
+  https://doi.org/10.1109/TVCG.2004.1260772
diff --git a/doc/users/next_whats_new/mouse_rotation.rst b/doc/users/next_whats_new/mouse_rotation.rst
@@ -4,9 +4,12 @@ Rotating 3d plots with the mouse
 Rotating three-dimensional plots with the mouse has been made more intuitive.
 The plot now reacts the same way to mouse movement, independent of the
 particular orientation at hand; and it is possible to control all 3 rotational
-degrees of freedom (azimuth, elevation, and roll). It uses a variation on
-Ken Shoemake's ARCBALL [Shoemake1992]_.
+degrees of freedom (azimuth, elevation, and roll). By default,
+it uses a variation on Ken Shoemake's ARCBALL [1]_.
+The particular style of mouse rotation can be set via
+``rcParams.axes3d.mouserotationstyle``.
+See also :doc:`/api/toolkits/mplot3d/view_angles`.
 
-.. [Shoemake1992] Ken Shoemake, "ARCBALL: A user interface for specifying
-  three-dimensional rotation using a mouse." in Proceedings of Graphics
+.. [1] Ken Shoemake, "ARCBALL: A user interface for specifying
+  three-dimensional rotation using a mouse", in Proceedings of Graphics
   Interface '92, 1992, pp. 151-156, https://doi.org/10.20380/GI1992.18
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -433,6 +433,10 @@
 #axes3d.yaxis.panecolor:    (0.90, 0.90, 0.90, 0.5)  # background pane on 3D axes
 #axes3d.zaxis.panecolor:    (0.925, 0.925, 0.925, 0.5)  # background pane on 3D axes
 
+#axes3d.mouserotationstyle: arcball  # {azel, trackball, arcball, Shoemake, Holroyd}
+                            # See also https://matplotlib.org/stable/api/toolkits/mplot3d/view_angles.html#rotation-with-mouse
+#axes3d.trackballsize: 0.667  # trackball diameter, in units of the Axes bbox
+
 ## ***************************************************************************
 ## * AXIS                                                                    *
 ## ***************************************************************************
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1132,6 +1132,10 @@ def _convert_validator_spec(key, conv):
     "axes3d.yaxis.panecolor":    validate_color,  # 3d background pane
     "axes3d.zaxis.panecolor":    validate_color,  # 3d background pane
 
+    "axes3d.mouserotationstyle": ["azel", "trackball", "arcball",
+                                  "Shoemake", "Holroyd"],
+    "axes3d.trackballsize": validate_float,
+
     # scatter props
     "scatter.marker":     _validate_marker,
     "scatter.edgecolors": validate_string,
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1508,7 +1508,7 @@ def _calc_coord(self, xv, yv, renderer=None):
         p2 = p1 - scale*vec
         return p2, pane_idx
 
-    def _arcball(self, x: float, y: float) -> np.ndarray:
+    def _arcball(self, x: float, y: float, Holroyd: bool) -> np.ndarray:
         """
         Convert a point (x, y) to a point on a virtual trackball
         This is Ken Shoemake's arcball
@@ -1517,13 +1517,20 @@ def _arcball(self, x: float, y: float) -> np.ndarray:
         Proceedings of Graphics Interface '92, 1992, pp. 151-156,
         https://doi.org/10.20380/GI1992.18
         """
-        x *= 2
-        y *= 2
+        s = mpl.rcParams['axes3d.trackballsize'] / 2
+        x /= s
+        y /= s
         r2 = x*x + y*y
-        if r2 > 1:
-            p = np.array([0, x/math.sqrt(r2), y/math.sqrt(r2)])
-        else:
-            p = np.array([math.sqrt(1-r2), x, y])
+        if Holroyd:
+            if r2 > 0.5:
+                p = np.array([1/(2*math.sqrt(r2)), x, y])/math.sqrt(1/(4*r2)+r2)
+            else:
+                p = np.array([math.sqrt(1-r2), x, y])
+        else:  # Shoemake
+            if r2 > 1:
+                p = np.array([0, x/math.sqrt(r2), y/math.sqrt(r2)])
+            else:
+                p = np.array([math.sqrt(1-r2), x, y])
         return p
 
     def _on_move(self, event):
@@ -1561,23 +1568,49 @@ def _on_move(self, event):
             if dx == 0 and dy == 0:
                 return
 
-            # Convert to quaternion
-            elev = np.deg2rad(self.elev)
-            azim = np.deg2rad(self.azim)
-            roll = np.deg2rad(self.roll)
-            q = _Quaternion.from_cardan_angles(elev, azim, roll)
-
-            # Update quaternion - a variation on Ken Shoemake's ARCBALL
-            current_vec = self._arcball(self._sx/w, self._sy/h)
-            new_vec = self._arcball(x/w, y/h)
-            dq = _Quaternion.rotate_from_to(current_vec, new_vec)
-            q = dq * q
-
-            # Convert to elev, azim, roll
-            elev, azim, roll = q.as_cardan_angles()
-            azim = np.rad2deg(azim)
-            elev = np.rad2deg(elev)
-            roll = np.rad2deg(roll)
+            style = mpl.rcParams['axes3d.mouserotationstyle']
+            if style == 'azel':
+                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)
+                elev = self.elev + delev
+                azim = self.azim + dazim
+                roll = self.roll
+            else:
+                # Convert to quaternion
+                elev = np.deg2rad(self.elev)
+                azim = np.deg2rad(self.azim)
+                roll = np.deg2rad(self.roll)
+                q = _Quaternion.from_cardan_angles(elev, azim, roll)
+
+                if style in ['arcball', 'Shoemake', 'Holroyd']:
+                    # Update quaternion
+                    is_Holroyd = (style == 'Holroyd')
+                    current_vec = self._arcball(self._sx/w, self._sy/h, is_Holroyd)
+                    new_vec = self._arcball(x/w, y/h, is_Holroyd)
+                    if style == 'arcball':
+                        dq = _Quaternion.rotate_from_to(current_vec, new_vec)
+                    else:  # 'Shoemake', 'Holroyd'
+                        dq = _Quaternion(0, new_vec) * _Quaternion(0, -current_vec)
+                    q = dq * q
+                elif style == 'trackball':
+                    s = mpl.rcParams['axes3d.trackballsize'] / 2
+                    k = np.array([0, -(y-self._sy)/h, (x-self._sx)/w]) / s
+                    nk = np.linalg.norm(k)
+                    th = nk / 2
+                    dq = _Quaternion(math.cos(th), k*math.sin(th)/nk)
+                    q = dq * q
+                else:
+                    warnings.warn("Mouse rotation style (axes3d.mouserotationstyle: " +
+                                  style + ") not recognized.")
+
+                # Convert to elev, azim, roll
+                elev, azim, roll = q.as_cardan_angles()
+                elev = np.rad2deg(elev)
+                azim = np.rad2deg(azim)
+                roll = np.rad2deg(roll)
+
+            # update view
             vertical_axis = self._axis_names[self._vertical_axis]
             self.view_init(
                 elev=elev,
@@ -3984,7 +4017,7 @@ def rotate_from_to(cls, r1, r2):
         k = np.cross(r1, r2)
         nk = np.linalg.norm(k)
         th = np.arctan2(nk, np.dot(r1, r2))
-        th = th/2
+        th /= 2
         if nk == 0:  # r1 and r2 are parallel or anti-parallel
             if np.dot(r1, r2) < 0:
                 warnings.warn("Rotation defined by anti-parallel vectors is ambiguous")
@@ -4021,6 +4054,7 @@ def as_cardan_angles(self):
         """
         The inverse of `from_cardan_angles()`.
         Note that the angles returned are in radians, not degrees.
+        The angles are not sensitive to the quaternion's norm().
         """
         qw = self.scalar
         qx, qy, qz = self.vector[..., :]
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
@@ -1939,37 +1939,85 @@ def test_quaternion():
                 np.deg2rad(elev), np.deg2rad(azim), np.deg2rad(roll))
             assert np.isclose(q.norm, 1)
             q = Quaternion(mag * q.scalar, mag * q.vector)
-            e, a, r = np.rad2deg(Quaternion.as_cardan_angles(q))
-            assert np.isclose(e, elev)
-            assert np.isclose(a, azim)
-            assert np.isclose(r, roll)
+            np.testing.assert_allclose(np.rad2deg(Quaternion.as_cardan_angles(q)),
+                                       (elev, azim, roll), atol=1e-6)
 
 
-def test_rotate():
+@pytest.mark.parametrize('style',
+                         ('azel', 'trackball', 'arcball', 'Shoemake', 'Holroyd'))
+def test_rotate(style):
     """Test rotating using the left mouse button."""
-    for roll, dx, dy, new_elev, new_azim, new_roll in [
-            [0, 0.5, 0, 0, -90, 0],
-            [30, 0.5, 0, 30, -90, 0],
-            [0, 0, 0.5, -90, 0, 0],
-            [30, 0, 0.5, -60, -90, 90],
-            [0, 0.5, 0.5, -45, -90, 45],
-            [30, 0.5, 0.5, -15, -90, 45]]:
-        fig = plt.figure()
-        ax = fig.add_subplot(1, 1, 1, projection='3d')
-        ax.view_init(0, 0, roll)
-        fig.canvas.draw()
-
-        # drag mouse to change orientation
-        ax._button_press(
-            mock_event(ax, button=MouseButton.LEFT, xdata=0, ydata=0))
-        ax._on_move(
-            mock_event(ax, button=MouseButton.LEFT,
-                           xdata=dx*ax._pseudo_w, ydata=dy*ax._pseudo_h))
-        fig.canvas.draw()
-
-        assert np.isclose(ax.elev, new_elev)
-        assert np.isclose(ax.azim, new_azim)
-        assert np.isclose(ax.roll, new_roll)
+    if style == 'azel':
+        s = 0.5
+    else:
+        s = mpl.rcParams['axes3d.trackballsize'] / 2
+    s *= 0.5
+    with mpl.rc_context({'axes3d.mouserotationstyle': style}):
+        for roll, dx, dy in [
+                [0, 1, 0],
+                [30, 1, 0],
+                [0, 0, 1],
+                [30, 0, 1],
+                [0, 0.5, np.sqrt(3)/2],
+                [30, 0.5, np.sqrt(3)/2],
+                [0, 2, 0]]:
+            fig = plt.figure()
+            ax = fig.add_subplot(1, 1, 1, projection='3d')
+            ax.view_init(0, 0, roll)
+            ax.figure.canvas.draw()
+
+            # drag mouse to change orientation
+            ax._button_press(
+                mock_event(ax, button=MouseButton.LEFT, xdata=0, ydata=0))
+            ax._on_move(
+                mock_event(ax, button=MouseButton.LEFT,
+                               xdata=s*dx*ax._pseudo_w, ydata=s*dy*ax._pseudo_h))
+            ax.figure.canvas.draw()
+
+            c = np.sqrt(3)/2
+            expectations = {
+                ('azel', 0, 1, 0): (0,  -45, 0),
+                ('azel', 0, 0, 1): (-45, 0, 0),
+                ('azel', 0, 0.5, c): (-38.971143, -22.5, 0),
+                ('azel', 0, 2, 0): (0, -90, 0),
+                ('azel', 30, 1, 0): (22.5, -38.971143, 30),
+                ('azel', 30, 0, 1): (-38.971143, -22.5, 30),
+                ('azel', 30, 0.5, c): (-22.5, -38.971143, 30),
+
+                ('trackball', 0, 1, 0): (0, -28.64789, 0),
+                ('trackball', 0, 0, 1): (-28.64789, 0, 0),
+                ('trackball', 0, 0.5, c): (-24.531578, -15.277726, 3.340403),
+                ('trackball', 0, 2, 0): (0, -180/np.pi, 0),
+                ('trackball', 30, 1, 0): (13.869588, -25.319385, 26.87008),
+                ('trackball', 30, 0, 1): (-24.531578, -15.277726, 33.340403),
+                ('trackball', 30, 0.5, c): (-13.869588, -25.319385, 33.129920),
+
+                ('arcball', 0, 1, 0): (0, -30, 0),
+                ('arcball', 0, 0, 1): (-30, 0, 0),
+                ('arcball', 0, 0.5, c): (-25.658906, -16.102114, 3.690068),
+                ('arcball', 0, 2, 0): (0, -90, 0),
+                ('arcball', 30, 1, 0): (14.477512, -26.565051, 26.565051),
+                ('arcball', 30, 0, 1): (-25.658906, -16.102114, 33.690068),
+                ('arcball', 30, 0.5, c): (-14.477512, -26.565051, 33.434949),
+
+                ('Shoemake', 0, 1, 0): (0, -60, 0),
+                ('Shoemake', 0, 0, 1): (-60, 0, 0),
+                ('Shoemake', 0, 0.5, c): (-48.590378, -40.893395, 19.106605),
+                ('Shoemake', 0, 2, 0): (0, 180, 0),
+                ('Shoemake', 30, 1, 0): (25.658906, -56.309932, 16.102114),
+                ('Shoemake', 30, 0, 1): (-48.590378, -40.893395, 49.106605),
+                ('Shoemake', 30, 0.5, c): (-25.658906, -56.309932, 43.897886),
+
+                ('Holroyd', 0, 1, 0): (0, -60, 0),
+                ('Holroyd', 0, 0, 1): (-60, 0, 0),
+                ('Holroyd', 0, 0.5, c): (-48.590378, -40.893395, 19.106605),
+                ('Holroyd', 0, 2, 0): (0, -126.869898, 0),
+                ('Holroyd', 30, 1, 0):  (25.658906, -56.309932, 16.102114),
+                ('Holroyd', 30, 0, 1): (-48.590378, -40.893395, 49.106605),
+                ('Holroyd', 30, 0.5, c): (-25.658906, -56.309932, 43.897886)}
+            new_elev, new_azim, new_roll = expectations[(style, roll, dx, dy)]
+            np.testing.assert_allclose((ax.elev, ax.azim, ax.roll),
+                                       (new_elev, new_azim, new_roll), atol=1e-6)
 
 
 def test_pan():
