Reference Source
``import {Camera} from '@xeokit/xeokit-sdk/src/viewer/scene/camera/Camera.js'``
public class

# Camera

#### Extends:

Component → Camera

Manages viewing and projection transforms for its Scene.

## Getting the Camera

There is exactly one Camera per Scene:

``````import {Viewer} from "xeokit-sdk.es.js";

var camera = viewer.scene.camera;

``````

## Setting the Camera Position

Get and set the Camera's absolute position via Camera#eye, Camera#look and Camera#up:

``````camera.eye = [-10,0,0];
camera.look = [-10,0,0];
camera.up = [0,1,0];
``````

## Camera View and Projection Matrices

The Camera's view matrix transforms coordinates from World-space to View-space.

Getting the view matrix:

``````var viewMatrix = camera.viewMatrix;
var viewNormalMatrix = camera.normalMatrix;
``````

The Camera's view normal matrix transforms normal vectors from World-space to View-space.

Getting the view normal matrix:

``````var viewNormalMatrix = camera.normalMatrix;
``````

The Camera fires a `"viewMatrix"` event whenever the Camera#viewMatrix and Camera#viewNormalMatrix updates.

``````camera.on("viewMatrix", function(matrix) { ... });
``````

## Rotating the Camera

Orbiting the Camera#look position:

``````camera.orbitYaw(20.0);
camera.orbitPitch(10.0);
``````

First-person rotation, rotates Camera#look and Camera#up about Camera#eye:

``````camera.yaw(5.0);
camera.pitch(-10.0);
``````

## Panning the Camera

Panning along the Camera's local axis (ie. left/right, up/down, forward/backward):

``````camera.pan([-20, 0, 10]);
``````

## Zooming the Camera

Zoom to vary distance between Camera#eye and Camera#look:

``````camera.zoom(-5); // Move five units closer
``````

Get the current distance between Camera#eye and Camera#look:

``````var distance = camera.eyeLookDist;
``````

## Projection

The Camera has a Component to manage each projection type, which are: Perspective, Ortho and Frustum and CustomProjection.

You can configure those components at any time, regardless of which is currently active:

The Camera has a Perspective to manage perspective

``````
// Set some properties on Perspective
camera.perspective.near = 0.4;
camera.perspective.fov = 45;

// Set some properties on Ortho
camera.ortho.near = 0.8;
camera.ortho.far = 1000;

// Set some properties on Frustum
camera.frustum.left = -1.0;
camera.frustum.right = 1.0;
camera.frustum.far = 1000.0;

// Set the matrix property on CustomProjection
camera.customProjection.matrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];

// Switch between the projection types
camera.projection = "perspective"; // Switch to perspective
camera.projection = "frustum"; // Switch to frustum
camera.projection = "ortho"; // Switch to ortho
camera.projection = "customProjection"; // Switch to custom
``````

Camera provides the projection matrix for the currently active projection in Camera#projMatrix.

Get the projection matrix:

``````var projMatrix = camera.projMatrix;
``````

``````camera.on("projMatrix", function(matrix) { ... });
``````

## Configuring World up direction

We can dynamically configure the directions of the World-space coordinate system.

Setting the +Y axis as World "up", +X as right and -Z as forwards (convention in some modeling software):

``````camera.worldAxis = [
1, 0, 0,    // Right
0, 1, 0,    // Up
0, 0,-1     // Forward
];
``````

Setting the +Z axis as World "up", +X as right and -Y as "up" (convention in most CAD and BIM viewers):

``````camera.worldAxis = [
1, 0, 0, // Right
0, 0, 1, // Up
0,-1, 0  // Forward
];
``````

The Camera has read-only convenience properties that provide each axis individually:

``````var worldRight = camera.worldRight;
var worldForward = camera.worldForward;
var worldUp = camera.worldUp;
``````

### Gimbal locking

By default, the Camera locks yaw rotation to pivot about the World-space "up" axis. We can dynamically lock and unlock that at any time:

``````camera.gimbalLock = false; // Yaw rotation now happens about Camera's local Y-axis
camera.gimbalLock = true; // Yaw rotation now happens about World's "up" axis
``````

