Reference Source
public class | source

CameraControl

Extends:

Component → CameraControl

Controls the Camera with user input, and fires events when the user interacts with pickable Entitys.

Contents

Overview

Examples

Orbit Mode

In orbit mode, CameraControl orbits the Camera about the target.

To enable orbit mode:

cameraControl.navMode = "orbit";

Then orbit by:

  • left-dragging the mouse,
  • tap-dragging the touch pad, and
  • pressing arrow keys, or Q and E on a QWERTY keyboard, or A and E on an AZERTY keyboard.

Dolly forwards and backwards by:

  • spinning the mouse wheel,
  • pinching on the touch pad, and
  • pressing the + and - keys, or W and S on a QWERTY keyboard, or Z and S for AZERTY.

Pan horizontally and vertically by:

  • right-dragging the mouse,
  • left-dragging the mouse with the SHIFT key down,
  • tap-dragging the touch pad with SHIFT down,
  • pressing the A, D, Z and X keys on a QWERTY keyboard, and
  • pressing the Q, D, W and X keys on an AZERTY keyboard,

Following the Pointer in Orbit Mode

When CameraControl#followPointer is truein orbiting mode, the mouse or touch pointer will dynamically indicate the target that the Camera will orbit, as well as dolly to and from.

Lets ensure that we're in orbit mode, then enable the Camera to follow the pointer:

cameraControl.navMode = "orbit";
cameraControl.followPointer = true;

When the pointer is over empty space, the target will remain on the last object that the pointer was over.

Showing the Pivot Position

We can configure CameraControl#pivotElement with an HTML element to indicate the current pivot position. The indicator will appear momentarily each time we move the Camera while in orbit mode with CameraControl#followPointer set true.

First we'll define some CSS to style our pivot indicator as a black dot with a white border:

.camera-pivot-marker {
     color: #ffffff;
     position: absolute;
     width: 25px;
     height: 25px;
     border-radius: 15px;
     border: 2px solid #ebebeb;
     background: black;
     visibility: hidden;
     box-shadow: 5px 5px 15px 1px #000000;
     z-index: 10000;
     pointer-events: none;
}

Then we'll attach our pivot indicator's HTML element to the CameraControl:

const pivotElement = document.createRange().createContextualFragment("<div class='camera-pivot-marker'></div>").firstChild;

document.body.appendChild(pivotElement);

cameraControl.pivotElement = pivotElement;

Axis-Aligned Views in Orbit Mode

In orbit mode, we can use keys 1-6 to position the Camera to look at the center of the Scene from along each of the six World-space axis. Pressing one of these keys will fly the Camera to the corresponding axis-aligned view.

View-Fitting Entitys in Orbit Mode

When CameraControl#doublePickFlyTo is true, we can left-double-click or double-tap (ie. "double-pick") an Entity to fit it to view. This will cause the Camera to fly to that Entity. Our target then becomes the center of that Entity. If we are currently pivoting, then our pivot position is then also set to the Entity center.

Disable that behaviour by setting CameraControl#doublePickFlyTo false.

First-Person Mode

In first-person mode, CameraControl rotates the World about the Camera position.

To enable first-person mode:

cameraControl.navMode = "firstPerson";

Then rotate by:

  • left-dragging the mouse,
  • tap-dragging the touch pad,
  • pressing arrow keys, or Q and E on a QWERTY keyboard, or A and E on an AZERTY keyboard.

Dolly forwards and backwards by:

  • spinning the mouse wheel,
  • pinching on the touch pad, and
  • pressing the + and - keys, or W and S on a QWERTY keyboard, or Z and S for AZERTY.

Pan left, right, up and down by:

  • left-dragging or right-dragging the mouse, and
  • tap-dragging the touch pad with SHIFT down.

Pan forwards, backwards, left, right, up and down by pressing the WSADZX keys on a QWERTY keyboard, or WSQDWX keys on an AZERTY keyboard.

