Force cancel user dragging.
Still an experimental feature. This could change at any time.
Still an experimental feature. This could change at any time.
Adds the specified event listener.
Applicable event types (which is K) are:
| Event name | Timing |
|---|---|
'controlstart' |
When the user starts to control the camera via mouse / touches. ¹ |
'control' |
When the user controls the camera (dragging). |
'controlend' |
When the user ends to control the camera. ¹ |
'transitionstart' |
When any kind of transition starts, either user control or using a method with enableTransition = true |
'update' |
When the camera position is updated. |
'wake' |
When the camera starts moving. |
'rest' |
When the camera movement is below .restThreshold ². |
'sleep' |
When the camera end moving. |
mouseButtons.wheel (Mouse wheel control) does not emit 'controlstart' and 'controlend'. mouseButtons.wheel uses scroll-event internally, and scroll-event happens intermittently. That means "start" and "end" cannot be detected.sleep will usually fire a few seconds after the camera appears to have stopped moving. If you want to do something (e.g. enable UI, perform another transition) at the point when the camera has stopped, you probably want the rest event. This can be fine tuned using the .restThreshold parameter. See the Rest and Sleep Example.e.g.
cameraControl.addEventListener( 'controlstart', myCallbackFunction );
Dolly in, but does not change the distance between the target and the camera, and moves the target position instead. Specify a negative value for dolly out.
Distance of dolly.
OptionalenableTransition: booleanWhether to move smoothly or immediately.
Fit the viewport to the box or the bounding box of the object, using the nearest axis. paddings are in unit.
set cover: true to fill enter screen.
e.g.
cameraControls.fitToBox( myMesh );
Axis aligned bounding box to fit the view.
Whether to move smoothly or immediately.
Optionaloptions: Partial<FitToOptions>| <object> { cover: boolean, paddingTop: number, paddingLeft: number, paddingBottom: number, paddingRight: number }
Transition end promise
Returns the focal offset, which is how much the camera appears to be translated in screen parallel coordinates.
The receiving Vector3 instance to copy the result
OptionalreceiveEndValue: booleanWhether receive the transition end coords or current. default is true
Similar to setLookAt, but it interpolates between two states.
OptionalenableTransition: booleanMove target position to given point.
x coord to move center position
y coord to move center position
z coord to move center position
OptionalenableTransition: booleanWhether to move smoothly or immediately
Removes the specified event listener e.g.
cameraControl.addEventListener( 'controlstart', myCallbackFunction );
Rotate azimuthal angle(horizontal) and polar angle(vertical). Every value is added to the current value.
Azimuth rotate angle. In radian.
Polar rotate angle. In radian.
OptionalenableTransition: booleanWhether to move smoothly or immediately
Rotate azimuthal angle(horizontal) to the given angle and keep the same polar angle(vertical) target.
e.g.
cameraControls.rotateAzimuthTo( 30 * THREE.MathUtils.DEG2RAD, true );
Azimuth rotate angle. In radian.
OptionalenableTransition: booleanWhether to move smoothly or immediately
Rotate polar angle(vertical) to the given angle and keep the same azimuthal angle(horizontal) target.
e.g.
cameraControls.rotatePolarTo( 30 * THREE.MathUtils.DEG2RAD, true );
Polar rotate angle. In radian.
OptionalenableTransition: booleanWhether to move smoothly or immediately
Rotate azimuthal angle(horizontal) and polar angle(vertical) to the given angle. Camera view will rotate over the orbit pivot absolutely:
azimuthAngle
0º
\
90º -----+----- -90º
\
180º
| direction | angle |
|---|---|
| front | 0º |
| left | 90º (Math.PI / 2) |
| right | -90º (- Math.PI / 2) |
| back | 180º (Math.PI) |
polarAngle
180º
|
90º
|
0º
| direction | angle |
|---|---|
| top/sky | 180º (Math.PI) |
| horizontal from view | 90º (Math.PI / 2) |
| bottom/floor | 0º |
Azimuth rotate angle to. In radian.
Polar rotate angle to. In radian.
OptionalenableTransition: booleanWhether to move smoothly or immediately
Look at the target from the position.
OptionalenableTransition: booleanSet angle and distance by given position.
An alias of setLookAt(), without target change. Thus keep gazing at the current target
OptionalenableTransition: booleanProtected_activeProtected_boundaryProtected_boundaryProtected_cameraProtected_cameraProtected_changedProtected_changedProtected_dollyProtected_dollyProtected Optional_domProtected_dragProtected_elementProtected_enabledProtected_focalProtected_focalProtected_focalProtected_focalProtected_hasProtected_interactiveProtected_isProtected_isProtected_isProtected_isProtected_isProtected_isProtected_lastProtected_lastProtected_lastProtected_lockedProtected_nearProtected_needsProtected_phiProtected_position0Protected_radiusProtected_rotateProtected_sphericalProtected_sphericalProtected_stateProtected_targetProtected_target0Protected_targetProtected_targetProtected_thetaProtected_truckProtected_updatedProtected_viewportProtected_yProtected_yProtected_zoomProtected_zoom0Protected_zoomProtected_zoomProtected_zoomReadonlyactiveReadonlycurrentThe events associated with the gamepad controls.
The parameters for the gamepad controls.
Static ReadonlyACTIONProtected_addProtected_collisionProtected_createProtected_disposeProtected_dollyProtected_encloseProtected_findProtected_findProtected_getProtected_getProtected_getProtected_removeProtected_updateStaticcreateSpeed of azimuth (horizontal) rotation.
Friction ratio of the boundary.
An array of Meshes to collide with camera. Be aware colliderMeshes may decrease performance. The collision test uses 4 raycasters from the camera since the near plane has 4 corners.
true to invert direction when dollying or zooming via drag
Speed of mouse-wheel dollying.
true to enable Dolly-in to the mouse cursor coords.
the smoothTime while dragging
true to enable Infinity Dolly for wheel and pinch. Use this with minDistance and maxDistance
If the Dolly distance is less (or over) than the minDistance (or maxDistance), infinityDolly will keep the distance and pushes the target position instead.
Maximum horizontal angle in radians.
The angle has to be greater than .minAzimuthAngle.
The default value is Infinity.
e.g.
cameraControls.maxAzimuthAngle = Infinity;
Maximum distance for dolly. The value must be higher than minDistance. Default is Infinity.
PerspectiveCamera only.
Maximum vertical angle in radians.
The angle has to be between .maxPolarAngle and Math.PI inclusive.
The default value is Math.PI.
e.g.
cameraControls.maxPolarAngle = Math.PI;
Max transition speed in unit-per-seconds
Maximum camera zoom.
Minimum horizontal angle in radians.
The angle has to be less than .maxAzimuthAngle.
The default value is - Infinity.
e.g.
cameraControls.minAzimuthAngle = - Infinity;
Minimum distance for dolly. The value must be higher than 0. Default is Number.EPSILON.
PerspectiveCamera only.
Minimum vertical angle in radians.
The angle has to be between 0 and .maxPolarAngle inclusive.
The default value is 0.
e.g.
cameraControls.maxPolarAngle = 0;
Minimum camera zoom.
User's mouse input config.
| button to assign | behavior |
|---|---|
mouseButtons.left |
CameraControls.ACTION.ROTATE* | CameraControls.ACTION.TRUCK | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.right |
CameraControls.ACTION.ROTATE | CameraControls.ACTION.TRUCK* | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.wheel ¹ |
CameraControls.ACTION.ROTATE | CameraControls.ACTION.TRUCK | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.middle ² |
CameraControls.ACTION.ROTATE | CameraControls.ACTION.TRUCK | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY* | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.wheel is:
DOLLY for Perspective camera.ZOOM for Orthographic camera, and can't set DOLLY.Speed of polar (vertical) rotation.
Controls how soon the rest event fires as the camera slows.
Approximate time in seconds to reach the target. A smaller value will reach the target faster.
User's touch input config.
| fingers to assign | behavior |
|---|---|
touches.one |
CameraControls.ACTION.TOUCH_ROTATE* | CameraControls.ACTION.TOUCH_TRUCK | CameraControls.ACTION.TOUCH_OFFSET | CameraControls.ACTION.DOLLY |
touches.two |
ACTION.TOUCH_DOLLY_TRUCK | ACTION.TOUCH_DOLLY_OFFSET | ACTION.TOUCH_DOLLY_ROTATE | ACTION.TOUCH_ZOOM_TRUCK | ACTION.TOUCH_ZOOM_OFFSET | ACTION.TOUCH_ZOOM_ROTATE | ACTION.TOUCH_DOLLY | ACTION.TOUCH_ZOOM | CameraControls.ACTION.TOUCH_ROTATE | CameraControls.ACTION.TOUCH_TRUCK | CameraControls.ACTION.TOUCH_OFFSET | CameraControls.ACTION.NONE |
touches.three |
ACTION.TOUCH_DOLLY_TRUCK | ACTION.TOUCH_DOLLY_OFFSET | ACTION.TOUCH_DOLLY_ROTATE | ACTION.TOUCH_ZOOM_TRUCK | ACTION.TOUCH_ZOOM_OFFSET | ACTION.TOUCH_ZOOM_ROTATE | CameraControls.ACTION.TOUCH_ROTATE | CameraControls.ACTION.TOUCH_TRUCK | CameraControls.ACTION.TOUCH_OFFSET | CameraControls.ACTION.NONE |
touches.two and touches.three is:
TOUCH_DOLLY_TRUCK for Perspective camera.TOUCH_ZOOM_TRUCK for Orthographic camera, and can't set TOUCH_DOLLY_TRUCK and TOUCH_DOLLY.Speed of drag for truck and pedestal.
The same as .screenSpacePanning in three.js's OrbitControls.
StaticinstallInjects THREE as the dependency. You can then proceed to use CameraControls.
e.g
CameraControls.install( { THREE: THREE } );
Note: If you do not wish to use enter three.js to reduce file size(tree-shaking for example), make a subset to install.
import {
Vector2,
Vector3,
Vector4,
Quaternion,
Matrix4,
Spherical,
Box3,
Sphere,
Raycaster,
MathUtils,
} from 'three';
const subsetOfTHREE = {
Vector2 : Vector2,
Vector3 : Vector3,
Vector4 : Vector4,
Quaternion: Quaternion,
Matrix4 : Matrix4,
Spherical : Spherical,
Box3 : Box3,
Sphere : Sphere,
Raycaster : Raycaster,
};
CameraControls.install( { THREE: subsetOfTHREE } );
GamepadCameraControls extends the CameraControls class to provide camera control using a gamepad. It listens for gamepad connection and disconnection events and processes gamepad input to control the camera's rotation, movement, zoom, and elevation.