Class Camera

Controls the viewpoint and projection for a @xeokit/viewer!View.

Summary

Getting a View's Camera

Let's create a Viewer with a single @xeokit/viewer!View, from which we'll get a Camera:

const viewer = new Viewer();

const view = new View(viewer, {
     elementId: "myCanvas1"
});

const camera = view.camera;

Setting the Camera Position

Get and set the Camera's absolute position:

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:

var viewMatrix = camera.viewMatrix;

Camera.onViewMatrix fires whenever Camera.viewMatrix updates:

camera.onViewMatrix.subscribe((camera, matrix) => { ... });

Rotating the Camera

Orbiting the Camera.look position:

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

Perform a first-person rotation, in which we rotate Camera.look and Camera.up about Camera.eye:

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

Panning the Camera

Pan 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: PerspectiveProjection, OrthoProjection and FrustumProjection and CustomProjection.

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

The Camera has a PerspectiveProjection to manage perspective


// Set some properties on PerspectiveProjection
camera.perspectiveProjection.near = 0.4;
camera.perspectiveProjection.fov = 45;

// Set some properties on OrthoProjection
camera.orthoProjection.near = 0.8;
camera.orthoProjection.far = 1000;

// Set some properties on FrustumProjection
camera.frustumProjection.left = -1.0;
camera.frustumProjection.right = 1.0;
camera.frustumProjection.far = 1000.0;

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

// Switch between the projection types
Camera.projectionType = PerspectiveProjectionType; // Switch to perspective
Camera.projectionType = FrustumProjectiontype; // Switch to frustum
Camera.projectionType = OrthoProjectionType; // Switch to ortho
Camera.projectionType = CustomProjectionType; // 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.onProjMatrix((camera, 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

Hierarchy

  • Component
    • Camera

Properties

customProjection destroyed dirty frustumProjection id orthoProjection perspectiveProjection view

Accessors

constrainPitch deviceMatrix eye eyeLookDist frustum gimbalLock inverseViewMatrix look projMatrix projection projectionType up viewMatrix worldAxis worldForward worldRight worldUp xUp yUp zUp

Methods

clean cleanIfDirty error log orbitPitch orbitYaw pan pitch setDirty warn yaw zoom

Events

onDestroyed onFrustum onProjMatrix onProjectionType onViewMatrix onWorldAxis

Properties

Readonly customProjection

customProjection: CustomProjection

The custom projection.

The Camera uses this while Camera.projectionType equals @xeokit/constants!CustomProjectionType.

destroyed

destroyed: boolean

True once this Component has been destroyed.

Don't use this Component if this is true.

Protected dirty

dirty: boolean

Readonly frustumProjection

frustumProjection: FrustumProjection

The frustum projection.

The Camera uses this while Camera.projectionType equals @xeokit/constants!FrustumProjectionType.

id

id: string

Unique ID of this Component.

Readonly orthoProjection

orthoProjection: OrthoProjection

The orthographic projection.

The Camera uses this while Camera.projectionType equals @xeokit/constants!OrthoProjectionType.

Readonly perspectiveProjection

perspectiveProjection: PerspectiveProjection

The perspective projection.

The Camera uses this while Camera.projectionType equals PerspectiveProjectionType.

Readonly view

view: View

The View to which this Camera belongs.

Final

Accessors

constrainPitch

  • get constrainPitch(): boolean

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

    Returns boolean

    true if pitch rotation is currently constrained.

  • set constrainPitch(value): void

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

    Default value is false.

    Parameters

    • value: boolean

      Set true to contrain pitch rotation.

    Returns void

deviceMatrix

  • get deviceMatrix(): FloatArrayParam

  • Gets an optional matrix to premultiply into Camera.projMatrix matrix.

    Returns FloatArrayParam

    The matrix.

  • set deviceMatrix(matrix): void

  • Sets an optional matrix to premultiply into Camera.projMatrix matrix.

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

    Parameters

    • matrix: FloatArrayParam

      The matrix.

    Returns void

eye

  • get eye(): FloatArrayParam

  • Gets the position of the Camera's eye.

    Default vale is [0,0,10].

    Returns FloatArrayParam

  • set eye(eye): void

  • Sets the position of the Camera's eye.

    Default value is [0,0,10].

    Parameters

    • eye: FloatArrayParam

    Returns void

    Emits

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

eyeLookDist

frustum

  • get frustum(): Frustum3

  • Gets the Camera's 3D World-space viewing frustum.

    Returns Frustum3

    The frustum.

gimbalLock

  • get gimbalLock(): boolean

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

    Returns boolean

    Returns true if gimbal is locked.

  • set gimbalLock(value): void

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

    Parameters

    • value: boolean

    Returns void

    Params

    gimbalLock Set true to lock gimbal.

inverseViewMatrix

  • get inverseViewMatrix(): FloatArrayParam

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

    Returns FloatArrayParam

    The inverse viewing transform matrix.

