camera-controls

camera-controls

A camera control for three.js, similar to THREE.OrbitControls yet supports smooth transitions and more features.

documentation

Examples

• basic
• fit-and-padding
• fit-to-rect
• fit-to-bounding-sphere
• infinity dolly
• boundary
• focal offset
• click to set orbit point
• look in the point direction
• viewport within the canvas
• multiple camera-controls and viewport
• z-up camera
• orthographic
• event attach / detach
• user input config
• mouse drag with modifier keys
• combined gestures
• keyboard events
• rest and sleep events
• changing the cursor
• collision
• collision (custom)
• first-person
• third-person (with meshwalk)
• pointer lock
• auto rotate
• view offset translate
• camera shake effect
• rotate with time duration and easing (with gsap)
• path animation (with gsap)
• complex transitions with await
• set view padding
• WebWorker (OffscreenCanvas)
• outside of iframe dragging
• in react-three-fiber (simplest)
• in react-three-fiber (drei official) (see doc)

Usage

(The below code is for three.js users. If you use react-three-fiber (aka R3F), r3f-ready camera-controls is available on @react-three/drei

…

Important!

You must install three.js before using camera-controls. Not doing so will lead to runtime errors (undefined references to THREE).

Before creating a new CameraControls instance, call:

CameraControls.install( { THREE: THREE } );

You can then proceed to use CameraControls.

Note: If you do not wish to use the entire 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,
} 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 } );

Constructor

CameraControls( camera, domElement )

• camera is a THREE.PerspectiveCamera or THREE.OrthographicCamera to be controlled.
• domElement is a HTMLElement for draggable area. (optional. if domElement is omitted here, can be connect later with .connect())

Terms

Orbit rotations

CameraControls uses Spherical Coordinates for orbit rotations.

If your camera is Y-up, the Azimuthal angle will be the angle for y-axis rotation and the Polar angle will be the angle for vertical position.

Dolly vs Zoom

• A Zoom involves changing the lens focal length. In three.js, zooming is actually changing the camera FOV, and the camera is stationary (doesn't move).
• A Dolly involves physically moving the camera to change the composition of the image in the frame.

See the demo

Properties

1. Every 360 degrees turn is added to .azimuthAngle value, which is accumulative.
   360º = 360 * THREE.MathUtils.DEG2RAD = Math.PI * 2, 720º = Math.PI * 4.
   Tip: How to normalize accumulated azimuthAngle?
2. Be aware colliderMeshes may decrease performance. The collision test uses 4 raycasters from the camera since the near plane has 4 corners.
3. If the Dolly distance is less (or over) than the minDistance (or maxDistance), infinityDolly will keep the distance and pushes the target position instead.

Events

CameraControls instance emits the following events.
To subscribe, use cameraControl.addEventListener( 'eventname', function ).
To unsubscribe, use cameraControl.removeEventListener( 'eventname', function ).

1. 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.
2. Due to damping, 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.

User input config

Working example: user input config