Reference Source
public class | source

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.

Listen for view matrix 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;

Listen for projection matrix updates:

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

See: https://en.wikipedia.org/wiki/Gimbal_lock

Member Summary

Public Members
public set

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

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

Gets whether to prevent camera from being pitched upside down.

public get

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

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

public get

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

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

Gets the Camera's projection transformation projMatrix.

Fires a Camera#projMatrix:event event on change.

public get

Gets the currently active projection for this Camera.

public set

projection(value: String)

Sets the active projection type.

public get

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

Gets the Camera's viewing transformation matrix.

Fires a Camera#matrix:event event on change.

public get

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

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

public get

Gets the direction of World-space "forwards".

public get

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

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

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

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

public set constrainPitch(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.

public get customProjection: CustomProjection: * source

Gets the Camera's custom projection.

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

Return:

CustomProjection

The custom projection.

public set deviceMatrix(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.

public get deviceMatrix: Number[]: * source

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

Return:

Number[]

The matrix.

public set eye: 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.

public get eye: Number[] source

Gets the position of the Camera's eye.

Default vale is [0,0,10].

public get eyeLookDist: 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.

public get frustum: Frustum: * source

Gets the Camera's frustum projection.

The Camera uses this while Camera#projection equals frustum.

Return:

Frustum

The Ortho component.

public set gimbalLock source

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

Fires a Camera#gimbalLock:event event on change.

public get gimbalLock: Boolean: * source

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

Return:

Boolean

Returns true if gimbal is locked.

public get inverseViewMatrix: 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.

public set look(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.

public get look: Number[]: * source

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

Default value is [0,0,0].

Return:

Number[]

Camera look position.

public get matrix: Number[]: * source

Gets the Camera's viewing transformation matrix.

Fires a Camera#matrix:event event on change.

Return:

Number[]

The viewing transform matrix.

public get normalMatrix: Number[]: * source

The Camera's viewing normal transformation matrix.

Fires a Camera#matrix:event event on change.

Return:

Number[]

The viewing normal transform matrix.

public get ortho: Ortho: * source

Gets the Camera's orthographic projection.

The Camera uses this while Camera#projection equals ortho.

Return:

Ortho

The Ortho component.

public get perspective: Perspective: * source

Gets the Camera's perspective projection.

The Camera uses this while Camera#projection equals perspective.

Return:

Perspective

The Perspective component.

public get projMatrix: Number[]: * source

Gets the Camera's projection transformation projMatrix.

Fires a Camera#projMatrix:event event on change.

Return:

Number[]

The projection matrix.

public get project: 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.

public set projection(value: String) source

Sets the active projection type.

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

Default value is "perspective".

public get projection: 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.

public set up(up: Number[]) source

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

Emit:

*

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

public get up: Number[]: * source

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

Return:

Number[]

Direction of "up".

public get viewMatrix: Number[]: * source

Gets the Camera's viewing transformation matrix.

Fires a Camera#matrix:event event on change.

Return:

Number[]

The viewing transform matrix.

public get viewNormalMatrix: Number[]: * source

The Camera's viewing normal transformation matrix.

Fires a Camera#matrix:event event on change.

Return:

Number[]

The viewing normal transform matrix.

public set worldAxis(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]

public get worldAxis: 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.

public get worldForward: 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.

public get worldRight: 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.

public get worldUp: 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.

public get xUp: Boolean: * source

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

Return:

Boolean

public get yUp: Boolean: * source

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

Return:

Boolean

public get zUp: Boolean: * source

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

Return:

Boolean

Public Methods

public destroy() source

Destroys this Camera.

Override:

Component#destroy

public orbitPitch(angleInc: Number) source

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

Params:

NameTypeAttributeDescription
angleInc Number

Angle of rotation in degrees

public orbitYaw(angleInc: Number) source

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

Params:

NameTypeAttributeDescription
angleInc Number

Angle of rotation in degrees

public pan(pan: *) source

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

Params:

NameTypeAttributeDescription
pan *

The pan vector

public pitch(angleInc: Number) source

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

Params:

NameTypeAttributeDescription
angleInc Number

Angle of rotation in degrees

public projectWorldPos(worldPos: [number, number, number]): [number, number] source

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

Params:

NameTypeAttributeDescription
worldPos [number, number, number]

Return:

[number, number]

the canvas position

public yaw(angleInc: Number) source

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

Params:

NameTypeAttributeDescription
angleInc Number

Angle of rotation in degrees

public zoom(delta: Number) source

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

Params:

NameTypeAttributeDescription
delta Number

Zoom factor increment.