Cameras

Cameras control how the current scene is viewed. There are three different kinds of cameras:

  • Perspective Camera (perspectiveCamera)
  • Virtual Reality Camera (vrCamera)
  • Augmented Reality Camera (arCamera)

The Perspective Camera (perspectiveCamera) is used to display a scene in a virtual 3D space. Users can move around their virtual objects and zoom in or out the virtual space. A grid view is used.

The Virtual Reality Camera (vrCamera) provides the user with a first person kind of experience (walk view). The scene can be viewed from a first person point of view and the user can move around or walk forward/backward/sideways.

The Augmented Reality Camera (arCamera) activates and shows the device's camera input. This camera is used together with different tracking providers to stabilise the scene in the real world's camera picture.

The Camera Object in the JavaScript API controls and holds all these cameras.

Activating a camera

To activate a camera, simply call the corresponding, asynchronous function. This will also automatically set the camera's internal state to active.

// Activate the Augmented Reality Camera.
const camera = cameras.arCamera;
await camera.activate();

One can easily check if a specific camera is active at the moment.

// Check if Augmented Reality Camera is active.
const camera = cameras.arCamera;
if (camera.active) {
    console.log('Augmented Reality Camera is active.');
} else {
    console.log('Augmented Reality Camera is not active.');
}

Enable/disable stereoscopic rendering

For Head-Mounted Displays (HMD) the current camera can enable stereoscopic rendering. This will render to the display two pictures, horizontally next to each other, instead of one. This can be enabled or disabled for all camera types with an asynchronous method.

const camera = cameras.perspectiveCamera;

// Enable stereoscopic rendering for head-mounted displays.
await camera.enableHmdMode();

// Disable stereoscopic rendering for head-mounted displays.
await camera.disableHmdMode();

Get pose in viewing direction

Sometimes it may be of use to get the pose directly in front of the camera (e.g. to insert a model instance in front of a user, so that it would be immediately visible). An asynchronous method getPoseInViewingDirection , retrieving such a pose, may be used for every camera.

// Retrieve the pose 5 metres in front of the Augmented Reality Camera, projected to the floor.
const camera = cameras.arCamera;
const projectToFloor = true;
const distanceInMM = 5000;

const pose = await camera.getPoseInViewingDirection(distanceInMM, projectToFloor);

Get the current camera pose

The Camera Pose defines the position and orientation of the camera in the 3D space (virtual or real world, respectively). If a user moves around with the device or within the scene, the pose isn't updated automatically. Therefore, an asynchronous method updatePose updates the current pose value. It also immediately returns the current pose.

const camera = camera.vrCamera;

// Retrieve pose from last update (this will NOT return the current camera pose).
const pose = camera.pose;

// Update and get the current camera pose.
const pose = await camera.updatePose();

The pose is defined differently for each camera. Below is a list how each camera's pose is defined:

  • Perspective Camera (perspectiveCamera):
    • position (3d vector) and
    • lookAt (3d vector)
{
    position: {x, y, z},
    lookAt: {x, y, z}
}
  • Virtual Reality Camera (vrCamera):
    • position (3d vector) and
    • orientation (quaternion)
{
    position: {x, y, z},
    orientation: {w, x, y, z}
}
  • Augmented Reality Camera (arCamera):
    • position (3d vector) and
    • orientation (quaternion)
{
    position: {x, y, z},
    orientation: {w, x, y, z}
}

There is also a way to constantly update the pose with a fixed interval. The code snippet below shows how to start and stop a continuous camera pose update:

const camera = cameras.vrCamera;

// Start the continous pose update with updates every 200ms.
const interval = 200;
camera.startPoseUpdate(interval);

// Stop the previously started continous pose update.
camera.stopPoseUpdate();