## Member Summary

 Public Members public set constrainPitch(value: Boolean) Sets whether to prevent camera from being pitched upside down. public get Gets the Camera's custom projection. This is used while Camera#projection equals "customProjection". public set deviceMatrix(matrix: Number[]) Sets an optional matrix to premultiply into Camera#matrix matrix. public get deviceMatrix: Number[]: * Gets an optional matrix to premultiply into Camera#matrix matrix. public set eye: Number[] Sets the position of the Camera's eye. Default value is `[0,0,10]`. public get eye: Number[] Gets the position of the Camera's eye. Default vale is `[0,0,10]`. public get eyeLookDist: Number: * Gets whether to prevent camera from being pitched upside down. public get frustum: Frustum: * Gets the Camera's frustum projection. The Camera uses this while Camera#projection equals `frustum`. public set Sets whether to lock yaw rotation to pivot about the World-space "up" axis. public get gimbalLock: Boolean: * Gets whether to lock yaw rotation to pivot about the World-space "up" axis. public get inverseViewMatrix: Number[]: * Gets the inverse of the Camera's viewing transform matrix. This has the same value as Camera#normalMatrix. public set look(look: Number[]) Sets the position of this Camera's point-of-interest. Default value is `[0,0,0]`. public get look: Number[]: * Gets the position of this Camera's point-of-interest. Default value is `[0,0,0]`. public get matrix: Number[]: * Gets the Camera's viewing transformation matrix. Fires a Camera#matrix:event event on change. public get normalMatrix: Number[]: * The Camera's viewing normal transformation matrix. Fires a Camera#matrix:event event on change. public get ortho: Ortho: * Gets the Camera's orthographic projection. The Camera uses this while Camera#projection equals `ortho`. public get Gets the Camera's perspective projection. The Camera uses this while Camera#projection equals `perspective`. public get projMatrix: Number[]: * Gets the Camera's projection transformation projMatrix. Fires a Camera#projMatrix:event event on change. public get project Gets the currently active projection for this Camera. public set projection(value: String) Sets the active projection type. public get projection: String: * Gets the active projection type. public set up(up: Number[]) Sets the direction of this Camera's Camera#up vector. public get up: Number[]: * Gets the direction of this Camera's Camera#up vector. public get viewMatrix: Number[]: * Gets the Camera's viewing transformation matrix. Fires a Camera#matrix:event event on change. public get viewNormalMatrix: Number[]: * The Camera's viewing normal transformation matrix. Fires a Camera#matrix:event event on change. public set worldAxis(axis: Number[]) Sets the up, right and forward axis of the World coordinate system. public get worldAxis: Number[]: * Gets the up, right and forward axis of the World coordinate system. public get worldForward: Number[]: * Gets the direction of World-space "forwards". public get worldRight: Number[]: * Gets the direction of World-space "right". public get worldUp: Number[]: * Gets the direction of World-space "up". public get xUp: Boolean: * Gets if the World-space X-axis is "up". public get yUp: Boolean: * Gets if the World-space Y-axis is "up". public get zUp: Boolean: * Gets if the World-space Z-axis is "up".

## Method Summary

 Public Methods public destroy() Destroys this Camera. public orbitPitch(angleInc: Number) Rotates Camera#eye about Camera#look around the right axis (orthogonal to Camera#up and "look"). public orbitYaw(angleInc: Number) Rotates Camera#eye about Camera#look, around the Camera#up vector public pan(pan: *) Pans the Camera along its local X, Y and Z axis. public pitch(angleInc: Number) Rotates Camera#look about Camera#eye, around the right axis (orthogonal to Camera#up and "look"). public projectWorldPos(worldPos: [number, number, number]): [number, number] Get the 2D canvas position of a 3D world position. public yaw(angleInc: Number) Rotates Camera#look about Camera#eye, around the Camera#up vector. public zoom(delta: Number) Increments/decrements the Camera's zoom factor, which is the distance between Camera#eye and Camera#look.

