camera-controls

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

Examples

• basic
• fit-and-padding
• fit-to-bounding-sphere
• boundary
• focal offset
• viewport within the canvas
• z-up camera
• orthographic
• user input config
• combined gestures
• keyboard events
• rest and sleep events
• changing-cursor
• collision
• first-person
• third-person (with meshwalk)
• camera shake effect
• rotate with duration and easing (with tween.js)
• path animation (with tween.js)
• complex transitions with await
• dragging outside the iframe

Usage

import * as THREE from 'three';
import CameraControls from 'camera-controls';

CameraControls.install( { THREE: THREE } );

// snip ( init three scene... )
const clock = new THREE.Clock();
const camera = new THREE.PerspectiveCamera( 60, width / height, 0.01, 1000 );
const cameraControls = new CameraControls( camera, renderer.domElement );

( function anim () {

    // snip
    const delta = clock.getDelta();
    const hasControlsUpdated = cameraControls.update( delta );

    requestAnimationFrame( anim );

    // you can skip this condition to render though
    if ( hasControlsUpdated ) {

        renderer.render( scene, camera );

    }

} )();

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 don't want to use full of three.js (tree-shaking for example), make a subset to install.

import {
    MOUSE,
    Vector2,
    Vector3,
    Vector4,
    Quaternion,
    Matrix4,
    Spherical,
    Box3,
    Sphere,
    Raycaster,
    MathUtils,
} from 'three';

const subsetOfTHREE = {
    MOUSE     : MOUSE,
    Vector2   : Vector2,
    Vector3   : Vector3,
    Vector4   : Vector4,
    Quaternion: Quaternion,
    Matrix4   : Matrix4,
    Spherical : Spherical,
    Box3      : Box3,
    Sphere    : Sphere,
    Raycaster : Raycaster,
    MathUtils : {
        DEG2RAD: MathUtils.DEG2RAD,
        clamp: MathUtils.clamp,
    },
};

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.

Terms

Orbit rotations

CameraControls uses Spherical Coordinates for orbit rotations.

If your camera is Y-up, Azimuthal angle will be the angle for y-axis rotation and 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. Be aware colliderMeshes may decrease performance. Collision test uses 4 raycasters from camera, since near plane has 4 corners.
2. When the Dolly distance less than the minDistance, the sphere of radius will set minDistance.

Events

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

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

• * is the default.
• The default of mouseButtons.wheel is:
  • DOLLY for Perspective camera.
  • ZOOM for Orthographic camera, and can't set DOLLY.

• * is the default.
• The default of 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.

Methods

rotate( azimuthAngle, polarAngle, enableTransition )

Rotate azimuthal angle(horizontal) and polar angle(vertical).

rotateAzimuthTo( azimuthAngle, enableTransition )

Rotate azimuthal angle(horizontal) and keep the same polar angle(vertical) target.

rotatePolarTo( polarAngle, enableTransition )

Rotate polar angle(vertical) and keep the same azimuthal angle(horizontal) target.

rotateTo( azimuthAngle, polarAngle, enableTransition )

Rotate azimuthal angle(horizontal) and polar angle(vertical) to a given point.

dolly( distance, enableTransition )

Dolly in/out camera position.

dollyTo( distance, enableTransition )

Dolly in/out camera position to given distance.

zoom( zoomStep, enableTransition )

Zoom in/out of camera.

You can also make zoomIn function using camera.zoom property. e.g.

const zoomIn  = () => cameraControls.zoom(   camera.zoom / 2, true );
const zoomOut = () => cameraControls.zoom( - camera.zoom / 2, true );

zoomTo( zoom, enableTransition )

Zoom in/out camera to given scale.

truck( x, y, enableTransition )

Truck and pedestal camera using current azimuthal angle.

setFocalOffset( x, y, z, enableTransition )

Set focal offset using the screen parallel coordinates. z doesn't affect in Orthographic as with Dolly.

forward( distance, enableTransition )

Move forward / backward.

moveTo( x, y, z, enableTransition )

Move target position to given point.

fitToBox( box3OrMesh, enableTransition, { paddingTop, paddingLeft, paddingBottom, paddingRight } )

Fit the viewport to the box or the bounding box of the object, using the nearest axis. paddings are in unit.

fitToSphere( sphereOrMesh, enableTransition )

Fit the viewport to the sphere or the bounding sphere of the object.

setLookAt( positionX, positionY, positionZ, targetX, targetY, targetZ, enableTransition )

Make a orbit with given points.

lerpLookAt( positionAX, positionAY, positionAZ, targetAX, targetAY, targetAZ, positionBX, positionBY, positionBZ, targetBX, targetBY, targetBZ, t, enableTransition )

Similar to setLookAt, but it interpolates between two states.

setPosition( positionX, positionY, positionZ, enableTransition )

setLookAt without target, keep gazing at the current target.

setTarget( targetX, targetY, targetZ, enableTransition )

setLookAt without position, Stay still at the position.

setBoundary( box3? )

Set the boundary box that encloses the target of the camera. box3 is in THREE.Box3

Return its current position.

setViewport( vector4? )

Set (or unset) the current viewport.

Set this when you want to use renderer viewport and .dollyToCursor feature at the same time.

See: THREE.WebGLRenderer.setViewport()

setViewport( x, y, width, height )

Same as setViewport( vector4 ) , but you can give it four numbers that represents a viewport instead:

getPosition( out )

Return its current position.

getTarget( out )

Return its current gazing target, which is the center position of the orbit.

getFocalOffset( out )

Return its current focal offset, which is how much the camera appears to be translated in screen parallel coordinates.

saveState()

Set current camera position as the default position

normalizeRotations()

Normalize camera azimuth angle rotation between 0 and 360 degrees.

reset( enableTransition )

Reset all rotation and position to default.

update( delta ): boolean

Update camera position and directions. This should be called in your tick loop and returns true if re-rendering is needed.

updateCameraUp()

When you change camera-up vector, run .updateCameraUp() to sync.

addEventListener( type: string, listener: function )

Adds the specified event listener.

removeEventListener( type: string, listener: function )

Removes the specified event listener.

removeAllEventListeners( type: string )

Removes all listeners for the specified type.

toJSON()

Get all state in JSON string

fromJSON( json, enableTransition )

Reproduce the control state with JSON. enableTransition is where anim or not in a boolean.

dispose()

Dispose the cameraControls instance itself, remove all eventListeners.

Creating Complex Transitions

All methods that take the enableTransition parameter return a Promise can be used to create complex animations, for example:

async function complexTransition() {
    await cameraControls.rotateTo( Math.PI / 2, Math.PI / 4, true );
    await cameraControls.dollyTo( 3, true );
    await cameraControls.fitToSphere( mesh, true );
}

This will rotate the camera, then dolly, and finally fit to the bounding sphere of the mesh.

The speed and timing of transitions can be tuned using .restThreshold and .dampingFactor.

If enableTransition is false, the promise will resolve immediately:

// will resolve immediately
await cameraControls.dollyTo( 3, false );

Breaking changes

@1.16.0 dolly() will take opposite value. e.g. dolly-in to dolly( 1 ) (used be dolly-in to dolly( -1 ))

Contributors

This project exists thanks to all the people who contribute.