Class Camera

Controls the viewpoint and projection for a View.

Getting a View's Camera

Let's create a Viewer with a single 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 (View Summary)

Properties

customProjection destroyed dirty frustumProjection id orthoProjection perspectiveProjection view

Accessors

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

Methods

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

Events

onDestroyed onFrustum onProjectionType onProjMatrix onViewMatrix onWorldAxis

Properties

ReadonlycustomProjection

customProjection: CustomProjection

The custom projection.

The Camera uses this while Camera.projectionType equals constants!CustomProjectionType.

destroyed

destroyed: boolean

True once this Component has been destroyed.

Don't use this Component if this is true.

Protecteddirty

dirty: boolean

ReadonlyfrustumProjection

frustumProjection: FrustumProjection

The frustum projection.

The Camera uses this while Camera.projectionType equals constants!FrustumProjectionType.

id

id: string

Unique ID of this Component.

ReadonlyorthoProjection

orthoProjection: OrthoProjection

The orthographic projection.

The Camera uses this while Camera.projectionType equals constants!OrthoProjectionType.

ReadonlyperspectiveProjection

perspectiveProjection: PerspectiveProjection

The perspective projection.

The Camera uses this while Camera.projectionType equals PerspectiveProjectionType.

Readonlyview

view: View

The View to which this Camera belongs.

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: boolean): 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

eye

eyeLookDist

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: boolean): 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

look

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: number): 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

projMatrix

up

viewMatrix

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: FloatArrayParam): 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

    Returns void

worldForward

worldRight

worldUp

xUp

yUp

zUp

Methods

clean

ProtectedcleanIfDirty

Protectederror

  • error(message: string): 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

fromParams

Protectedlog

  • log(message: string): 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

pitch

setDirty

toParams

Protectedwarn

  • warn(message: string): 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.

ReadonlyonFrustum

onFrustum: EventEmitter<Camera, Frustum3>

Emits an event each time Camera.frustum updates.

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

ReadonlyonProjectionType

onProjectionType: EventEmitter<Camera, number>

Emits an event each time Camera.projectionType updates.

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

ReadonlyonProjMatrix

onProjMatrix: EventEmitter<Camera, FloatArrayParam>

Emits an event each time Camera.projMatrix updates.

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

ReadonlyonViewMatrix

onViewMatrix: EventEmitter<Camera, FloatArrayParam>

Emits an event each time Camera.viewMatrix updates.

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

ReadonlyonWorldAxis

onWorldAxis: EventEmitter<Camera, FloatArrayParam>

Emits an event each time Camera.worldAxis updates.

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

Settings

Member Visibility

On This Page

Getting a View's CameraSetting the Camera PositionCamera View and Projection MatricesRotating the CameraPanning the CameraZooming the CameraProjectionConfiguring World up directionGimbal locking
Properties
Accessors
Methods
Events