## Inherited Summary

 From class Component public get The Component that owns the lifecycle of this Component, if any. public True as soon as this Component has been destroyed public id ID of this Component, unique within the Scene. public meta: * Arbitrary, user-defined metadata on this component. public The parent Scene that contains this Component. public The viewer that contains this Scene. public clear() Destroys all Components that are owned by this. public destroy() Destroys this component. public error(message: String) Logs an error for this component to the JavaScript console. public fire(event: String, value: Object, forget: Boolean) Fires an event on this component. public hasSubs(event: String): Boolean Returns true if there are any subscribers to the given event on this component. public isType(type: *): *: Boolean Tests if this component is of the given type, or is a subclass of the given type. public log(message: String) Logs a console debugging message for this component. public off(subId: String) Cancels an event subscription that was previously made with Component#on or Component#once. public on(event: String, callback: Function, scope: Object): String Subscribes to an event on this component. public once(event: String, callback: Function, scope: Object) Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd. public scheduleTask(task: *) Schedule a task to perform on the next browser interval public warn(message: String) Logs a warning for this component to the JavaScript console.

## Public Members

### publicsetconstrainPitch(value: Boolean) source

Sets whether to prevent camera from being pitched upside down.

The camera is upside down when the angle between Camera#up and Camera#worldUp is less than one degree.

Fires a Camera#constrainPitch:event event on change.

Default value is `false`.

### publicgetcustomProjection: CustomProjection: * source

Gets the Camera's custom projection.

This is used while Camera#projection equals "customProjection".

#### Return:

 CustomProjection The custom projection.

### publicsetdeviceMatrix(matrix: Number[]) source

Sets an optional matrix to premultiply into Camera#matrix matrix.

This is intended to be used for stereo rendering with WebVR etc.

### publicgetdeviceMatrix: Number[]: * source

Gets an optional matrix to premultiply into Camera#matrix matrix.

#### Return:

 Number[] The matrix.

### publicseteye: Number[] source

Sets the position of the Camera's eye.

Default value is `[0,0,10]`.

#### Emit:

 * "eye" event on change, with the value of this property.

### publicgeteye: Number[] source

Gets the position of the Camera's eye.

Default vale is `[0,0,10]`.

### publicgeteyeLookDist: Number: * source

Gets whether to prevent camera from being pitched upside down.

The camera is upside down when the angle between Camera#up and Camera#worldUp is less than one degree.

Default value is `false`.

#### Return:

 Number The distance.

### publicgetfrustum: Frustum: * source

Gets the Camera's frustum projection.

The Camera uses this while Camera#projection equals `frustum`.

#### Return:

 Frustum The Ortho component.

### publicsetgimbalLock source

Sets whether to lock yaw rotation to pivot about the World-space "up" axis.

Fires a Camera#gimbalLock:event event on change.

### publicgetgimbalLock: Boolean: * source

Gets whether to lock yaw rotation to pivot about the World-space "up" axis.

#### Return:

 Boolean Returns `true` if gimbal is locked.

### publicgetinverseViewMatrix: Number[]: * source

Gets the inverse of the Camera's viewing transform matrix.

This has the same value as Camera#normalMatrix.

#### Return:

 Number[] The inverse viewing transform matrix.

### publicsetlook(look: Number[]) source

Sets the position of this Camera's point-of-interest.

Default value is `[0,0,0]`.

#### Emit:

 * "look" event on change, with the value of this property.

### publicgetlook: Number[]: * source

Gets the position of this Camera's point-of-interest.

Default value is `[0,0,0]`.

#### Return:

 Number[] Camera look position.

### publicgetmatrix: Number[]: * source

Gets the Camera's viewing transformation matrix.

Fires a Camera#matrix:event event on change.

#### Return:

 Number[] The viewing transform matrix.

### publicgetnormalMatrix: Number[]: * source

The Camera's viewing normal transformation matrix.

Fires a Camera#matrix:event event on change.

#### Return:

 Number[] The viewing normal transform matrix.

### publicgetortho: Ortho: * source

Gets the Camera's orthographic projection.

The Camera uses this while Camera#projection equals `ortho`.

#### Return:

 Ortho The Ortho component.

### publicgetperspective: Perspective: * source

Gets the Camera's perspective projection.

The Camera uses this while Camera#projection equals `perspective`.

#### Return:

 Perspective The Perspective component.

### publicgetprojMatrix: Number[]: * source

Gets the Camera's projection transformation projMatrix.

Fires a Camera#projMatrix:event event on change.

#### Return:

 Number[] The projection matrix.

### publicgetproject: Perspective | Ortho | Frustum | CustomProjection: * source

Gets the currently active projection for this Camera.

The currently active project is selected with Camera#projection.

#### Return:

 Perspective | Ortho | Frustum | CustomProjection The currently active projection is active.

