Camera

new Camera(scene)

The camera is defined by a position, orientation, and view frustum.

The orientation forms an orthonormal basis with a view, up and right = view x up unit vectors.

The viewing frustum is defined by 6 planes. Each plane is represented by a Cartesian4 object, where the x, y, and z components define the unit vector normal to the plane, and the w component is the distance of the plane from the origin/camera position.
Name Type Description
scene Scene The scene.
Example:
// Create a camera looking down the negative z-axis, positioned at the origin,
// with a field of view of 60 degrees, and 1:1 aspect ratio.
var camera = new Cesium.Camera(scene);
camera.position = new Cesium.Cartesian3();
camera.direction = Cesium.Cartesian3.negate(Cesium.Cartesian3.UNIT_Z, new Cesium.Cartesian3());
camera.up = Cesium.Cartesian3.clone(Cesium.Cartesian3.UNIT_Y);
camera.frustum.fov = Cesium.Math.PI_OVER_THREE;
camera.frustum.near = 1.0;
camera.frustum.far = 2.0;
Demo:
Source: Scene/Camera.js, line 86

Members

staticCamera.DEFAULT_VIEW_FACTOR :Number

A scalar to multiply to the camera position and add it back after setting the camera to view the rectangle. A value of zero means the camera will view the entire Camera#DEFAULT_VIEW_RECTANGLE, a value greater than zero will move it further away from the extent, and a value less than zero will move it close to the extent.
Source: Scene/Camera.js, line 249

staticCamera.DEFAULT_VIEW_RECTANGLE :Rectangle

The default extent the camera will view on creation.
Source: Scene/Camera.js, line 241

constrainedAxis :Cartesian3

If set, the camera will not be able to rotate past this axis in either direction.
Default Value: undefined
Source: Scene/Camera.js, line 184

defaultLookAmount :Number

The default amount to rotate the camera when an argument is not provided to the look methods.
Default Value: Math.PI / 60.0
Source: Scene/Camera.js, line 164

defaultMoveAmount :Number

The default amount to move the camera when an argument is not provided to the move methods.
Default Value: 100000.0;
Source: Scene/Camera.js, line 157

defaultRotateAmount :Number

The default amount to rotate the camera when an argument is not provided to the rotate methods.
Default Value: Math.PI / 3600.0
Source: Scene/Camera.js, line 171

defaultZoomAmount :Number

The default amount to move the camera when an argument is not provided to the zoom methods.
Default Value: 100000.0;
Source: Scene/Camera.js, line 178

direction :Cartesian3

The view direction of the camera.
Source: Scene/Camera.js, line 115

readonlydirectionWC :Cartesian3

Gets the view direction of the camera in world coordinates.
Source: Scene/Camera.js, line 652

frustum :Frustum

The region of space in view.
Default Value: PerspectiveFrustum()
See:
Source: Scene/Camera.js, line 147

readonlyheading :Number

Gets the camera heading in radians.
Source: Scene/Camera.js, line 694

readonlyinverseTransform :Matrix4

Gets the inverse camera transform.
Default Value: Matrix4.IDENTITY
Source: Scene/Camera.js, line 576

readonlyinverseViewMatrix :Matrix4

Gets the inverse view matrix.
See:
Source: Scene/Camera.js, line 608

maximumTranslateFactor :Number

The factor multiplied by the the map size used to determine where to clamp the camera position when translating across the surface. The default is 1.5. Only valid for 2D and Columbus view.
Default Value: 1.5
Source: Scene/Camera.js, line 191

maximumZoomFactor :Number

The factor multiplied by the the map size used to determine where to clamp the camera position when zooming out from the surface. The default is 2.5. Only valid for 2D.
Default Value: 2.5
Source: Scene/Camera.js, line 198

readonlymoveEnd :Event

Gets the event that will be raised at when the camera has stopped moving.
Source: Scene/Camera.js, line 789

readonlymoveStart :Event

Gets the event that will be raised at when the camera starts to move.
Source: Scene/Camera.js, line 777

readonlypitch :Number

Gets the camera pitch in radians.
Source: Scene/Camera.js, line 722

position :Cartesian3

The position of the camera.
Source: Scene/Camera.js, line 105

