Soften the arcball edge using a 'border' parameter

MischaMegens2 · MischaMegens2 · commit 89701eb7ec50 · 2024-10-09T23:30:50.000-07:00
- revise _arcball() to soften the edge, according to border width parameter
- drop _arcball() 'style' function parameter
- add trackballborder rcParam
- _arcball() 'border' case: normalize, so result vector is on unit sphere
-  math.sin/cos/sqrt -&gt; np.sin/cos/sqrt: use numpy instead of math for consistency
- remove 'Bell' style
- rename arcball -&gt; sphere, Shoemake -&gt; arcball
- update documentation
- update test
diff --git a/doc/api/toolkits/mplot3d/view_angles.rst b/doc/api/toolkits/mplot3d/view_angles.rst
@@ -70,23 +70,20 @@ 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).
+sphere (``mouserotationstyle: sphere``). 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
+Ken Shoemake's ARCBALL [Shoemake1992]_ is also available (``mouserotationstyle: Shoemake``);
+it resembles the ``sphere`` style, but 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.
+and it lacks an obvious mechanical equivalent; arguably, the path-independent
+rotation is not natural (however convenient), it could take some getting used to.
 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::
@@ -111,19 +108,13 @@ Henriksen et al. [Henriksen2002]_ provide an overview. In summary:
      - ✔️
      - ❌
      - ✔️
-   * - arcball
+   * - sphere
      - ❌
      - ✔️
      - ✔️
      - ❌
      - ✔️
-   * - Shoemake
-     - ❌
-     - ✔️
-     - ✔️
-     - ✔️
-     - ❌
-   * - Bell
+   * - arcball
      - ❌
      - ✔️
      - ✔️
@@ -134,16 +125,16 @@ Henriksen et al. [Henriksen2002]_ provide an overview. In summary:
 .. [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)
+.. [4] Returning mouse to original position returns figure to original orientation (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
+.. [6] While it is possible to control roll with the ``trackball`` style, this is not immediately obvious (it requires moving the mouse in large circles) and a bit counterintuitive (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'
+    mpl.rcParams['axes3d.mouserotationstyle'] = 'trackball'  # 'azel', 'trackball', 'sphere', or 'arcball'
 
     import numpy as np
     import matplotlib.pyplot as plt
@@ -169,22 +160,37 @@ Alternatively, create a file ``matplotlibrc``, with contents::
 (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,
+The size of the virtual trackball, sphere, or arcball can be adjusted
 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).
+and it controls where the edge of the sphere or arcball is (how far from
+the center, hence 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.
+i.e., to make the arcball span the whole bounding box, set it to 1.
 A size of about 2/3 appears to work reasonably well; this is the default.
 
-----
+Both arcballs (``mouserotationstyle: sphere`` and
+``mouserotationstyle: arcball``) have a noticeable edge; the edge can be made
+less abrupt by specifying a border width, :rc:`axes3d.trackballborder`.
+This works somewhat like Gavin Bell's arcball, which was
+originally written for OpenGL [Bell1988]_, and is used in Blender and Meshlab.
+Bell's arcball extends the arcball's spherical control surface with a hyperbola;
+the two are smoothly joined. However, the hyperbola extends all the way beyond
+the edge of the plot. In the mplot3d sphere and arcball style, the border extends
+to a radius :rc:`axes3d.trackballsize`/2 + :rc:`axes3d.trackballborder`.
+Beyond the border, the style works like the original: it controls roll only.
+A border width of about 0.2 appears to work well; this is the default.
+To obtain the original Shoemake's arcball with a sharp border,
+set the border width to 0.
+For an extended border similar to Bell's arcball, where the transition from
+the arcball to the border occurs at 45°, set the border width to
+$\sqrt 2 \approx 1.414$.
+
 
 .. [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
diff --git a/doc/users/next_whats_new/mouse_rotation.rst b/doc/users/next_whats_new/mouse_rotation.rst
@@ -20,7 +20,7 @@ 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'
+    mpl.rcParams['axes3d.mouserotationstyle'] = 'trackball'  # 'azel', 'trackball', 'sphere', or 'arcball'
 
     import numpy as np
     import matplotlib.pyplot as plt
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -433,9 +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}
+#axes3d.mouserotationstyle: arcball  # {azel, trackball, sphere, arcball}
                             # 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
+#axes3d.trackballborder: 0.2  # trackball border width, in units of the Axes bbox (only for 'sphere' and 'arcball' style)
 
 ## ***************************************************************************
 ## * AXIS                                                                    *
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1132,9 +1132,9 @@ 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.mouserotationstyle": ["azel", "trackball", "sphere", "arcball"],
     "axes3d.trackballsize": validate_float,
+    "axes3d.trackballborder": validate_float,
 
     # scatter props
     "scatter.marker":     _validate_marker,
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1508,31 +1508,37 @@ def _calc_coord(self, xv, yv, renderer=None):
         p2 = p1 - scale*vec
         return p2, pane_idx
 
-    def _arcball(self, x: float, y: float, style: str) -> np.ndarray:
+    def _arcball(self, x: float, y: float) -> np.ndarray:
         """
         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).
+        This is Ken Shoemake's arcball (a sphere), modified
+        to soften the abrupt edge (optionally).
         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
+        The smoothing of the edge is inspired by Gavin Bell's arcball
+        (a sphere combined with a hyperbola), but here, the sphere
+        is combined with a section of a cylinder, so it has finite support.
         """
         s = mpl.rcParams['axes3d.trackballsize'] / 2
+        b = mpl.rcParams['axes3d.trackballborder'] / s
         x /= s
         y /= s
         r2 = x*x + y*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])
+        r = np.sqrt(r2)
+        ra = 1 + b
+        a = b * (1 + b/2)
+        ri = 2/(ra + 1/ra)
+        if r < ri:
+            p = np.array([np.sqrt(1 - r2), x, y])
+        elif r < ra:
+            dr = ra - r
+            p = np.array([a - np.sqrt((a + dr) * (a - dr)), x, y])
+            p /= np.linalg.norm(p)
+        else:
+            p = np.array([0, x/r, y/r])
         return p
 
     def _on_move(self, event):
@@ -1587,12 +1593,12 @@ def _on_move(self, event):
                     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':
+                else:  # 'sphere', 'arcball'
+                    current_vec = self._arcball(self._sx/w, self._sy/h)
+                    new_vec = self._arcball(x/w, y/h)
+                    if style == 'sphere':
                         dq = _Quaternion.rotate_from_to(current_vec, new_vec)
-                    else:  # 'Shoemake', 'Bell'
+                    else:  # 'arcball'
                         dq = _Quaternion(0, new_vec) * _Quaternion(0, -current_vec)
 
                 q = dq * q
@@ -4017,7 +4023,7 @@ def rotate_from_to(cls, r1, r2):
             else:
                 q = cls(1, [0, 0, 0])  # = 1, no rotation
         else:
-            q = cls(math.cos(th), k*math.sin(th)/nk)
+            q = cls(np.cos(th), k*np.sin(th)/nk)
         return q
 
     @classmethod
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
@@ -1944,14 +1944,15 @@ def test_quaternion():
 
 
 @pytest.mark.parametrize('style',
-                         ('azel', 'trackball', 'arcball', 'Shoemake', 'Bell'))
+                         ('azel', 'trackball', 'sphere', 'arcball'))
 def test_rotate(style):
     """Test rotating using the left mouse button."""
     if style == 'azel':
         s = 0.5
     else:
         s = mpl.rcParams['axes3d.trackballsize'] / 2
     s *= 0.5
