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;

ViewerEvents.onCameraViewMatrixUpdated 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

Properties

customProjection frustumProjection orthoProjection perspectiveProjection view

Accessors

constrainPitch deviceMatrix eye eyeLookDist frustum gimbalLock inverseViewMatrix look projection projectionType projMatrix up viewMatrix

Methods

fromParams orbitPitch orbitYaw pan pitch toParams yaw zoom

Properties

ReadonlycustomProjection

customProjection: CustomProjection

The custom projection.

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

ReadonlyfrustumProjection

frustumProjection: FrustumProjection

The frustum projection.

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

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

      Set true to lock gimbal.

    Returns void

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

Methods

fromParams

orbitPitch

orbitYaw

pan

pitch

toParams

yaw

zoom

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