timarnold/orbit-controls

generic controls for orbiting a target in 3D

orbit-controls

^{(demo) – (source)}

Generic controls for orbiting a target in 3D. Can be used to control a camera, a 3D ray, or anything with { position, direction }.

Features:

• zooms on mouse wheel
• values are smoothed with damping
• intuitive orbiting; roll is locked
• modular and un-opinionated; can be used in any render engine
• zooming with two-touch pinch

Roadmap:

• panning with two fingers / right mouse button

Can be used with any camera abstraction that uses position and direction to form the view matrix, including ThreeJS, Babylon, stackgl, etc.

Well-suited alongside perspective-camera.

Note: This module is still in development.

Example

var controls = require('orbit-controls')()

function tick () {
  controls.update()
  controls.copyInto(camera.position, camera.direction, camera.up)
}

Demos

• Canvas
• WebGL (StreetView)

Usage

controls = createControls([opts])

• position the initial position of the camera, default [0, 0, 1]
• up the initial direction of the camera, default [0, 1, 0]
• target the center of the orbit, default [0, 0, 0]
• phi the initial rotation in radians, phi in spherical coordinates, default Math.PI/2
• theta the initial rotation in radians, theta in spherical coordinates, default 0
• distance the distance from the target, default 1
• damping how fast the controls slow down, between 0 and 1, default 0.25
• rotateSpeed the speed of the rotation, default 0.28
• zoomSpeed the speed of the zoom, default 0.0075
• pinchSpeed (coming soon) the speed of the pinch, default 0.0075
• pinch (coming soon) enable pinching, default true
• zoom enable zooming, default true
• rotate enable rotating, default true
• phiBounds the bounds of the phi rotation, default [0, Math.PI]
• thetaBounds the bounds of the theta rotation, default [-Infinity, Infinity]
• distanceBounds the bounds of the distance, default [0, Infinity]
• parent the parent element, default window
• element the element, default window

methods

controls.update()

Update the internal position, direction, and up vectors that represent the camera.

controls.copyInto(position, direction, up)

Apply the control's current state to a target camera.

This is purely for convenience; you can also copy the controls.position and other members manually.

controls.enable()

Enables the DOM events and input, attaching new mouse and touch events. If already enabled, this function does nothing.

controls.disable()

Disables the DOM events and input, detaching all events. If already disabled, this function does nothing.

properties

position, direction, up

Vector arrays [x, y, z] that represent the camera controls. These are typically copied into your camera interface with:

var camera = new MyPerspectiveCamera()
controls.copyInto(camera.position, camera.direction, camera.up)

target

The vec3 center of the orbit

phi, theta

The initial rotation in radians, in spherical coordinates. Changing either will re-calculate the direction.

distance

The distance from the target, default 1

damping

How fast the controls slow down, between 0 and 1, default 0.25

rotateSpeed, zoomSpeed, pinchSpeed

The speed of the controls.

pinch, zoom, rotate

Enable pinch, zoom, and rotate

phiBounds, thetaBounds, distanceBounds

The bounds of the controls

dragging (read-only)

Returns true if the user is currently dragging the controls.

pinching (read-only)

Returns true if the user is currently pinching (zooming on mobile) the controls.

License

MIT, see LICENSE.md for details.