You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
282 lines
8.7 KiB
282 lines
8.7 KiB
2 years ago
|
<!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>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 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>
|
||
|
|
|
||
|
|
<h3>[property:Float radiusFactor]</h3>
|
||
|
|
<p>
|
||
|
|
The size of the gizmo relative to the screen width and height. Default is 0.67.
|
||
|
|
</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>
|