[page:EventDispatcher] →

[name]

Arcball controls allow the camera to be controlled by a virtual trackball with full touch support and advanced navigation functionality.
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).

In addition to supporting pan, zoom and pinch gestures, Arcball controls provide focus 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).

Unlike [page:OrbitControls] and [page:TrackballControls], [name] doesn't require [page:.update] to be called externally in an animation loop when animations are on.

To use this, as with all files in the /examples directory, you will have to include the file separately in your HTML.

Code Example

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();

Examples

[example:misc_controls_arcball misc / controls / arcball ]

Constructor

[name]( [param:Camera camera], [param:HTMLDOMElement domElement], [param:Scene scene] )

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

[page:HTMLDOMElement domElement]: The HTML element used for event listeners.

[page:Scene scene]: The scene rendered by the camera. If not given, gizmos cannot be shown.

Events

change

Fires when the camera has been transformed by the controls.

start

Fires when an interaction was initiated.

end

Fires when an interaction has finished.

Properties

.adjustNearFar : Boolean

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.

.camera : Camera

The camera being controlled.

.cursorZoom : Boolean

Set to true to make zoom become cursor centered.

.dampingFactor : Float

The damping inertia used if [page:.enableAnimations] is set to true.

.domElement : HTMLDOMElement

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.

.enabled : Boolean

When set to `false`, the controls will not respond to user input. Default is `true`.

.enableAnimations : Boolean

Set to true to enable animations for rotation (damping) and focus operation. Default is true.

.enableGrid : Boolean

When set to true, a grid will appear when panning operation is being performed (desktop interaction only). Default is false.

.enablePan : Boolean

Enable or disable camera panning. Default is true.

.enableRotate : Boolean

Enable or disable camera rotation. Default is true.

.enableZoom : Boolean

Enable or disable zooming of the camera.

.focusAnimationTime : Float

Duration time of focus animation.

.maxDistance : Float

How far you can dolly out ( [page:PerspectiveCamera] only ). Default is Infinity.

.maxZoom : Float

How far you can zoom out ( [page:OrthographicCamera] only ). Default is Infinity.

.minDistance : Float

How far you can dolly in ( [page:PerspectiveCamera] only ). Default is 0.

.minZoom : Float

How far you can zoom in ( [page:OrthographicCamera] only ). Default is 0.

.scaleFactor : Float

The scaling factor used when performing zoom operation.

.scene : Scene

The scene rendered by the camera.

.wMax : Float

Maximum angular velocity allowed on rotation animation start.

.radiusFactor : Float

The size of the gizmo relative to the screen width and height. Default is 0.67.

Methods

.activateGizmos ( [param:Boolean isActive] ) : undefined

Make gizmos more or less visible.

.copyState () : undefined

Copy the current state to clipboard (as a readable JSON text).

.dispose () : undefined

Remove all the event listeners, cancel any pending animation and clean the scene from gizmos and grid.

.pasteState () : undefined

Set the controls state from the clipboard, assumes that the clipboard stores a JSON text as saved from [page:.copyState].

.reset () : undefined

Reset the controls to their state from either the last time the [page:.saveState] was called, or the initial state.

.saveState () : undefined

Save the current state of the controls. This can later be recovered with [page:.reset].

.setCamera ( [param:Camera camera] ) : undefined

Set the camera to be controlled. Must be called in order to set a new camera to be controlled.

.setGizmosVisible ( [param:Boolean value] ) : undefined

Set the visible property of gizmos.

.setTbRadius ( [param:Float value] ) : undefined

Update the `radiusFactor` value, redraw the gizmo and send a `changeEvent` to visualise the changes.

.setMouseAction ( [param:String operation], mouse, key ) : Boolean

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.

Operations can be specified as 'ROTATE', 'PAN', 'FOV' or 'ZOOM'.
Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches.
Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed.

.unsetMouseAction ( mouse, key ) : Boolean

Removes a mouse action by specifying its mouse/key combination.

Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches.
Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed.

.update () : undefined

Update the controls. Must be called after any manual changes to the camera's transform.

.getRaycaster () : Raycaster

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.

Source

[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/controls/ArcballControls.js examples/jsm/controls/ArcballControls.js]

ArcballControls ArcballControls ArcballControls ArcballControls

ArcballControls ArcballControls ArcballControls ArcballControls