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

Contents

• Overview
• Examples
• Orbit Mode
  • Following the Pointer in Orbit Mode
  • Showing the Pivot Position
  • Axis-Aligned Views in Orbit Mode
  • View-Fitting Entitys in Orbit Mode
• First-Person Mode
  • Following the Pointer in First-Person Mode
  • Constraining Vertical Position in First-Person Mode
  • Axis-Aligned Views in First-Person Mode
  • View-Fitting Entitys in First-Person Mode
• Plan-View Mode
  • Following the Pointer in Plan-View Mode
  • Axis-Aligned Views in Plan-View Mode
• CameraControl Events
  • "hover"
  • "hoverOff"
  • "hoverEnter"
  • "hoverOut"
  • "picked"
  • "pickedSurface"
  • "pickedNothing"
  • "doublePicked"
  • "doublePickedSurface"
  • "doublePickedNothing"
  • "rightClick"
• Custom Keyboard Mappings

Overview

• Each Viewer has a CameraControl, located at Viewer#cameraControl.
• CameraControl#navMode selects the navigation mode:
  • "orbit" rotates the Camera position about the target.
  • "firstPerson" rotates the World about the Camera position.
  • "planView" never rotates, but still allows to pan and dolly, typically for an axis-aligned view.
• CameraControl#followPointer makes the Camera follow the mouse or touch pointer.
• CameraControl#constrainVertical locks the Camera to its current height when in first-person mode.
• CameraControl fires pick events when we hover, click or tap on an Entity.
  
  

Examples

• Orbit Navigation - Duplex Model
• Orbit Navigation - Holter Tower Model
• First-Person Navigation - Duplex Model
• First-Person Navigation - Holter Tower Model
• Plan-view Navigation - Schependomlaan Model
• Custom Keyboard Mapping
  
  

Orbit Mode

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

To enable orbit mode:

const cameraControl = myViewer.cameraControl;
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;

Smart Pivoting

TODO

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; // Default

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"

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

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

"rightClick"

Event fired when we right-click on the canvas.

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

Custom Keyboard Mappings

We can customizeCameraControl key bindings as shown below.

In this example, we'll just set the default bindings for a QWERTY keyboard.

const input = myViewer.scene.input;

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

const keyMap = {};

keyMap[cameraControl.PAN_LEFT] = [input.KEY_A];
keyMap[cameraControl.PAN_RIGHT] = [input.KEY_D];
keyMap[cameraControl.PAN_UP] = [input.KEY_Z];
keyMap[cameraControl.PAN_DOWN] = [input.KEY_X];
keyMap[cameraControl.DOLLY_FORWARDS] = [input.KEY_W, input.KEY_ADD];
keyMap[cameraControl.DOLLY_BACKWARDS] = [input.KEY_S, input.KEY_SUBTRACT];
keyMap[cameraControl.ROTATE_X_POS] = [input.KEY_DOWN_ARROW];
keyMap[cameraControl.ROTATE_X_NEG] = [input.KEY_UP_ARROW];
keyMap[cameraControl.ROTATE_Y_POS] = [input.KEY_LEFT_ARROW];
keyMap[cameraControl.ROTATE_Y_NEG] = [input.KEY_RIGHT_ARROW];
keyMap[cameraControl.AXIS_VIEW_RIGHT] = [input.KEY_NUM_1];
keyMap[cameraControl.AXIS_VIEW_BACK] = [input.KEY_NUM_2];
keyMap[cameraControl.AXIS_VIEW_LEFT] = [input.KEY_NUM_3];
keyMap[cameraControl.AXIS_VIEW_FRONT] = [input.KEY_NUM_4];
keyMap[cameraControl.AXIS_VIEW_TOP] = [input.KEY_NUM_5];
keyMap[cameraControl.AXIS_VIEW_BOTTOM] = [input.KEY_NUM_6];

cameraControl.keyMap = keyMap;

We can also just configure default bindings for a specified keyboard layout, like this:

cameraControl.keyMap = "qwerty";

Then, CameraControl will internally set CameraControl#keyMap to the default key map for the QWERTY layout (which is the same set of mappings we set in the previous example). In other words, if we subsequently read CameraControl#keyMap, it will now be a key map, instead of the "qwerty" string value we set it to.

Supported layouts are, so far:

• "qwerty"
• "azerty"