Following the Pointer in First-Person Mode

When CameraControl#followPointer is true in first-person mode, the mouse or touch pointer will dynamically indicate the target to which the Camera will dolly to and from. In first-person mode, however, the World will always rotate about the Camera position.

Lets ensure that we're in first-person mode, then enable the Camera to follow the pointer:

cameraControl.navMode = "firstPerson";
cameraControl.followPointer = true;

When the pointer is over empty space, the target will remain the last object that the pointer was over.

Constraining Vertical Position in First-Person Mode

In first-person mode, we can lock the Camera to its current position on the vertical World axis, which is useful for walk-through navigation:

cameraControl.constrainVertical = true;

Axis-Aligned Views in First-Person Mode

In first-person mode we can use keys 1-6 to position the Camera to look at the center of the Scene from along each of the six World-space axis. Pressing one of these keys will fly the Camera to the corresponding axis-aligned view.

View-Fitting Entitys in First-Person Mode

As in orbit mode, when in first-person mode and CameraControl#doublePickFlyTo is true, we can double-click or double-tap an Entity (ie. "double-picking") to fit it in view. This will cause the Camera to fly to that Entity. Our target then becomes the center of that Entity.

Disable that behaviour by setting CameraControl#doublePickFlyTo false.

Plan-View Mode

In plan-view mode, CameraControl pans and rotates the Camera, without rotating it.

To enable plan-view mode:

cameraControl.navMode = "planView";

Dolly forwards and backwards by:

  • spinning the mouse wheel,
  • pinching on the touch pad, and
  • pressing the + and - keys.


Pan left, right, up and down by:

  • left-dragging or right-dragging the mouse, and
  • tap-dragging the touch pad with SHIFT down.

Pan forwards, backwards, left, right, up and down by pressing the WSADZX keys on a QWERTY keyboard, or WSQDWX keys on an AZERTY keyboard.

Following the Pointer in Plan-View Mode

When CameraControl#followPointer is true in plan-view mode, the mouse or touch pointer will dynamically indicate the target to which the Camera will dolly to and from. In plan-view mode, however, the Camera cannot rotate.

Lets ensure that we're in plan-view mode, then enable the Camera to follow the pointer:

cameraControl.navMode = "planView";
cameraControl.followPointer = true;

When the pointer is over empty space, the target will remain the last object that the pointer was over.

Axis-Aligned Views in Plan-View Mode

As in orbit and first-person modes, in plan-view mode we can use keys 1-6 to position the Camera to look at the center of the Scene from along each of the six World-space axis. Pressing one of these keys will fly the Camera to the corresponding axis-aligned view.

CameraControl Events

CameraControl fires events as we interact with Entitys using mouse or touch input.

The following examples demonstrate how to subscribe to those events.

The first example shows how to save a handle to a subscription, which we can later use to unsubscribe.

"hover"

Event fired when the pointer moves while hovering over an Entity.

const onHover = cameraControl.on("hover", (e) => {
     const entity = e.entity; // Entity
     const canvasPos = e.canvasPos; // 2D canvas position
});

To unsubscribe from the event:

cameraControl.off(onHover);

"hoverOff"

Event fired when the pointer moves while hovering over empty space.

cameraControl.on("hoverOff", (e) => {
     const canvasPos = e.canvasPos;
});

"hoverEnter"

Event fired when the pointer moves onto an Entity.

cameraControl.on("hoverEnter", (e) => {
     const entity = e.entity;
     const canvasPos = e.canvasPos;
});

"hoverOut"

Event fired when the pointer moves off an Entity.

cameraControl.on("hoverOut", (e) => {
     const entity = e.entity;
     const canvasPos = e.canvasPos;
});

"picked"

Event fired when we left-click or tap on an Entity.

cameraControl.on("picked", (e) => {
     const entity = e.entity;
     const canvasPos = e.canvasPos;
});