positionCartographic :Cartographic

Gets the Cartographic position of the camera, with longitude and latitude expressed in radians and height in meters. In 2D and Columbus View, it is possible for the returned longitude and latitude to be outside the range of valid longitudes and latitudes when the camera is outside the map.
Source: Scene/Camera.js, line 624

readonlypositionWC :Cartesian3

Gets the position of the camera in world coordinates.
Source: Scene/Camera.js, line 638
The right direction of the camera.
Source: Scene/Camera.js, line 133

readonlyrightWC :Cartesian3

Gets the right direction of the camera in world coordinates.
Source: Scene/Camera.js, line 680

readonlyroll :Number

Gets the camera roll in radians.
Source: Scene/Camera.js, line 750

readonlytransform :Matrix4

Gets the camera's reference frame. The inverse of this transformation is appended to the view matrix.
Default Value: Matrix4.IDENTITY
Source: Scene/Camera.js, line 561

up :Cartesian3

The up direction of the camera.
Source: Scene/Camera.js, line 124

readonlyupWC :Cartesian3

Gets the up direction of the camera in world coordinates.
Source: Scene/Camera.js, line 666

readonlyviewMatrix :Matrix4

Gets the view matrix.
See:
Source: Scene/Camera.js, line 592

Methods

cameraToWorldCoordinates(cartesian, result) → Cartesian4

Transform a vector or point from the camera's reference frame to world coordinates.
Name Type Description
cartesian Cartesian4 The vector or point to transform.
result Cartesian4 optional The object onto which to store the result.
Returns:
The transformed vector or point.
Source: Scene/Camera.js, line 1167

cameraToWorldCoordinatesPoint(cartesian, result) → Cartesian3

Transform a point from the camera's reference frame to world coordinates.
Name Type Description
cartesian Cartesian3 The point to transform.
result Cartesian3 optional The object onto which to store the result.
Returns:
The transformed point.
Source: Scene/Camera.js, line 1188

cameraToWorldCoordinatesVector(cartesian, result) → Cartesian3

Transform a vector from the camera's reference frame to world coordinates.
Name Type Description
cartesian Cartesian3 The vector to transform.
result Cartesian3 optional The object onto which to store the result.
Returns:
The transformed vector.
Source: Scene/Camera.js, line 1209

flyTo(options)

Flies the camera from its current position to a new position.
Name Type Description
options Object Object with the following properties:
Name Type Default Description
destination Cartesian3 | Rectangle The final position of the camera in WGS84 (world) coordinates or a rectangle that would be visible from a top-down view.
orientation Object optional An object that contains either direction and up properties or heading, pith and roll properties. By default, the direction will point towards the center of the frame in 3D and in the negative z direction in Columbus view or 2D. The up direction will point towards local north in 3D and in the positive y direction in Columbus view or 2D.
duration Number optional The duration of the flight in seconds. If ommitted, Cesium attempts to calculate an ideal duration based on the distance to be traveled by the flight.
complete Camera~FlightCompleteCallback optional The function to execute when the flight is complete.
cancel Camera~FlightCancelledCallback optional The function to execute if the flight is cancelled.
endTransform Matrix4 optional Transform matrix representing the reference frame the camera will be in when the flight is completed.
convert Boolean true optional When true, the destination is converted to the correct coordinate system for each scene mode. When false, the destination is expected to be in the correct coordinate system.
maximumHeight Number optional The maximum height at the peak of the flight.
easingFunction EasingFunction | EasingFunction~Callback optional Controls how the time is interpolated over the duration of the flight.
Throws:
  • DeveloperError : If either direction or up is given, then both are required.
Example:
// 1. Fly to a position with a top-down view
viewer.camera.flyTo({
    destination : Cesium.Cartesian3.fromDegrees(-117.16, 32.71, 15000.0)
});

// 2. Fly to a Rectangle with a top-down view
viewer.camera.flyTo({
    destination : Cesium.Rectangle.fromDegrees(west, south, east, north)
});

// 3. Fly to a position with an orientation using unit vectors.
viewer.camera.flyTo({
    destination : Cesium.Cartesian3.fromDegrees(-122.19, 46.25, 5000.0),
    orientation : {
        direction : new Cesium.Cartesian3(-0.04231243104240401, -0.20123236049443421, -0.97862924300734),
        up : new Cesium.Cartesian3(-0.47934589305293746, -0.8553216253114552, 0.1966022179118339)
    }
});

