forked from serjIII/threejsSDK
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ArcballControls.html
296 lines (229 loc) · 9.05 KB
/
ArcballControls.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<base href="../../../" />
<script src="page.js"></script>
<link type="text/css" rel="stylesheet" href="page.css" />
</head>
<body>
[page:EventDispatcher] →
<h1>[name]</h1>
<p class="desc">
Arcball controls allow the camera to be controlled by a virtual trackball with full touch support and advanced navigation functionality. <br>
Cursor/finger positions and movements are mapped over a virtual trackball surface
represented by a gizmo and mapped in intuitive and consistent camera movements.
Dragging cursor/fingers will cause camera to orbit around the center of the trackball in a conservative way (returning to the starting point
will make the camera to return to its starting orientation).<br><br>
In addition to supporting pan, zoom and pinch gestures, Arcball controls provide <i>focus</i> functionality with a double click/tap for
intuitively moving the object's point of interest in the center of the virtual trackball.
Focus allows a much better inspection and navigation in complex environment.
Moreover Arcball controls allow FOV manipulation (in a vertigo-style method) and z-rotation.
Saving and restoring of Camera State is supported also through clipboard
(use ctrl+c and ctrl+v shortcuts for copy and paste the state).<br><br>
Unlike [page:OrbitControls] and [page:TrackballControls], [name] doesn't require [page:.update] to be called externally in an animation loop when animations
are on.<br><br>
To use this, as with all files in the /examples directory, you will have to
include the file separately in your HTML.
</p>
<h2>Import</h2>
<p>
[name] is an add-on, and must be imported explicitly.
See [link:#manual/introduction/Installation Installation / Addons].
</p>
<code>
import { ArcballControls } from 'three/addons/controls/ArcballControls.js';
</code>
<h2>Code Example</h2>
<code>
const renderer = new THREE.WebGLRenderer();
renderer.setSize( window.innerWidth, window.innerHeight );
document.body.appendChild( renderer.domElement );
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 10000 );
const controls = new ArcballControls( camera, renderer.domElement, scene );
controls.addEventListener( 'change', function () {
renderer.render( scene, camera );
} );
//controls.update() must be called after any manual changes to the camera's transform
camera.position.set( 0, 20, 100 );
controls.update();
</code>
<h2>Examples</h2>
<p>[example:misc_controls_arcball misc / controls / arcball ]</p>
<h2>Constructor</h2>
<h3>[name]( [param:Camera camera], [param:HTMLDOMElement domElement], [param:Scene scene] )</h3>
<p>
[page:Camera camera]: (required) The camera to be controlled. The camera must not be a child of another object, unless that object is the scene itself.<br><br>
[page:HTMLDOMElement domElement]: The HTML element used for event listeners.<br><br>
[page:Scene scene]: The scene rendered by the camera. If not given, gizmos cannot be shown.
</p>
<h2>Events</h2>
<h3>change</h3>
<p>
Fires when the camera has been transformed by the controls.
</p>
<h3>start</h3>
<p>
Fires when an interaction was initiated.
</p>
<h3>end</h3>
<p>
Fires when an interaction has finished.
</p>
<h2>Properties</h2>
<h3>[property:Boolean adjustNearFar]</h3>
<p>
If true, camera's near and far values will be adjusted every time zoom is performed trying to mantain the same visible portion
given by initial near and far values ( [page:PerspectiveCamera] only ).
Default is false.
</p>
<h3>[property:Camera camera]</h3>
<p>
The camera being controlled.
</p>
<h3>[property:Boolean cursorZoom]</h3>
<p>
Set to true to make zoom become cursor centered.
</p>
<h3>
[property:Float dampingFactor]</h3>
<p>
The damping inertia used if [page:.enableAnimations] is set to true.
</p>
<h3>[property:HTMLDOMElement domElement]</h3>
<p>
The HTMLDOMElement used to listen for mouse / touch events. This must be passed in the constructor; changing it here will
not set up new event listeners.
</p>
<h3>[property:Boolean enabled]</h3>
<p>
When set to `false`, the controls will not respond to user input. Default is `true`.
</p>
<h3>[property:Boolean enableAnimations]</h3>
<p>
Set to true to enable animations for rotation (damping) and focus operation. Default is true.
</p>
<h3>[property:Boolean enableGrid]</h3>
<p>
When set to true, a grid will appear when panning operation is being performed (desktop interaction only). Default is false.
</p>
<h3>[property:Boolean enablePan]</h3>
<p>
Enable or disable camera panning. Default is true.
</p>
<h3>[property:Boolean enableRotate]</h3>
<p>
Enable or disable camera rotation. Default is true.
</p>
<h3>[property:Boolean enableZoom]</h3>
<p>
Enable or disable zooming of the camera.
</p>
<h3>[property:Float focusAnimationTime]</h3>
<p>
Duration time of focus animation.
</p>
<h3>[property:Float maxDistance]</h3>
<p>
How far you can dolly out ( [page:PerspectiveCamera] only ). Default is Infinity.
</p>
<h3>[property:Float maxZoom]</h3>
<p>
How far you can zoom out ( [page:OrthographicCamera] only ). Default is Infinity.
</p>
<h3>[property:Float minDistance]</h3>
<p>
How far you can dolly in ( [page:PerspectiveCamera] only ). Default is 0.
</p>
<h3>[property:Float minZoom]</h3>
<p>
How far you can zoom in ( [page:OrthographicCamera] only ). Default is 0.
</p>
<h3>[property:Float radiusFactor]</h3>
<p>
The size of the gizmo relative to the screen width and height. Default is 0.67.
</p>
<h3>[property:Float rotateSpeed]</h3>
<p>
Speed of rotation. Default is 1.
</p>
<h3>[property:Float scaleFactor]</h3>
<p>
The scaling factor used when performing zoom operation.
</p>
<h3>[property:Scene scene]</h3>
<p>
The scene rendered by the camera.
</p>
<h3>[property:Float wMax]</h3>
<p>
Maximum angular velocity allowed on rotation animation start.
</p>
<h2>Methods</h2>
<h3>[method:undefined activateGizmos] ( [param:Boolean isActive] )</h3>
<p>
Make gizmos more or less visible.
</p>
<h3>[method:undefined copyState] ()</h3>
<p>
Copy the current state to clipboard (as a readable JSON text).
</p>
<h3>[method:undefined dispose] ()</h3>
<p>
Remove all the event listeners, cancel any pending animation and clean the scene from gizmos and grid.
</p>
<h3>[method:undefined pasteState] ()</h3>
<p>
Set the controls state from the clipboard, assumes that the clipboard stores a JSON text as saved from [page:.copyState].
</p>
<h3>[method:undefined reset] ()</h3>
<p>
Reset the controls to their state from either the last time the [page:.saveState] was called, or the initial state.
</p>
<h3>[method:undefined saveState] ()</h3>
<p>
Save the current state of the controls. This can later be recovered with [page:.reset].
</p>
<h3>[method:undefined setCamera] ( [param:Camera camera] )</h3>
<p>
Set the camera to be controlled. Must be called in order to set a new camera to be controlled.
</p>
<h3>[method:undefined setGizmosVisible] ( [param:Boolean value] )</h3>
<p>
Set the visible property of gizmos.
</p>
<h3>[method:undefined setTbRadius] ( [param:Float value] )</h3>
<p>
Update the `radiusFactor` value, redraw the gizmo and send a `changeEvent` to visualise the changes.
</p>
<h3>[method:Boolean setMouseAction] ( [param:String operation], mouse, key )</h3>
<p>
Set a new mouse action by specifying the operation to be performed and a mouse/key combination. In case of conflict, replaces the existing one.<br><br>
Operations can be specified as 'ROTATE', 'PAN', 'FOV' or 'ZOOM'.<br>
Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches.<br>
Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed.
</p>
<h3>[method:Boolean unsetMouseAction] ( mouse, key )</h3>
<p>
Removes a mouse action by specifying its mouse/key combination.<br><br>
Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches.<br>
Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed.
</p>
<h3>[method:undefined update] ()</h3>
<p>
Update the controls. Must be called after any manual changes to the camera's transform.
</p>
<h3>[method:Raycaster getRaycaster] ()</h3>
<p>
Returns the [page:Raycaster] object that is used for user interaction. This object is shared between all instances of
ArcballControls. If you set the [page:Object3D.layers .layers] property of the [name], you will also want to
set the [page:Raycaster.layers .layers] property on the [page:Raycaster] with a matching value, or else the [name]
won't work as expected.
</p>
<h2>Source</h2>
<p>
[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/controls/ArcballControls.js examples/jsm/controls/ArcballControls.js]
</p>
</body>
</html>