Camera

Manages viewing and projection transforms for its Scene.

• One Camera per Scene
• Scene is located at Viewer#scene and Camera is located at Scene#camera
• Controls viewing and projection transforms
• Has methods to pan, zoom and orbit (or first-person rotation)
• Dynamically configurable World-space axis
• Has Perspective, Ortho and Frustum and CustomProjection, which you can dynamically switch it between
• Switchable gimbal lock
• Can be "flown" to look at targets using a CameraFlightAnimation
• Can be animated along a path using a CameraPathAnimation

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