+    mpl.rcParams['axes3d.trackballborder'] = 0
     with mpl.rc_context({'axes3d.mouserotationstyle': style}):
         for roll, dx, dy in [
                 [0, 1, 0],
@@ -1992,29 +1993,21 @@ def test_rotate(style):
                 ('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),
-
-                ('Bell', 0, 1, 0): (0, -60, 0),
-                ('Bell', 0, 0, 1): (-60, 0, 0),
-                ('Bell', 0, 0.5, c): (-48.590378, -40.893395, 19.106605),
-                ('Bell', 0, 2, 0): (0, -126.869898, 0),
-                ('Bell', 30, 1, 0):  (25.658906, -56.309932, 16.102114),
-                ('Bell', 30, 0, 1): (-48.590378, -40.893395, 49.106605),
-                ('Bell', 30, 0.5, c): (-25.658906, -56.309932, 43.897886)}
+                ('sphere', 0, 1, 0): (0, -30, 0),
+                ('sphere', 0, 0, 1): (-30, 0, 0),
+                ('sphere', 0, 0.5, c): (-25.658906, -16.102114, 3.690068),
+                ('sphere', 0, 2, 0): (0, -90, 0),
+                ('sphere', 30, 1, 0): (14.477512, -26.565051, 26.565051),
+                ('sphere', 30, 0, 1): (-25.658906, -16.102114, 33.690068),
+                ('sphere', 30, 0.5, c): (-14.477512, -26.565051, 33.434949),
+
+                ('arcball', 0, 1, 0): (0, -60, 0),
+                ('arcball', 0, 0, 1): (-60, 0, 0),
+                ('arcball', 0, 0.5, c): (-48.590378, -40.893395, 19.106605),
+                ('arcball', 0, 2, 0): (0, 180, 0),
+                ('arcball', 30, 1, 0): (25.658906, -56.309932, 16.102114),
+                ('arcball', 30, 0, 1): (-48.590378, -40.893395, 49.106605),
+                ('arcball', 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)