look

  • get look(): FloatArrayParam

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

    Default value is [0,0,0].

    Returns FloatArrayParam

    Camera look position.

  • set look(look): void

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

    Default value is [0,0,0].

    Parameters

    • look: FloatArrayParam

      Camera look position.

    Returns void

projMatrix

  • get projMatrix(): FloatArrayParam

  • Gets the Camera's projection transformation projMatrix.

    Returns FloatArrayParam

    The projection matrix.

projection

projectionType

  • get projectionType(): number

  • Gets the active projection type.

    Possible values are PerspectiveProjectionType, OrthoProjectionType, "frustum" and "customProjection".

    Default value is PerspectiveProjectionType.

    Returns number

    Identifies the active projection type.

  • set projectionType(value): void

  • Sets the active projection type.

    Accepted values are PerspectiveProjectionType, OrthoProjectionType, "frustum" and "customProjection".

    Default value is PerspectiveProjectionType.

    Parameters

    • value: number

      Identifies the active projection type.

    Returns void

up

viewMatrix

  • get viewMatrix(): FloatArrayParam

  • Gets the Camera's viewing transformation matrix.

    Returns FloatArrayParam

    The viewing transform matrix.

worldAxis

  • get worldAxis(): FloatArrayParam

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

    Returns FloatArrayParam

    The current World coordinate axis.

  • set worldAxis(axis): void

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

    Parameters

    • axis: FloatArrayParam

      The new Wworld coordinate axis.

    Returns void

worldForward

  • get worldForward(): FloatArrayParam

  • Gets the direction of World-space "forwards".

    This is set by Camera.worldAxis.

    Default value is [0,0,1].

    Returns FloatArrayParam

    The "up" vector.

worldRight

  • get worldRight(): FloatArrayParam

  • Gets the direction of World-space "right".

    This is set by Camera.worldAxis.

    Default value is [1,0,0].

    Returns FloatArrayParam

    The "up" vector.

worldUp

  • get worldUp(): FloatArrayParam

  • Gets the direction of World-space "up".

    This is set by Camera.worldAxis.

    Default value is [0,1,0].

    Returns FloatArrayParam

    The "up" vector.

xUp

yUp

zUp

Methods

clean

Protected cleanIfDirty

  • cleanIfDirty(): void

  • Gives this component an opportunity to action any defered state updates.

    Returns void

Protected error

  • error(message): void
  • Protected

    Logs an error for this component to the JavaScript console.

    The console message will have this format: [ERROR] [<component type> =<component id>: <message>

    Parameters

    • message: string

      The error message to log

    Returns void

Protected log

  • log(message): void
  • Protected

    Logs a message for this component.

    The message will have this format: [LOG] [<component type> <component id>: <message>

    Parameters

    • message: string

      The message to log

    Returns void

orbitPitch

orbitYaw

pan

  • pan(pan): void

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

    Parameters

    • pan: FloatArrayParam

      The pan vector

    Returns void

pitch

setDirty

Protected warn

  • warn(message): void
  • Protected

    Logs a warning for this component to the JavaScript console.

    The console message will have this format: [WARN] [<component type> =<component id>: <message>

    Parameters

    • message: string

      The warning message to log

    Returns void

yaw

zoom

Events

onDestroyed

onDestroyed: EventEmitter<Component, null>

Emits an event when the Component has been destroyed.

Readonly onFrustum

onFrustum: EventEmitter<Camera, Frustum3>

Emits an event each time Camera.frustum updates.

myView.camera.onFrustum.subscribe((camera, frustum) => { ... });

Readonly onProjMatrix

onProjMatrix: EventEmitter<Camera, FloatArrayParam>

Emits an event each time Camera.projMatrix updates.

myView.camera.onProjMatrix.subscribe((camera, projMatrix) => { ... });

Readonly onProjectionType

onProjectionType: EventEmitter<Camera, number>

Emits an event each time Camera.projectionType updates.

myView.camera.onProjectionType.subscribe((camera, projType) => { ... });

Readonly onViewMatrix

onViewMatrix: EventEmitter<Camera, FloatArrayParam>

Emits an event each time Camera.viewMatrix updates.

myView.camera.onViewMatrix.subscribe((camera, viewMatrix) => { ... });

Readonly onWorldAxis

onWorldAxis: EventEmitter<Camera, FloatArrayParam>

Emits an event each time Camera.worldAxis updates.

myView.camera.onWorldAxis.subscribe((camera, worldAxis) => { ... });

Settings

Member Visibility

Theme

On This Page

customProjectiondestroyeddirtyfrustumProjectionidorthoProjectionperspectiveProjectionviewconstrainPitchdeviceMatrixeyeeyeLookDistfrustumgimbalLockinverseViewMatrixlookprojMatrixprojectionprojectionTypeupviewMatrixworldAxisworldForwardworldRightworldUpxUpyUpzUpcleancleanIfDirtyerrorlogorbitPitchorbitYawpanpitchsetDirtywarnyawzoomonDestroyedonFrustumonProjMatrixonProjectionTypeonViewMatrixonWorldAxis