### publicsetprojection(value: String) source

Sets the active projection type.

Accepted values are `"perspective"`, `"ortho"`, `"frustum"` and `"customProjection"`.

Default value is `"perspective"`.

### publicgetprojection: String: * source

Gets the active projection type.

Possible values are `"perspective"`, `"ortho"`, `"frustum"` and `"customProjection"`.

Default value is `"perspective"`.

#### Return:

 String Identifies the active projection type.

### publicsetup(up: Number[]) source

Sets the direction of this Camera's Camera#up vector.

#### Emit:

 * "up" event on change, with the value of this property.

### publicgetup: Number[]: * source

Gets the direction of this Camera's Camera#up vector.

#### Return:

 Number[] Direction of "up".

### publicgetviewMatrix: Number[]: * source

Gets the Camera's viewing transformation matrix.

Fires a Camera#matrix:event event on change.

#### Return:

 Number[] The viewing transform matrix.

### publicgetviewNormalMatrix: Number[]: * source

The Camera's viewing normal transformation matrix.

Fires a Camera#matrix:event event on change.

#### Return:

 Number[] The viewing normal transform matrix.

### publicsetworldAxis(axis: Number[]) source

Sets the up, right and forward axis of the World coordinate system.

Has format: `[rightX, rightY, rightZ, upX, upY, upZ, forwardX, forwardY, forwardZ]`

Default axis is `[1, 0, 0, 0, 1, 0, 0, 0, 1]`

### publicgetworldAxis: Number[]: * source

Gets the up, right and forward axis of the World coordinate system.

Has format: `[rightX, rightY, rightZ, upX, upY, upZ, forwardX, forwardY, forwardZ]`

Default axis is `[1, 0, 0, 0, 1, 0, 0, 0, 1]`

#### Return:

 Number[] The current World coordinate axis.

### publicgetworldForward: Number[]: * source

Gets the direction of World-space "forwards".

This is set by Camera#worldAxis.

Default value is `[0,0,1]`.

#### Return:

 Number[] The "up" vector.

### publicgetworldRight: Number[]: * source

Gets the direction of World-space "right".

This is set by Camera#worldAxis.

Default value is `[1,0,0]`.

#### Return:

 Number[] The "up" vector.

### publicgetworldUp: Number[]: * source

Gets the direction of World-space "up".

This is set by Camera#worldAxis.

Default value is `[0,1,0]`.

#### Return:

 Number[] The "up" vector.

### publicgetxUp: Boolean: * source

Gets if the World-space X-axis is "up".

### publicgetyUp: Boolean: * source

Gets if the World-space Y-axis is "up".

### publicgetzUp: Boolean: * source

Gets if the World-space Z-axis is "up".

## Public Methods

### publicdestroy() source

Destroys this Camera.

#### Override:

Component#destroy

### publicorbitPitch(angleInc: Number) source

Rotates Camera#eye about Camera#look around the right axis (orthogonal to Camera#up and "look").

#### Params:

 Name Type Attribute Description angleInc Number Angle of rotation in degrees

### publicorbitYaw(angleInc: Number) source

Rotates Camera#eye about Camera#look, around the Camera#up vector

#### Params:

 Name Type Attribute Description angleInc Number Angle of rotation in degrees

### publicpan(pan: *) source

Pans the Camera along its local X, Y and Z axis.

#### Params:

 Name Type Attribute Description pan * The pan vector

### publicpitch(angleInc: Number) source

Rotates Camera#look about Camera#eye, around the right axis (orthogonal to Camera#up and "look").

#### Params:

 Name Type Attribute Description angleInc Number Angle of rotation in degrees

### publicprojectWorldPos(worldPos: [number, number, number]): [number, number] source

Get the 2D canvas position of a 3D world position.

#### Params:

 Name Type Attribute Description worldPos [number, number, number]

#### Return:

 [number, number] the canvas position

### publicyaw(angleInc: Number) source

Rotates Camera#look about Camera#eye, around the Camera#up vector.

#### Params:

 Name Type Attribute Description angleInc Number Angle of rotation in degrees

### publiczoom(delta: Number) source

Increments/decrements the Camera's zoom factor, which is the distance between Camera#eye and Camera#look.

#### Params:

 Name Type Attribute Description delta Number Zoom factor increment.