// 4. Fly to a position with an orientation using heading, pitch and roll.
viewer.camera.flyTo({
    destination : Cesium.Cartesian3.fromDegrees(-122.19, 46.25, 5000.0),
    orientation : {
        heading : Cesium.Math.toRadians(175.0),
        pitch : Cesium.Math.toRadians(-35.0),
        roll : 0.0
    }
});
Source: Scene/Camera.js, line 2480

flyToBoundingSphere(boundingSphere, options)

Flies the camera to a location where the current view contains the provided bounding sphere.

The offset is heading/pitch/range in the local east-north-up reference frame centered at the center of the bounding sphere. The heading and the pitch angles are defined in the local east-north-up reference frame. The heading is the angle from y axis and increasing towards the x axis. Pitch is the rotation from the xy-plane. Positive pitch angles are above the plane. Negative pitch angles are below the plane. The range is the distance from the center. If the range is zero, a range will be computed such that the whole bounding sphere is visible.

In 2D and Columbus View, there must be a top down view. The camera will be placed above the target looking down. The height above the target will be the range. The heading will be aligned to local north.

Name Type Description
boundingSphere BoundingSphere The bounding sphere to view, in world coordinates.
options Object optional Object with the following properties:
Name Type Description
duration Number optional The duration of the flight in seconds. If ommitted, Cesium attempts to calculate an ideal duration based on the distance to be traveled by the flight.
offset HeadingPitchRange optional The offset from the target in the local east-north-up reference frame centered at the target.
complete Camera~FlightCompleteCallback optional The function to execute when the flight is complete.
cancel Camera~FlightCancelledCallback optional The function to execute if the flight is cancelled.
endTransform Matrix4 optional Transform matrix representing the reference frame the camera will be in when the flight is completed.
maximumHeight Number optional The maximum height at the peak of the flight.
easingFunction EasingFunction | EasingFunction~Callback optional Controls how the time is interpolated over the duration of the flight.
Source: Scene/Camera.js, line 2643

getMagnitude() → Number

Gets the magnitude of the camera position. In 3D, this is the vector magnitude. In 2D and Columbus view, this is the distance to the map.
Returns:
The magnitude of the position.
Source: Scene/Camera.js, line 1655

getPickRay(windowPosition, result) → Ray

Create a ray from the camera position through the pixel at windowPosition in world coordinates.
Name Type Description
windowPosition Cartesian2 The x and y coordinates of a pixel.
result Ray optional The object onto which to store the result.
Returns:
Returns the Cartesian3 position and direction of the ray.
Source: Scene/Camera.js, line 2237

getRectangleCameraCoordinates(rectangle, result) → Cartesian3

Get the camera position needed to view an rectangle on an ellipsoid or map
Name Type Description
rectangle Rectangle The rectangle to view.
result Cartesian3 optional The camera position needed to view the rectangle
Returns:
The camera position needed to view the rectangle
Source: Scene/Camera.js, line 2051

look(axis, angle)

Rotate each of the camera's orientation vectors around axis by angle
Name Type Description
axis Cartesian3 The axis to rotate around.
angle Number optional The angle, in radians, to rotate by. Defaults to defaultLookAmount.
See:
Source: Scene/Camera.js, line 1411

lookAt(target, offset)

Sets the camera position and orientation using a target and offset. The target must be given in world coordinates. The offset can be either a cartesian or heading/pitch/range in the local east-north-up reference frame centered at the target. If the offset is a cartesian, then it is an offset from the center of the reference frame defined by the transformation matrix. If the offset is heading/pitch/range, then the heading and the pitch angles are defined in the reference frame defined by the transformation matrix. The heading is the angle from y axis and increasing towards the x axis. Pitch is the rotation from the xy-plane. Positive pitch angles are above the plane. Negative pitch angles are below the plane. The range is the distance from the center. In 2D, there must be a top down view. The camera will be placed above the target looking down. The height above the target will be the magnitude of the offset. The heading will be determined from the offset. If the heading cannot be determined from the offset, the heading will be north.
Name Type Description
target Cartesian3 The target position in world coordinates.
offset Cartesian3 | HeadingPitchRange The offset from the target in the local east-north-up reference frame centered at the target.
Throws:
Example:
// 1. Using a cartesian offset
var center = Cesium.Cartesian3.fromDegrees(-98.0, 40.0);
viewer.camera.lookAt(center, new Cesium.Cartesian3(0.0, -4790000.0, 3930000.0));