"pickedSurface"

Event fired when we left-click or tap on the surface of an Entity.

cameraControl.on("picked", (e) => {
     const entity = e.entity;
     const canvasPos = e.canvasPos;
     const worldPos = e.worldPos; // 3D World-space position
     const viewPos = e.viewPos; // 3D View-space position
     const worldNormal = e.worldNormal; // 3D World-space normal vector
});

"pickedNothing"

Event fired when we left-click or tap on empty space.

cameraControl.on("pickedNothing", (e) => {
     const canvasPos = e.canvasPos;
});

"doublePicked"

Event fired wwhen we left-double-click or double-tap on an Entity.

cameraControl.on("doublePicked", (e) => {
     const entity = e.entity;
     const canvasPos = e.canvasPos;
});

"doublePickedSurface"

Event fired when we left-double-click or double-tap on the surface of an Entity.

cameraControl.on("doublePickedSurface", (e) => {
     const entity = e.entity;
     const canvasPos = e.canvasPos;
     const worldPos = e.worldPos;
     const viewPos = e.viewPos;
     const worldNormal = e.worldNormal;
});

"doublePickedNothing"

Wvent fired when we left-double-click or double-tap on empty space.

cameraControl.on("doublePickedNothing", (e) => {
     const canvasPos = e.canvasPos;
});

"mouseRightClick"

Event fired when we right-click on the canvas.

cameraControl.on("rightClicked", (e) => {
     const event = e.event; // Mouse event
     const canvasPos = e.canvasPos;
});

Member Summary

Public Members
public set

active(value: Boolean)

Sets if this CameraControl is active or not.

public get

Gets if this CameraControl is active or not.

public set

Sets whether to vertically constrain the Camera position for first-person navigation.

public get

Gets whether to vertically constrain the Camera position for first-person navigation.

public set

dollyInertia(dollyInertia: Number)

Sets the dolly inertia factor.

public get

Gets the dolly inertia factor.

public set
this set was deprecated.
public get
this get was deprecated.
public set

Sets whether double-picking an Entity causes the Camera to fly to its boundary.

public get

Gets whether double-picking an Entity causes the Camera to fly to its boundary.

public set

dragRotationRate(dragRotationRate: Number)

Sets the current drag rotation rate.

public get

Gets the current drag rotation rate.

public set
this set was deprecated.

Sets whether this CameraControl is in first-person mode.

public get
this get was deprecated.

Gets whether this CameraControl is in first-person mode.

public set

Sets whether the Camera follows the mouse or touch pointer.

public get

Sets whether the Camera follows the mouse or touch pointer.

public set

keyboardDollyRate(keyboardDollyRate: Number)

Sets how much the Camera dollys each second with keyboard input.

public get

Gets how much the Camera dollys each second with keyboard input.

public set

Sets the keyboard layout.

public get

Gets the keyboard layout.

public set

keyboardPanRate(keyboardPanRate: Number)

Sets how much the Camera pans each second with keyboard input.

public get

Gets how much the Camera pans each second with keyboard input.

public set

keyboardRotationRate(keyboardRotationRate: Number)

Sets how many degrees per second the Camera rotates/orbits with keyboard input.

public get

Sets how many degrees per second the Camera rotates/orbits with keyboard input.

public set

mouseWheelDollyRate(mouseWheelDollyRate: Number)

Sets how much the Camera dollys each second while the mouse wheel is spinning.

public get

Gets how much the Camera dollys each second while the mouse wheel is spinning.

public set

navMode(navMode: String)

Sets the current navigation mode.

public get

Gets the current navigation mode.

public set

panInertia(panInertia: Number)

Sets the pan inertia factor.

public get

Gets the pan inertia factor.

public set

Sets whether either right-clicking (true) or middle-clicking (false) pans the Camera.

public get

Gets whether right-clicking pans the Camera.

public set
this set was deprecated.
public get
this get was deprecated.
public set

