matplotlib · scottshambaugh · Oct 15, 2024 · Jul 10, 2024 · Sep 27, 2024 · Oct 1, 2024
diff --git a/doc/api/toolkits/mplot3d/view_angles.rst b/doc/api/toolkits/mplot3d/view_angles.rst
@@ -38,3 +38,160 @@ further documented in the `.mplot3d.axes3d.Axes3D.view_init` API.

 .. plot:: gallery/mplot3d/view_planes_3d.py
   :align: center
+
+
+.. _toolkit_mouse-rotation:
+
+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 :rc:`axes3d.mouserotationstyle`, see
+:doc:`/users/explain/customizing`.
+
+Prior to v3.10, 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>`_.
+To keep it this way, set ``mouserotationstyle: azel``.
+This approach works fine for spherical coordinate 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 virtual '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
+move the mouse in circles with a handedness opposite to the desired rotation,
+counterintuitively.
+
+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 (grab the ball near its edge instead of near the center).
+
+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, which could be desirable.
+However, Shoemake's arcball rotates at twice the angular rate of the
+mouse movement (it is quite noticeable, especially when adjusting roll),
+and it lacks an obvious mechanical equivalent; arguably, the path-independent rotation is unnatural.
+So it is a trade-off.
+
+Shoemake's arcball has an abrupt edge; this is remedied in Gavin Bell's arcball
+(``mouserotationstyle: Bell``), originally written for OpenGL [Bell1988]_. It is used
+in Blender and Meshlab.
+
+Henriksen et al. [Henriksen2002]_ provide an overview. In summary:
+
+.. list-table::
+   :width: 100%
+   :widths: 30 20 20 20 20 35
+
+   * - Style
+     - traditional [1]_
+     - incl. roll [2]_
+     - uniform [3]_
+     - path independent [4]_
+     - mechanical counterpart [5]_
+   * - azel
+     - ✔️
+     - ❌
+     - ❌
+     - ✔️
+     - ✔️
+   * - trackball
+     - ❌
+     - ✓ [6]_
+     - ✔️
+     - ❌
+     - ✔️
+   * - arcball
+     - ❌
+     - ✔️
+     - ✔️
+     - ❌
+     - ✔️
+   * - Shoemake
+     - ❌
+     - ✔️
+     - ✔️
+     - ✔️
+     - ❌
+   * - Bell
+     - ❌
+     - ✔️
+     - ✔️
+     - ✔️
+     - ❌
+
+
+.. [1] The way it was prior to v3.10; 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)
+.. [5] The style has a corresponding natural implementation as a mechanical device
+.. [6] While it is possible to control roll with the ``trackball`` style, this is not very intuitive (it requires moving the mouse in large circles) and the resulting roll is in the opposite direction
+
+You can try out one of the various mouse rotation styles using::
+
+.. code::
+
+    import matplotlib as mpl
+    mpl.rcParams['axes3d.mouserotationstyle'] = 'trackball'  # 'azel', 'trackball', 'arcball', 'Shoemake', or 'Bell'
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+    from matplotlib import cm
+
+    ax = plt.figure().add_subplot(projection='3d')
+
+    X = np.arange(-5, 5, 0.25)
+    Y = np.arange(-5, 5, 0.25)
+    X, Y = np.meshgrid(X, Y)
+    R = np.sqrt(X**2 + Y**2)
+    Z = np.sin(R)
+
+    surf = ax.plot_surface(X, Y, Z, cmap=cm.coolwarm,
+                           linewidth=0, antialiased=False)
+
+    plt.show()
+
+Alternatively, create a file ``matplotlibrc``, with contents::
+
+    axes3d.mouserotationstyle: arcball
+
+(or any of the other styles, instead of ``arcball``), and then run any of
+the :ref:`mplot3d-examples-index` examples.
+
+The size of the virtual trackball or arcball can be adjusted as well,
+by setting :rc:`axes3d.trackballsize`. This specifies how much
+mouse motion is needed to obtain a given rotation angle (when near the center),
+and it controls where the edge of the arcball is (how far from the center,
+how close to the plot edge).
+The size is specified 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 about 2/3 appears to work reasonably well; this is the default.
+
+----
+
+.. [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
+
+
+.. [Bell1988] Gavin Bell, in the examples included with the GLUT (OpenGL
+  Utility Toolkit) library,
+  https://github.com/markkilgard/glut/blob/master/progs/examples/trackball.h
+
+.. [Henriksen2002] Knud Henriksen, Jon Sporring, Kasper Hornbæk,
+  "Virtual Trackballs Revisited", 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 `[full-text]`__;
+
+__ https://www.researchgate.net/publication/8329656_Virtual_Trackballs_Revisited#fullTextFileContent
diff --git a/doc/users/next_whats_new/mouse_rotation.rst b/doc/users/next_whats_new/mouse_rotation.rst
@@ -4,9 +4,42 @@ 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
+:rc:`axes3d.mouserotationstyle`.
+See also :ref:`toolkit_mouse-rotation`.

-.. [Shoemake1992] Ken Shoemake, "ARCBALL: A user interface for specifying
-  three-dimensional rotation using a mouse." in Proceedings of Graphics
+To revert to the original mouse rotation style,
+create a file ``matplotlibrc`` with contents::
+
+    axes3d.mouserotationstyle: azel
+
+To try out one of the various mouse rotation styles:
+
+.. code::
+
+    import matplotlib as mpl
+    mpl.rcParams['axes3d.mouserotationstyle'] = 'trackball'  # 'azel', 'trackball', 'arcball', 'Shoemake', or 'Bell'
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+    from matplotlib import cm
+
+    ax = plt.figure().add_subplot(projection='3d')
+
+    X = np.arange(-5, 5, 0.25)
+    Y = np.arange(-5, 5, 0.25)
+    X, Y = np.meshgrid(X, Y)
+    R = np.sqrt(X**2 + Y**2)
+    Z = np.sin(R)
+
+    surf = ax.plot_surface(X, Y, Z, cmap=cm.coolwarm,
+                           linewidth=0, antialiased=False)
+
+    plt.show()
+
+
+.. [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, Bell}
+                            # 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", "Bell"],
+    "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,22 +1508,31 @@ 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, style: str) -> np.ndarray:
        """
-        Convert a point (x, y) to a point on a virtual trackball
-        This is Ken Shoemake's arcball
+        Convert a point (x, y) to a point on a virtual trackball.
+
+        This is either Ken Shoemake's arcball (a sphere) or
+        Gavin Bell's (a sphere combined with a hyperbola).
        See: 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
        """
-        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 style == 'Bell':
+            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:  # 'arcball', '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 +1570,35 @@ 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:
+                q = _Quaternion.from_cardan_angles(
+                        *np.deg2rad((self.elev, self.azim, self.roll)))
+
+                if style == 'trackball':
+                    k = np.array([0, -dy/h, dx/w])
+                    nk = np.linalg.norm(k)
+                    th = nk / mpl.rcParams['axes3d.trackballsize']
+                    dq = _Quaternion(np.cos(th), k*np.sin(th)/nk)
+                else:  # 'arcball', 'Shoemake', 'Bell'
+                    current_vec = self._arcball(self._sx/w, self._sy/h, style)
+                    new_vec = self._arcball(x/w, y/h, style)
+                    if style == 'arcball':
+                        dq = _Quaternion.rotate_from_to(current_vec, new_vec)
+                    else:  # 'Shoemake', 'Bell'
+                        dq = _Quaternion(0, new_vec) * _Quaternion(0, -current_vec)
+
+                q = dq * q
+                elev, azim, roll = np.rad2deg(q.as_cardan_angles())
+
+            # update view
            vertical_axis = self._axis_names[self._vertical_axis]
            self.view_init(
                elev=elev,
@@ -3984,7 +4005,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 +4042,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[..., :]