// 2. Using a HeadingPitchRange offset
var center = Cesium.Cartesian3.fromDegrees(-72.0, 40.0);
var heading = Cesium.Math.toRadians(50.0);
var pitch = Cesium.Math.toRadians(-20.0);
var range = 5000.0;
viewer.camera.lookAt(center, new Cesium.HeadingPitchRange(heading, pitch, range));
Source: Scene/Camera.js, line 1697

lookAtTransform(transform, offset)

Sets the camera position and orientation using a target and transformation matrix. The offset can be either a cartesian or heading/pitch/range. If the offset is a cartesian, then it is an offset from the center of the reference frame defined by the transformation matrix. If the offset is heading/pitch/range, then the heading and the pitch angles are defined in the reference frame defined by the transformation matrix. The heading is the angle from y axis and increasing towards the x axis. Pitch is the rotation from the xy-plane. Positive pitch angles are above the plane. Negative pitch angles are below the plane. The range is the distance from the center. In 2D, there must be a top down view. The camera will be placed above the center of the reference frame. The height above the target will be the magnitude of the offset. The heading will be determined from the offset. If the heading cannot be determined from the offset, the heading will be north.
Name Type Description
transform Matrix4 The transformation matrix defining the reference frame.
offset Cartesian3 | HeadingPitchRange optional The offset from the target in a reference frame centered at the target.
Throws:
Example:
// 1. Using a cartesian offset
var transform = Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(-98.0, 40.0));
viewer.camera.lookAtTransform(transform, new Cesium.Cartesian3(0.0, -4790000.0, 3930000.0));

// 2. Using a HeadingPitchRange offset
var transform = Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(-72.0, 40.0));
var heading = Cesium.Math.toRadians(50.0);
var pitch = Cesium.Math.toRadians(-20.0);
var range = 5000.0;
viewer.camera.lookAtTransform(transform, new Cesium.HeadingPitchRange(heading, pitch, range));
Source: Scene/Camera.js, line 1763

lookDown(amount)

Rotates the camera around its right vector by amount, in radians, in the opposite direction of its up vector.
Name Type Description
amount Number optional The amount, in radians, to rotate by. Defaults to defaultLookAmount.
See:
Source: Scene/Camera.js, line 1393

lookLeft(amount)

Rotates the camera around its up vector by amount, in radians, in the opposite direction of its right vector.
Name Type Description
amount Number optional The amount, in radians, to rotate by. Defaults to defaultLookAmount.
See:
Source: Scene/Camera.js, line 1354

lookRight(amount)

Rotates the camera around its up vector by amount, in radians, in the direction of its right vector.
Name Type Description
amount Number optional The amount, in radians, to rotate by. Defaults to defaultLookAmount.
See:
Source: Scene/Camera.js, line 1367

lookUp(amount)

Rotates the camera around its right vector by amount, in radians, in the direction of its up vector.
Name Type Description
amount Number optional The amount, in radians, to rotate by. Defaults to defaultLookAmount.
See:
Source: Scene/Camera.js, line 1380

move(direction, amount)

Translates the camera's position by amount along direction.
Name Type Description
direction Cartesian3 The direction to move.
amount Number optional The amount, in meters, to move. Defaults to defaultMoveAmount.
See:
Source: Scene/Camera.js, line 1255

moveBackward(amount)

Translates the camera's position by amount along the opposite direction of the camera's view vector.
Name Type Description
amount Number optional The amount, in meters, to move. Defaults to defaultMoveAmount.
See:
Source: Scene/Camera.js, line 1291

moveDown(amount)

Translates the camera's position by amount along the opposite direction of the camera's up vector.
Name Type Description
amount Number optional The amount, in meters, to move. Defaults to defaultMoveAmount.
See:
Source: Scene/Camera.js, line 1316