pivotElement(element: HTMLElement)

Sets the HTMl element to represent the pivot point when CameraControl#followPointer is true.

public set

pivotPos(worldPos: Number[])

Sets the current World-space 3D target position.

public get

Gets the current World-space 3D pivot position.

public set

planView(value: Boolean)

this set was deprecated.

Sets whether this CameraControl is in plan-view mode.

public get
this get was deprecated.

Gets whether this CameraControl is in plan-view mode.

public set

Sets whether mouse and touch input is enabled.

public get

Gets whether mouse and touch input is enabled.

public set

rotationInertia(rotationInertia: Number)

Sets a factor in range [0..1] indicating how much the Camera keeps moving after you finish rotating it.

public get

Gets the rotation inertia factor.

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

warn(message: String)

Logs a warning for this component to the JavaScript console.

Public Members

public set active(value: Boolean) source

Sets if this CameraControl is active or not.

When inactive, the CameraControl will not react to input.

Default is true.

public get active: Boolean: * source

Gets if this CameraControl is active or not.

When inactive, the CameraControl will not react to input.

Default is true.

Return:

Boolean

Returns true if this CameraControl is active.

public set constrainVertical(value: Boolean) source

Sets whether to vertically constrain the Camera position for first-person navigation.

When set true, this constrains Camera#eye to its current vertical position.

Only applies when CameraControl#navMode is "firstPerson".

Default is false.

public get constrainVertical: Boolean: * source

Gets whether to vertically constrain the Camera position for first-person navigation.

When set true, this constrains Camera#eye to its current vertical position.

Only applies when CameraControl#navMode is "firstPerson".

Default is false.

Return:

Boolean

true when Camera is vertically constrained.

public set dollyInertia(dollyInertia: Number) source

Sets the dolly inertia factor.

This factor configures how much the Camera keeps moving after you finish dollying it.

This factor is a value in range [0..1]. A value of 0.0 causes dollying to immediately stop, 0.5 causes dollying to decay 50% on each animation frame, while 1.0 causes no decay, which allows dollying to continue until further input stops it.

You might set dollyInertia to zero when you want be able to precisely position or rotate the Camera, without interference from inertia. This also means that xeokit renders less frames while dollying the Camera, which can improve rendering performance.

Default is 0.75.

public get dollyInertia: Number: * source

Gets the dolly inertia factor.

Default is 0.75.

Return:

Number

The current dolly inertia factor.

public set dollyToPointer(value: Boolean) source

this set was deprecated.

public get dollyToPointer: Boolean: * source

this get was deprecated.

Return:

Boolean

Returns true if dolly-to-pointer behaviour is enabled.

public set doublePickFlyTo(value: Boolean) source

Sets whether double-picking an Entity causes the Camera to fly to its boundary.

Default is false.

public get doublePickFlyTo: Boolean: * source

Gets whether double-picking an Entity causes the Camera to fly to its boundary.

Default is false.

Return:

Boolean

Returns true when double-pick-fly-to mode is enabled.

public set dragRotationRate(dragRotationRate: Number) source

Sets the current drag rotation rate.

This configures how many degrees the Camera rotates/orbits for a full sweep of the canvas by mouse or touch dragging.

For example, a value of 360.0 indicates that the Camera rotates/orbits 360.0 degrees horizontally when we sweep the entire width of the canvas.

CameraControl makes vertical rotation half as sensitive as horizontal rotation, so that we don't tend to flip upside-down. Therefore, a value of 360.0 rotates/orbits the Camera through 180.0 degrees vertically when we sweep the entire height of the canvas.

Default is 360.0.

public get dragRotationRate: Number: * source

Gets the current drag rotation rate.

Default is 360.0.

Return:

Number

The current drag rotation rate.

public set firstPerson(value: Boolean) source

this set was deprecated.

Sets whether this CameraControl is in first-person mode.

