You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/api/toolkits/mplot3d/view_angles.rst
+68-31Lines changed: 68 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,6 +40,8 @@ further documented in the `.mplot3d.axes3d.Axes3D.view_init` API.
40
40
:align: center
41
41
42
42
43
+
.. _toolkit_mouse-rotation:
44
+
43
45
Rotation with mouse
44
46
===================
45
47
@@ -48,99 +50,132 @@ There are various ways to accomplish this; the style of mouse rotation
48
50
can be specified by setting ``rcParams.axes3d.mouserotationstyle``, see
49
51
:doc:`/users/explain/customizing`.
50
52
51
-
Originally (with ``mouserotationstyle: azel``), the 2D mouse position
52
-
corresponded directly to azimuth and elevation; this is also how it is done
53
+
Originally (prior to v3.10), the 2D mouse position corresponded directly
54
+
to azimuth and elevation; this is also how it is done
53
55
in `MATLAB <https://www.mathworks.com/help/matlab/ref/view.html>`_.
56
+
To keep it this way, set ``mouserotationstyle: azel``.
54
57
This approach works fine for polar plots, where the *z* axis is special;
55
58
however, it leads to a kind of 'gimbal lock' when looking down the *z* axis:
56
59
the plot reacts differently to mouse movement, dependent on the particular
57
60
orientation at hand. Also, 'roll' cannot be controlled.
58
61
59
62
As an alternative, there are various mouse rotation styles where the mouse
60
-
manipulates a 'trackball'. In its simplest form (``mouserotationstyle: trackball``),
63
+
manipulates a virtual 'trackball'. In its simplest form (``mouserotationstyle: trackball``),
61
64
the trackball rotates around an in-plane axis perpendicular to the mouse motion
62
65
(it is as if there is a plate laying on the trackball; the plate itself is fixed
63
66
in orientation, but you can drag the plate with the mouse, thus rotating the ball).
64
67
This is more natural to work with than the ``azel`` style; however,
65
68
the plot cannot be easily rotated around the viewing direction - one has to
66
-
drag the mouse in circles with a handedness opposite to the desired rotation.
69
+
move the mouse in circles with a handedness opposite to the desired rotation,
70
+
counterintuitively.
67
71
68
72
A different variety of trackball rotates along the shortest arc on the virtual
69
73
sphere (``mouserotationstyle: arcball``); it is a variation on Ken Shoemake's
70
74
ARCBALL [Shoemake1992]_. Rotating around the viewing direction is straightforward
71
-
with it. Shoemake's original arcball is also available
72
-
(``mouserotationstyle: Shoemake``); it is free of hysteresis, i.e.,
73
-
returning mouse to the original position returns the figure to its original
74
-
orientation, the rotation is independent of the details of the path the mouse
75
-
took. However, Shoemake's arcball rotates at twice the angular rate of the
76
-
mouse movement (it is quite noticeable, especially when adjusting roll).
75
+
with it (grab the ball near its edge instead of near the center).
76
+
77
+
Shoemake's original arcball is also available (``mouserotationstyle: Shoemake``);
78
+
it is free of hysteresis, i.e., returning mouse to the original position
79
+
returns the figure to its original orientation, the rotation is independent
80
+
of the details of the path the mouse took, which could be desirable.
81
+
However, Shoemake's arcball rotates at twice the angular rate of the
82
+
mouse movement (it is quite noticeable, especially when adjusting roll),
83
+
and it lacks an obvious mechanical equivalent; arguably, the path-independent rotation is unnatural.
77
84
So it is a trade-off.
78
85
79
86
Shoemake's arcball has an abrupt edge; this is remedied in Holroyd's arcball
80
87
(``mouserotationstyle: Holroyd``).
81
88
82
-
Henriksen et al. [Henriksen2002]_ provide an overview.
83
-
84
-
In summary:
89
+
Henriksen et al. [Henriksen2002]_ provide an overview. In summary:
85
90
86
91
.. list-table::
87
92
:width: 100%
88
-
:widths: 30 20 20 20 35
93
+
:widths: 30 20 20 20 20 35
89
94
90
95
* - Style
91
96
- traditional [1]_
92
97
- incl. roll [2]_
93
98
- uniform [3]_
94
99
- path independent [4]_
100
+
- mechanical counterpart [5]_
95
101
* - azel
96
102
- ✔️
97
103
- ❌
98
104
- ❌
99
105
- ✔️
106
+
- ✔️
100
107
* - trackball
101
108
- ❌
102
-
- ～
109
+
- ✓ [6]_
103
110
- ✔️
104
111
- ❌
112
+
- ✔️
105
113
* - arcball
106
114
- ❌
107
115
- ✔️
108
116
- ✔️
109
117
- ❌
118
+
- ✔️
110
119
* - Shoemake
111
120
- ❌
112
121
- ✔️
113
122
- ✔️
114
123
- ✔️
124
+
- ❌
115
125
* - Holroyd
116
126
- ❌
117
127
- ✔️
118
128
- ✔️
119
129
- ✔️
130
+
- ❌
120
131
121
132
122
-
.. [1] The way it was historically; this is also MATLAB's style
133
+
.. [1] The way it was prior to v3.10; this is also MATLAB's style
123
134
.. [2] Mouse controls roll too (not only azimuth and elevation)
124
135
.. [3] Figure reacts the same way to mouse movements, regardless of orientation (no difference between 'poles' and 'equator')
125
136
.. [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)
137
+
.. [5] The style has a corresponding natural implementation as a mechanical device
138
+
.. [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
126
139
127
-
Try it out by adding a file ``matplotlibrc`` to folder ``matplotlib\galleries\examples\mplot3d``,
128
-
with contents::
140
+
You can try out one of the various mouse rotation styles using::
129
141
130
-
axes3d.mouserotationstyle: arcball
142
+
.. code::
143
+
144
+
import matplotlib as mpl
145
+
mpl.rcParams['axes3d.mouserotationstyle'] = 'trackball' # 'azel', 'trackball', 'arcball', 'Shoemake', or 'Holroyd'
131
146
132
-
(or any of the other styles), and run a suitable example, e.g.::
147
+
import numpy as np
148
+
import matplotlib.pyplot as plt
149
+
from matplotlib import cm
150
+
151
+
ax = plt.figure().add_subplot(projection='3d')
152
+
153
+
X = np.arange(-5, 5, 0.25)
154
+
Y = np.arange(-5, 5, 0.25)
155
+
X, Y = np.meshgrid(X, Y)
156
+
R = np.sqrt(X**2 + Y**2)
157
+
Z = np.sin(R)
158
+
159
+
surf = ax.plot_surface(X, Y, Z, cmap=cm.coolwarm,
160
+
linewidth=0, antialiased=False)
133
161
134
-
python surfaced3d.py
162
+
plt.show()
135
163
136
-
(If eternal compatibility with the horrors of the past is less of a consideration
137
-
for you, then it is likely that you would want to go with ``arcball``, ``Shoemake``,
138
-
or ``Holroyd``.)
164
+
Alternatively, create a file ``matplotlibrc``, with contents::
139
165
140
-
The size of the trackball or arcball can be adjusted by setting
141
-
``rcParams.axes3d.trackballsize``, in units of the Axes bounding box;
166
+
axes3d.mouserotationstyle: arcball
167
+
168
+
(or any of the other styles, instead of ``arcball``), and then run any of
169
+
the :ref:`mplot3d-examples-index` examples.
170
+
171
+
The size of the virtual trackball or arcball can be adjusted as well,
172
+
by setting ``rcParams.axes3d.trackballsize``. This specifies how much
173
+
mouse motion is needed to obtain a given rotation angle (when near the center),
174
+
and it controls where the edge of the arcball is (how far from the center,
175
+
how close to the plot edge).
176
+
The size is specified in units of the Axes bounding box,
142
177
i.e., to make the trackball span the whole bounding box, set it to 1.
143
-
A size of ca. 2/3 appears to work reasonably well.
178
+
A size of about 2/3 appears to work reasonably well; this is the default.
144
179
145
180
----
146
181
@@ -149,8 +184,10 @@ A size of ca. 2/3 appears to work reasonably well.
149
184
Interface '92, 1992, pp. 151-156, https://doi.org/10.20380/GI1992.18
150
185
151
186
.. [Henriksen2002] Knud Henriksen, Jon Sporring, Kasper Hornbæk,
152
-
"Virtual Trackballs Revisited", in Proceedings of DSAGM'2002:
0 commit comments