moveForward(amount)

Translates the camera's position by amount along the camera's view vector.
Name Type Description
amount Number optional The amount, in meters, to move. Defaults to defaultMoveAmount.
See:
Source: Scene/Camera.js, line 1278

moveLeft(amount)

Translates the camera's position by amount along the opposite direction of the camera's right vector.
Name Type Description
amount Number optional The amount, in meters, to move. Defaults to defaultMoveAmount.
See:
Source: Scene/Camera.js, line 1341

moveRight(amount)

Translates the camera's position by amount along the camera's right vector.
Name Type Description
amount Number optional The amount, in meters, to move. Defaults to defaultMoveAmount.
See:
Source: Scene/Camera.js, line 1328

moveUp(amount)

Translates the camera's position by amount along the camera's up vector.
Name Type Description
amount Number optional The amount, in meters, to move. Defaults to defaultMoveAmount.
See:
Source: Scene/Camera.js, line 1303

pickEllipsoid(windowPosition, ellipsoid, result) → Cartesian3

Pick an ellipsoid or map.
Name Type Default Description
windowPosition Cartesian2 The x and y coordinates of a pixel.
ellipsoid Ellipsoid Ellipsoid.WGS84 optional The ellipsoid to pick.
result Cartesian3 optional The object onto which to store the result.
Returns:
If the ellipsoid or map was picked, returns the point on the surface of the ellipsoid or map in world coordinates. If the ellipsoid or map was not picked, returns undefined.
Source: Scene/Camera.js, line 2148

rotate(axis, angle)

Rotates the camera around axis by angle. The distance of the camera's position to the center of the camera's reference frame remains the same.
Name Type Description
axis Cartesian3 The axis to rotate around given in world coordinates.
angle Number optional The angle, in radians, to rotate by. Defaults to defaultRotateAmount.
See:
Source: Scene/Camera.js, line 1469

rotateDown(angle)

Rotates the camera around the center of the camera's reference frame by angle downwards.
Name Type Description
angle Number optional The angle, in radians, to rotate by. Defaults to defaultRotateAmount.
See:
Source: Scene/Camera.js, line 1494

rotateLeft(angle)

Rotates the camera around the center of the camera's reference frame by angle to the left.
Name Type Description
angle Number optional The angle, in radians, to rotate by. Defaults to defaultRotateAmount.
See:
Source: Scene/Camera.js, line 1568

rotateRight(angle)

Rotates the camera around the center of the camera's reference frame by angle to the right.
Name Type Description
angle Number optional The angle, in radians, to rotate by. Defaults to defaultRotateAmount.
See:
Source: Scene/Camera.js, line 1555

rotateUp(angle)

Rotates the camera around the center of the camera's reference frame by angle upwards.
Name Type Description
angle Number optional The angle, in radians, to rotate by. Defaults to defaultRotateAmount.
See:
Source: Scene/Camera.js, line 1507

setView(options)

Sets the camera position, orientation and transform.
Name Type Description
options Object Object with the following properties:
Name Type Description
destination Cartesian3 | Rectangle The final position of the camera in WGS84 (world) coordinates or a rectangle that would be visible from a top-down view.
orientation Object optional An object that contains either direction and up properties or heading, pith and roll properties. By default, the direction will point towards the center of the frame in 3D and in the negative z direction in Columbus view or 2D. The up direction will point towards local north in 3D and in the positive y direction in Columbus view or 2D.
endTransform Matrix4 optional Transform matrix representing the reference frame of the camera.
Example:
// 1. Set position with a top-down view
viewer.camera.setView({
    destination : Cesium.Cartesian3.fromDegrees(-117.16, 32.71, 15000.0)
});

// 2 Set view with heading, pitch and roll
viewer.camera.setView({
    destination : cartesianPosition,
    orientation: {
        heading : Cesium.Math.toRadians(90.0), // east, default value is 0.0 (north)
        pitch : Cesium.Math.toRadians(-90),    // default value (looking down)
        roll : 0.0                             // default value
    }
});

// 3. Change heading, pitch and roll with the camera position remaining the same.
viewer.camera.setView({
    orientation: {
        heading : Cesium.Math.toRadians(90.0), // east, default value is 0.0 (north)
        pitch : Cesium.Math.toRadians(-90),    // default value (looking down)
        roll : 0.0                             // default value
    }
});


