# orbit-controls

> generic controls for orbiting a target in 3D

Latest version **1.2.4** (published 2018-01-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install orbit-controls
pnpm add orbit-controls
yarn add orbit-controls
bun add orbit-controls
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.4 |
| Published | 2018-01-04 |
| First published | 2015-09-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 8 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Matt DesLauriers |
| Maintainers | mattdesl, tatumcreative |
| Keywords | orbit, camera, control, controls, perpsective, perspective-camera, 3d, 2d, webgl, stackgl |

## Links

- npm: https://www.npmjs.com/package/orbit-controls
- Repository: https://github.com/Jam3/orbit-controls
- Issues: https://github.com/Jam3/orbit-controls/issues
- npm.io page: https://npm.io/package/orbit-controls

## Dependencies (8)

- [clamp](https://npm.io/package/clamp.md) ^1.0.1
- [defined](https://npm.io/package/defined.md) ^1.0.0
- [gl-quat](https://npm.io/package/gl-quat.md) ^1.0.0
- [gl-vec3](https://npm.io/package/gl-vec3.md) ^1.0.3
- [mouse-wheel](https://npm.io/package/mouse-wheel.md) ^1.2.0
- [touch-pinch](https://npm.io/package/touch-pinch.md) ^1.0.0
- [mouse-event-offset](https://npm.io/package/mouse-event-offset.md) ^3.0.2
- [quat-from-unit-vec3](https://npm.io/package/quat-from-unit-vec3.md) ^1.0.0

## Recent versions

- 1.2.4 (latest) — 2018-01-04
- 1.2.3 — 2018-01-04
- 1.2.2 — 2018-01-04
- 1.2.1 — 2018-01-04
- 1.2.0 — 2017-07-28
- 1.1.3 — 2017-04-12
- 1.1.2 — 2017-01-27
- 1.1.1 — 2016-07-06
- 1.1.0 — 2016-07-06
- 1.0.4 — 2016-02-22
- 1.0.3 — 2016-02-21
- 1.0.2 — 2016-02-21
- 1.0.1 — 2016-02-05
- 1.0.0 — 2016-01-25
- 0.0.1 — 2015-10-03
- … 1 more at https://npm.io/package/orbit-controls/versions

## README

# orbit-controls

[![experimental](http://badges.github.io/stability-badges/dist/experimental.svg)](http://github.com/badges/stability-badges)

<img src="http://i.imgur.com/d3vtXo1.png" width="75%" />  

<sup>[(demo)](http://jam3.github.io/orbit-controls/demo/canvas.html) – [(source)](./demo/canvas.js)</sup>

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](https://github.com/Jam3/perspective-camera).

> *Note:* This module is still in development.

## Example

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

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

## Demos

- [Canvas](http://jam3.github.io/orbit-controls/demo/canvas.html)
- [WebGL (StreetView)](http://jam3.github.io/orbit-controls/demo/three.html)

## Usage

[![NPM](https://nodei.co/npm/orbit-controls.png)](https://www.npmjs.com/package/orbit-controls)

#### `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:

```js
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](http://github.com/Jam3/orbit-controls/blob/master/LICENSE.md) for details.

---
_Source: https://npm.io/package/orbit-controls · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._