In "first person" mode (disabled by default) the look position rotates about the eye position. Otherwise, Camera#eye rotates about Camera#look.

Default is false.

Deprecated - use CameraControl#navMode instead.

public get firstPerson: Boolean: * source

this get was deprecated.

Gets whether this CameraControl is in first-person mode.

In "first person" mode (disabled by default) the look position rotates about the eye position. Otherwise, Camera#eye rotates about Camera#look.

Default is false.

Deprecated - use CameraControl#navMode instead.

Return:

Boolean

Returns true if first-person mode is enabled.

public set followPointer(value: Boolean) source

Sets whether the Camera follows the mouse or touch pointer.

In orbiting mode, the Camera will orbit about the pointer, and will dolly to and from the pointer.

In fly-to mode, the Camera will dolly to and from the pointer, however the World will always rotate about the Camera position.

In plan-view mode, the Camera will dolly to and from the pointer, however the Camera will not rotate.

Default is false.

See class comments for more info.

public get followPointer: Boolean: * source

Sets whether the Camera follows the mouse or touch pointer.

In orbiting mode, the Camera will orbit about the pointer, and will dolly to and from the pointer.

In fly-to mode, the Camera will dolly to and from the pointer, however the World will always rotate about the Camera position.

In plan-view mode, the Camera will dolly to and from the pointer, however the Camera will not rotate.

Default is false.

See class comments for more info.

Return:

Boolean

Returns true if the Camera follows the pointer.

public set keyboardDollyRate(keyboardDollyRate: Number) source

Sets how much the Camera dollys each second with keyboard input.

Default is 15.0, to dolly the Camera 15.0 World-space units per second while we hold down the + and - keys.

public get keyboardDollyRate: Number: * source

Gets how much the Camera dollys each second with keyboard input.

Default is 15.0.

Return:

Number

The current keyboard dolly rate.

public set keyboardLayout(value: String) source

Sets the keyboard layout.

Supported layouts are:

  • "qwerty" (default)
  • "azerty"

public get keyboardLayout: String: * source

Gets the keyboard layout.

Supported layouts are:

  • "qwerty" (default)
  • "azerty"

Return:

String

The current keyboard layout.

public set keyboardPanRate(keyboardPanRate: Number) source

Sets how much the Camera pans each second with keyboard input.

Default is 5.0, to pan the Camera 5.0 World-space units every second that a panning key is depressed. See the CameraControl class documentation for which keys control panning.

Panning direction is aligned to our Camera's orientation. When we pan horizontally, we pan to our left and right, when we pan vertically, we pan upwards and downwards, and when we pan forwards and backwards, we pan along the direction the Camera is pointing.

Unlike dollying when followPointer is true, panning does not follow the pointer.

public get keyboardPanRate: Number: * source

Gets how much the Camera pans each second with keyboard input.

Default is 5.0.

Return:

Number

The current keyboard pan rate.

public set keyboardRotationRate(keyboardRotationRate: Number) source

Sets how many degrees per second the Camera rotates/orbits with keyboard input.

Default is 90.0, to rotate/orbit the Camera 90.0 degrees every second that a rotation key is depressed. See the CameraControl class documentation for which keys control rotation/orbit.

public get keyboardRotationRate: Number: * source

Sets how many degrees per second the Camera rotates/orbits with keyboard input.

Default is 90.0.

Return:

Number

The current keyboard rotation rate.

public set mouseWheelDollyRate(mouseWheelDollyRate: Number) source

Sets how much the Camera dollys each second while the mouse wheel is spinning.

Default is 15.0, to dolly the Camera 15.0 World-space units per second as we spin the mouse wheel.

public get mouseWheelDollyRate: Number: * source

Gets how much the Camera dollys each second while the mouse wheel is spinning.

Default is 15.0.

Return:

Number

The current mouseWheel dolly rate.

public set navMode(navMode: String) source

Sets the current navigation mode.