// 4. View rectangle with a top-down view
viewer.camera.setView({
    destination : Cesium.Rectangle.fromDegrees(west, south, east, north)
});

// 5. Setposition with an orientation using unit vectors.
viewer.camera.setView({
    destination : Cesium.Cartesian3.fromDegrees(-122.19, 46.25, 5000.0),
    orientation : {
        direction : new Cesium.Cartesian3(-0.04231243104240401, -0.20123236049443421, -0.97862924300734),
        up : new Cesium.Cartesian3(-0.47934589305293746, -0.8553216253114552, 0.1966022179118339)
    }
});
Source: Scene/Camera.js, line 1027

twistLeft(amount)

Rotate the camera counter-clockwise around its direction vector by amount, in radians.
Name Type Description
amount Number optional The amount, in radians, to rotate by. Defaults to defaultLookAmount.
See:
Source: Scene/Camera.js, line 1438

twistRight(amount)

Rotate the camera clockwise around its direction vector by amount, in radians.
Name Type Description
amount Number optional The amount, in radians, to rotate by. Defaults to defaultLookAmount.
See:
Source: Scene/Camera.js, line 1450

viewBoundingSphere(boundingSphere, offset)

Sets the camera so that the current view contains the provided bounding sphere.

The offset is heading/pitch/range in the local east-north-up reference frame centered at the center of the bounding sphere. The heading and the pitch angles are defined in the local east-north-up reference frame. The heading is the angle from y axis and increasing towards the x axis. Pitch is the rotation from the xy-plane. Positive pitch angles are above the plane. Negative pitch angles are below the plane. The range is the distance from the center. If the range is zero, a range will be computed such that the whole bounding sphere is visible.

In 2D, there must be a top down view. The camera will be placed above the target looking down. The height above the target will be the range. The heading will be determined from the offset. If the heading cannot be determined from the offset, the heading will be north.

Name Type Description
boundingSphere BoundingSphere The bounding sphere to view, in world coordinates.
offset HeadingPitchRange optional The offset from the target in the local east-north-up reference frame centered at the target.
Throws:
  • DeveloperError : viewBoundingSphere is not supported while morphing.
Source: Scene/Camera.js, line 2597

viewRectangle(rectangle)

View a rectangle on an ellipsoid or map.
Name Type Description
rectangle Rectangle The rectangle to view.
Deprecated: true
Source: Scene/Camera.js, line 2081

worldToCameraCoordinates(cartesian, result) → Cartesian4

Transform a vector or point from world coordinates to the camera's reference frame.
Name Type Description
cartesian Cartesian4 The vector or point to transform.
result Cartesian4 optional The object onto which to store the result.
Returns:
The transformed vector or point.
Source: Scene/Camera.js, line 1104

worldToCameraCoordinatesPoint(cartesian, result) → Cartesian3

Transform a point from world coordinates to the camera's reference frame.
Name Type Description
cartesian Cartesian3 The point to transform.
result Cartesian3 optional The object onto which to store the result.
Returns:
The transformed point.
Source: Scene/Camera.js, line 1125

worldToCameraCoordinatesVector(cartesian, result) → Cartesian3

Transform a vector from world coordinates to the camera's reference frame.
Name Type Description
cartesian Cartesian3 The vector to transform.
result Cartesian3 optional The object onto which to store the result.
Returns:
The transformed vector.
Source: Scene/Camera.js, line 1146

zoomIn(amount)

Zooms amount along the camera's view vector.
Name Type Description
amount Number optional The amount to move. Defaults to defaultZoomAmount.
See:
Source: Scene/Camera.js, line 1623

zoomOut(amount)

Zooms amount along the opposite direction of the camera's view vector.
Name Type Description
amount Number optional The amount to move. Defaults to defaultZoomAmount.
See:
Source: Scene/Camera.js, line 1640

Type Definitions

FlightCancelledCallback()

A function that will execute when a flight is cancelled.
Source: Scene/Camera.js, line 2724

FlightCompleteCallback()

A function that will execute when a flight completes.
Source: Scene/Camera.js, line 2719