.. _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: sphere``). Rotating around the viewing direction

is straightforward with it: grab the ball near its edge instead of near the center.

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 not natural (however convenient), it could take some getting used to.

So it is a trade-off.

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]_

- ✔️

- ❌

- ✔️

* - sphere

- ❌

- ✔️

- ✔️

- ❌

- ✔️

* - arcball

- ❌

- ✔️

- ✔️

- ✔️

- ❌

.. [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 (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 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', 'sphere', or 'arcball'

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: trackball

(or any of the other styles, instead of ``trackball``), and then run any of

the :ref:`mplot3d-examples-index` examples.

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 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 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 ``trackballsize/2 + 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

:math:`\sqrt 2 \approx 1.414`.

The border is a circular arc, wrapped around the arcball sphere cylindrically

(like a doughnut), joined smoothly to the sphere, much like Bell's hyperbola.

.. [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

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`.

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', 'sphere', or 'arcball'

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

#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)

"axes3d.mouserotationstyle": ["azel", "trackball", "sphere", "arcball"],

"axes3d.trackballsize": validate_float,

"axes3d.trackballborder": validate_float,

Convert a point (x, y) to a point on a virtual trackball.

This is Ken Shoemake's arcball (a sphere), modified

to soften the abrupt edge (optionally).

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

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)

p = np.array([0, x/r, y/r])

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: # '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: # 'arcball'

dq = _Quaternion(0, new_vec) * _Quaternion(0, -current_vec)

q = dq * q

elev, azim, roll = np.rad2deg(q.as_cardan_angles())

# update view

th /= 2

q = cls(np.cos(th), k*np.sin(th)/nk)

The angles are not sensitive to the quaternion's norm().

elev = np.arcsin(np.clip(2*(qw*qy+qz*qx)/(qw*qw+qx*qx+qy*qy+qz*qz), -1, 1))

roll = np.arctan2(2*(qw*qx-qy*qz), qw*qw-qx*qx-qy*qy+qz*qz)