Accepted values are:

  • "orbit" - rotation orbits about the current target or pivot point,
  • "firstPerson" - rotation is about the current eye position,
  • "planView" - rotation is disabled.

See class comments for more info.

public get navMode: String: * source

Gets the current navigation mode.

Return:

String

The navigation mode: "orbit", "firstPerson" or "planView".

public set panInertia(panInertia: Number) source

Sets the pan inertia factor.

This factor configures how much the Camera keeps moving after you finish panning it.

This factor is a value in range [0..1]. A value of 0.0 causes panning to immediately stop, 0.5 causes panning to decay 50% on each animation frame, while 1.0 causes no decay, which allows panning to continue until further input stops it.

You might set panInertia to zero when you want be able to precisely position or rotate the Camera, without interference from inertia. This also means that xeokit renders less frames while panning the Camera, wich can improve rendering performance.

Default is 0.5.

public get panInertia: Number: * source

Gets the pan inertia factor.

Default is 0.5.

Return:

Number

The current pan inertia factor.

public set panRightClick(value: Boolean) source

Sets whether either right-clicking (true) or middle-clicking (false) pans the Camera.

Default is true.

public get panRightClick: Boolean: * source

Gets whether right-clicking pans the Camera.

Default is true.

Return:

Boolean

Returns false when pan on right-click is disabled.

public set panToPointer(value: Boolean) source

this set was deprecated.

public get panToPointer: Boolean: boolean source

this get was deprecated.

Return:

Boolean

Returns true if dolly-to-pointer behaviour is enabled.

public set pivotElement(element: HTMLElement) source

Sets the HTMl element to represent the pivot point when CameraControl#followPointer is true.

See class comments for an example.

public set pivotPos(worldPos: Number[]) source

Sets the current World-space 3D target position.

Only applies when CameraControl#followPointer is true.

public get pivotPos: Number[]: * source

Gets the current World-space 3D pivot position.

Only applies when CameraControl#followPointer is true.

Return:

Number[]

worldPos The current World-space 3D pivot position.

public set planView(value: Boolean) source

this set was deprecated.

Sets whether this CameraControl is in plan-view mode.

When in plan-view mode, rotation is disabled.

Default is false.

Deprecated - use CameraControl#navMode instead.

public get planView: Boolean: * source

this get was deprecated.

Gets whether this CameraControl is in plan-view mode.

When in plan-view mode, rotation is disabled.

Default is false.

Deprecated - use CameraControl#navMode instead.

Return:

Boolean

Returns true if plan-view mode is enabled.

public set pointerEnabled(value: Boolean) source

Sets whether mouse and touch input is enabled.

Default is true.

Disabling mouse and touch input on CameraControl is useful when we want to temporarily use mouse or touch input to interact with some other 3D control, without disturbing the Camera.

public get pointerEnabled: Boolean: * source

Gets whether mouse and touch input is enabled.

Default is true.

Disabling mouse and touch input on CameraControl is desirable when we want to temporarily use mouse or touch input to interact with some other 3D control, without interfering with the Camera.

Return:

Boolean

Returns true if mouse and touch input is enabled.

public set rotationInertia(rotationInertia: Number) source

Sets a factor in range [0..1] indicating how much the Camera keeps moving after you finish rotating it.

A value of 0.0 causes it to immediately stop, 0.5 causes its movement to decay 50% on each tick, while 1.0 causes no decay, allowing it continue moving, by the current rate of rotation.

You may choose an inertia of zero when you want be able to precisely rotate the Camera, without interference from inertia. Zero inertia can also mean that less frames are rendered while you are rotating the Camera.

Default is 0.5.

Does not apply when CameraControl#navMode is "planView", which disallows rotation.

public get rotationInertia: Number: * source

Gets the rotation inertia factor.

Default is 0.5.

Does not apply when CameraControl#navMode is "planView", which disallows rotation.

Return:

Number

The inertia factor.