Chapter 314: TrackballControls

Core Idea

This class is similar to OrbitControls. However, it does not maintain a constant camera up vector. That means if the camera orbits over the “north” and “south” poles, it does not flip to stay "right side up".

Key Concepts

• dynamicDampingFactor : number: Defines the intensity of damping. Only considered if staticMoving is set to false.
• keys : Array.<string>: This array holds keycodes for controlling interactions.
• maxDistance : number: How far you can dolly out (perspective camera only).
• maxZoom : number: How far you can zoom out (orthographic camera only).
• minDistance : number: How far you can dolly in (perspective camera only).
• minZoom : number: How far you can zoom in (orthographic camera only).
• mouseButtons : Object: This object contains references to the mouse actions used by the controls.
• noPan : boolean: Whether panning is disabled or not.
• noRotate : boolean: Whether rotation is disabled or not.
• noZoom : boolean: Whether zooming is disabled or not.

Code Examples

import { TrackballControls } from 'three/addons/controls/TrackballControls.js';

• What it demonstrates: Typical usage of TrackballControls.

Reference Tables

Constructor

Signature
new TrackballControls( object : Object3D, domElement : HTMLElement )

Properties

Property	Description
.dynamicDampingFactor : number	Defines the intensity of damping. Only considered if staticMoving is set to false.
.keys : Array.<string>	This array holds keycodes for controlling interactions.
.maxDistance : number	How far you can dolly out (perspective camera only).
.maxZoom : number	How far you can zoom out (orthographic camera only).
.minDistance : number	How far you can dolly in (perspective camera only).
.minZoom : number	How far you can zoom in (orthographic camera only).
.mouseButtons : Object	This object contains references to the mouse actions used by the controls.
.noPan : boolean	Whether panning is disabled or not.
.noRotate : boolean	Whether rotation is disabled or not.
.noZoom : boolean	Whether zooming is disabled or not.
.panSpeed : number	The pan speed.
.rotateSpeed : number	The rotation speed.
.screen : Object (readonly)	Represents the properties of the screen. Automatically set when handleResize() is called.
.staticMoving : boolean	Whether damping is disabled or not.
.target : Vector3	The focus point of the controls.
.zoomSpeed : number	The zoom speed.

Methods

Method	Description
.handleResize()	Must be called if the application window is resized.
.reset()	Resets the controls to its initial state.

Key Takeaways

1. TrackballControls extends: EventDispatcher → Controls
2. Most relevant properties: dynamicDampingFactor, keys, maxDistance, maxZoom.
3. Key methods: handleResize, reset.

Connects To

• EventDispatcher: parent class
• Controls: parent class
• Source: examples/jsm/controls/TrackballControls.js