Cesium API - Camera 中文文档

new Cesium.Camera(scene)

由位置、方向和视锥体定义的相机。

视锥体(viewing frustum)由6个(上、下、左、右、近、远)平面限定，每个平面都由 Cartesian4 对象表示，其中x，y和z分量定义垂直于平面的单位向量，w分量是平面到原点/相机位置的距离。

Name	Type	Description
`scene`	Scene	场景（Scene对象）。

示例：

// 创建一个位置在原点，看向z轴负方向，视角60度，长宽比1:1的相机。
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：

成员变量

staticCesium.Camera.DEFAULT_OFFSET : HeadingPitchRange

Scene/Camera.js 247

当相机拉近到物体包围球时，默认的heading/pitch/range值。

staticCesium.Camera.DEFAULT_VIEW_FACTOR : Number

Scene/Camera.js 241

该值用来确定相机位置，当值为0是相机观察范围是整个Camera#DEFAULT_VIEW_RECTANGLE，大于0时远离Camera#DEFAULT_VIEW_RECTANGLE，小于0时向Camera#DEFAULT_VIEW_RECTANGLE拉近。

staticCesium.Camera.DEFAULT_VIEW_RECTANGLE : Rectangle

Scene/Camera.js 233

相机在创建时查看的默认矩形位置。

readonlychanged : Event

Scene/Camera.js 913

获取相机通过percentageChanged改变时触发的事件。

constrainedAxis : Cartesian3

Scene/Camera.js 170

如果设置，相机将不能在任何方向上通过这个轴旋转。

Default Value: undefined

defaultLookAmount : Number

Scene/Camera.js 152

当未向look方法提供参数时，相机默认的旋转步长。

Default Value: Math.PI / 60.0

defaultMoveAmount : Number

Scene/Camera.js 146

当未向move方法提供参数时，相机默认移动步长。

Default Value: 100000.0

defaultRotateAmount : Number

Scene/Camera.js 158

当未向rotate方法提供参数时，相机默认的旋转步长。

Default Value: Math.PI / 3600.0

defaultZoomAmount : Number

Scene/Camera.js 164

当未向zoom方法提供参数时，相机默认的移动步长。

Default Value: 100000.0;

direction : Cartesian3

Scene/Camera.js 106

相机的观察方向。

readonlydirectionWC : Cartesian3

Scene/Camera.js 767

获取世界坐标系中相机的观察方向。

frustum : Frustum

Scene/Camera.js 137

视锥（平截头体）

Default Value: PerspectiveFrustum()

参考：

readonlyheading : Number

Scene/Camera.js 809

获取相机的偏航角，以弧度表示。

readonlyinverseTransform : Matrix4

Scene/Camera.js 692

获取相机的变换矩阵的逆矩阵。

Default Value: Matrix4.IDENTITY

readonlyinverseViewMatrix : Matrix4

Scene/Camera.js 724

获取视图矩阵的逆矩阵。

参考：

Camera#viewMatrix

maximumZoomFactor : Number

Scene/Camera.js 176

缩放因子，用于确定相机位置。只在2D模式并且地图是可旋转时有效。

Default Value: 1.5

readonlymoveEnd : Event

Scene/Camera.js 901

获取相机停止移动时触发的事件。

readonlymoveStart : Event

Scene/Camera.js 889

获取相机在开始移动时触发的事件。

percentageChanged : number

Scene/Camera.js 191

在引发changed事件之前，相机必须更改的值，该值范围是[0,1]。

Default Value: 0.5

readonlypitch : Number

Scene/Camera.js 836

获取相机的俯仰角，以弧度表示。

position : Cartesian3

Scene/Camera.js 74

相机的位置。

readonlypositionCartographic : Cartographic

Scene/Camera.js 739

获取相机的Cartographic位置，经度和纬度以弧度表示，高度以米表示。在2D和Columbus视图中，当相机位于地图之外时，返回的经度和纬度可能超出有效经度和纬度的范围。

readonlypositionWC : Cartesian3

Scene/Camera.js 753

获取世界坐标系中相机的位置。

right : Cartesian3

Scene/Camera.js 123

相机向右的方向

readonlyrightWC : Cartesian3

Scene/Camera.js 795

获取世界坐标系中相机向右的方向。

readonlyroll : Number

Scene/Camera.js 863

获取相机的翻滚角，以弧度表示。

readonlytransform : Matrix4

Scene/Camera.js 677

获取相机的变换矩阵。

Default Value: Matrix4.IDENTITY

up : Cartesian3

Scene/Camera.js 114

相机向上的方向。

readonlyupWC : Cartesian3

Scene/Camera.js 781

获取世界坐标系中相机的向上方向。

readonlyviewMatrix : Matrix4

Scene/Camera.js 708

获取视图矩阵。

参考：

Camera#inverseViewMatrix

内置方法

cameraToWorldCoordinates(cartesian, result) → Cartesian4

Scene/Camera.js 1392

将一个向量或点从相机的参考系转换为世界坐标。

Name	Type	Description
`cartesian`	Cartesian4	要变换的向量或点。
`result`	Cartesian4	optional 存储结果的对象。

返回值：

变换后的向量或点。

cameraToWorldCoordinatesPoint(cartesian, result) → Cartesian3

Scene/Camera.js 1413

将一个点从相机的参考坐标系转换为世界坐标。

Name	Type	Description
`cartesian`	Cartesian3	要变换的点。
`result`	Cartesian3	optional 存储结果的对象。

返回值：

变换后的点。

cameraToWorldCoordinatesVector(cartesian, result) → Cartesian3

Scene/Camera.js 1434

将一个向量从相机的参考坐标系变换到世界坐标。

Name	Type	Description
`cartesian`	Cartesian3	要变换的向量。
`result`	Cartesian3	optional 存储结果的对象。

返回值：

变换后的向量。

cancelFlight()

Scene/Camera.js 2710

取消当前正在进行的相机飞行。相机留在当前位置。

computeViewRectangle(ellipsoid, result) → Rectangle|undefined

Scene/Camera.js 3100

在椭球面上计算近似可见矩形。

Name	Type	Default	Description
`ellipsoid`	Ellipsoid	`Ellipsoid.WGS84`	optional 椭球。
`result`	Rectangle		optional 存储结果的矩形。

返回值：

可见的矩形；如果椭圆形根本不可见，则为undefined。

distanceToBoundingSphere(boundingSphere) → Number

Scene/Camera.js 2560

返回从相机到包围球的前端的距离。

Name	Type	Description
`boundingSphere`	BoundingSphere	世界坐标中的包围球。

返回值：

到包围球的距离。

flyHome(duration)

Scene/Camera.js 1278

相机飞行到home位置，使用 Camera#.DEFAULT_VIEW_RECTANGLE设置3D场景的默认home位置。

Name	Type	Description
`duration`	Number	optional 飞行时间，以秒为单位。

flyTo(options)

Scene/Camera.js 2766

将相机从当前位置切换到新位置。

Name Type Description

options

Object

具有下列属性的对象：

Name	Type	Description
`destination`	Cartesian3 \| Rectangle	相机的位置。
`orientation`	Object	optional 包含相机偏航角、俯仰角、翻滚角的对象。
`duration`	Number	optional 飞行时间以秒为单位。
`complete`	Camera~FlightCompleteCallback	optional 当飞行完成时执行的函数。
`cancel`	Camera~FlightCancelledCallback	optional 如果飞行取消，要执行的函数。
`endTransform`	Matrix4	optional 相机的最终转换矩阵。
`maximumHeight`	Number	optional 飞行高峰期的最高高度。
`pitchAdjustHeight`	Number	optional 如果相机飞行高度高于该值，调整俯仰，使飞行向下看，并保持地球在视口。
`flyOverLongitude`	Number	optional 地球上两点之间总是有两条路经。此参数指定飞行路经经过的经度。
`flyOverLongitudeWeight`	Number	optional 只有在飞行距离不超过flyOverLongitudeWeight的情况下，才可以通过flyOverLongitude飞越指定的经线。
`convert`	Boolean	optional 是否将目标从世界坐标转换为场景坐标 (只有在不使用3D模式时才有意义)，默认是true。
`easingFunction`	EasingFunction \| EasingFunction~Callback	optional 控制如何在飞行期间内插时间。

异常情况：

DeveloperError : 如果给定了direction或up，则两者都是必需的。

示例：

// 1. 飞到一个自顶向下看的位置点
viewer.camera.flyTo({
    destination : Cesium.Cartesian3.fromDegrees(-117.16, 32.71, 15000.0)
});
// 2. 飞到一个自顶向下看的矩形位置
viewer.camera.flyTo({
    destination : Cesium.Rectangle.fromDegrees(west, south, east, north)
});
// 3. 飞到一个位置并使用单位向量确定观看方向
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. 飞到一个位置并使用偏航角、俯仰角、翻滚角确定观看方向
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
    }
});

flyToBoundingSphere(boundingSphere, options)

Scene/Camera.js 2961

将相机飞到当前视图包含所提供的包围球的位置。

偏移量是在以边界球中心为中心的局部东北向上参考框中的heading/pitch/range。

在2D模式下，必须有一个俯视图。相机将被放置在目标上方并向下看。上方的高度目标将是范围。航向将根据偏移量确定。如果不能根据偏移量确定，航向将为北。

Name Type Description

boundingSphere BoundingSphere 在世界坐标中的包围球。

options

Object

optional 具有下列属性的对象：

Name	Type	Description
`duration`	Number	optional 飞行时间，以秒为单位。
`offset`	HeadingPitchRange	optional 在局部东北向上参考系中，以目标为中心与目标的偏移。
`complete`	Camera~FlightCompleteCallback	optional 当飞行完成时执行的函数。
`cancel`	Camera~FlightCancelledCallback	optional 如果飞行取消，要执行的函数。
`endTransform`	Matrix4	optional 相机的最终转换矩阵。
`maximumHeight`	Number	optional 飞行高峰期的最高高度。
`pitchAdjustHeight`	Number	optional 如果相机飞行高度高于该值，调整俯仰，使飞行向下看，并保持地球在视口。
`flyOverLongitude`	Number	optional There are always two ways between 2 points on globe. This option force camera to choose fight direction to fly over that longitude.
`flyOverLongitudeWeight`	Number	optional 地球上两点之间总是有两条路。这个值是飞行经过的经度。
`easingFunction`	EasingFunction \| EasingFunction~Callback	optional 控制如何在飞行期间内插时间。

getMagnitude() → Number

Scene/Camera.js 1937

获取相机位置的大小，在3D中，这是矢量大小，在2D和哥伦布视图中，这是到地图的距离。

返回值：

位置的大小。

getPickRay(windowPosition, result) → Ray

Scene/Camera.js 2532

在世界坐标中，通过像素位置windowPosition，从相机位置创建一条射线。

Name	Type	Description
`windowPosition`	Cartesian2	一个像素的x和y坐标。
`result`	Ray	optional 存储结果的对象。

返回值：

返回Cartesian3射线的位置和方向。

getPixelSize(boundingSphere, drawingBufferWidth, drawingBufferHeight) → Number

Scene/Camera.js 2582

返回像素大小(以米为单位)，分辨率。

Name	Type	Description
`boundingSphere`	BoundingSphere	世界坐标中的包围球。
`drawingBufferWidth`	Number	绘图缓冲区宽度。
`drawingBufferHeight`	Number	绘图缓冲区高度。

返回值：

像素大小(以米为单位)

getRectangleCameraCoordinates(rectangle, result) → Cartesian3

Scene/Camera.js 2357

获取在椭球面或地图上查看矩形所需的相机位置

Name	Type	Description
`rectangle`	Rectangle	要查看的矩形。
`result`	Cartesian3	optional 查看矩形所需的相机位置。

返回值：

查看矩形所需的相机位置。

look(axis, angle)

Scene/Camera.js 1663

将相机沿axis旋转angle弧度（相机位置不变）

Name	Type	Description
`axis`	Cartesian3	旋转轴
`angle`	Number	optional 旋转的量，以弧度为单位，默认是`defaultLookAmount`。

参考：

lookAt(target, offset)

Scene/Camera.js 1971

使用目标和偏移量设置相机的位置和方向，目标必须用世界坐标表示，偏移量可以是一个笛卡尔坐标，也可以是在以目标为中心的局部东北向上参考系中的heading/pitch/range。

Name	Type	Description
`target`	Cartesian3	世界坐标系中的目标位置。
`offset`	Cartesian3 \| HeadingPitchRange	在局部东北朝上的参考系中，距目标的偏移量。

异常情况：

DeveloperError : 变形时不支持lookAt。

示例：

// 1. 使用笛卡尔坐标偏移
var center = Cesium.Cartesian3.fromDegrees(-98.0, 40.0);
viewer.camera.lookAt(center, new Cesium.Cartesian3(0.0, -4790000.0, 3930000.0));
// 2.使用HeadingPitchRange偏移
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));

lookAtTransform(transform, offset)

Scene/Camera.js 2029

使用目标和变换矩阵设置相机的位置和方向。

Name	Type	Description
`transform`	Matrix4	定义参考系的变换矩阵。
`offset`	Cartesian3 \| HeadingPitchRange	optional 在以目标为中心的参考系中，与目标的偏移量。

异常情况：

DeveloperError : 变形时不支持lookAtTransform。

示例：

// 1. 使用笛卡尔坐标偏移
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.使用HeadingPitchRange偏移
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));

lookDown(amount)

Scene/Camera.js 1641

绕着向右的方向，向下方向以弧度为单位旋转。（2D模式除外）

Name	Type	Description
`amount`	Number	optional 旋转的量，单位是弧度，默认是`defaultLookAmount`。

参考：

Camera#lookUp

lookLeft(amount)

Scene/Camera.js 1596

绕着向上的方向，向左方向以弧度为单位旋转。（2D模式除外）

Name	Type	Description
`amount`	Number	optional 旋转的量，单位是弧度，默认是`defaultLookAmount`。

参考：

Camera#lookRight

lookRight(amount)

Scene/Camera.js 1611

绕着向上的方向，向右方向以弧度为单位旋转。（2D模式除外）

Name	Type	Description
`amount`	Number	optional 旋转的量，单位是弧度，默认是`defaultLookAmount`。

参考：

Camera#lookLeft

lookUp(amount)

Scene/Camera.js 1626

绕着向右的方向，向上方向以弧度为单位旋转。（2D模式除外）

Name	Type	Description
`amount`	Number	optional 旋转的量，单位是弧度，默认是`defaultLookAmount`。

参考：

Camera#lookDown

move(direction, amount)

Scene/Camera.js 1492

沿direction通过amount变换相机的位置。

Name	Type	Description
`direction`	Cartesian3	移动的方向。
`amount`	Number	optional 移动的量，以米为单位，默认是`defaultMoveAmount`.

参考：

moveBackward(amount)

Scene/Camera.js 1533

沿相机观察方向的相反方向，通过amount 变换相机的位置。（后退）

Name	Type	Description
`amount`	Number	optional 移动的量，以米为单位，默认是 `defaultMoveAmount`。

参考：

Camera#moveForward

moveDown(amount)

Scene/Camera.js 1562

沿相机向上方向的反方向，通过amount 变换相机的位置。（向下）

Name	Type	Description
`amount`	Number	optional 移动的量，以米为单位，默认是`defaultMoveAmount`。

参考：

Camera#moveUp

moveForward(amount)

Scene/Camera.js 1515

沿相机观察的方向，通过amount 变换相机的位置。（前进）

Name	Type	Description
`amount`	Number	optional 移动的量，以米为单位，默认是 `defaultMoveAmount`。

参考：

Camera#moveBackward

moveLeft(amount)

Scene/Camera.js 1585

沿相机向右方向的反方向，通过amount 变换相机的位置。（向左）

Name	Type	Description
`amount`	Number	optional 移动的量，以米为单位，默认是`defaultMoveAmount`。

参考：

Camera#moveRight

moveRight(amount)

Scene/Camera.js 1573

沿相机向右的方向，通过amount 变换相机的位置。（向右）

Name	Type	Description
`amount`	Number	optional 移动的量，以米为单位，默认是`defaultMoveAmount`。

参考：

Camera#moveLeft

moveUp(amount)

Scene/Camera.js 1551

沿相机向上的方向，通过amount 变换相机的位置。（向上）

Name	Type	Description
`amount`	Number	optional 移动的量，以米为单位，默认是`defaultMoveAmount`。

参考：

Camera#moveDown

pickEllipsoid(windowPosition, ellipsoid, result) → Cartesian3

Scene/Camera.js 2431

选择一个椭球或地图。

Name	Type	Default	Description
`windowPosition`	Cartesian2		一个像素的x和y坐标。
`ellipsoid`	Ellipsoid	`Ellipsoid.WGS84`	optional 选择的椭球。
`result`	Cartesian3		optional 存储结果的对象。

返回值：

如果选择了椭球或地图，则返回椭球或地图在世界坐标中的点。如果没有选择了椭球或地图，返回undefined。

rotate(axis, angle)

Scene/Camera.js 1720

围绕轴axis旋转相机angle。相机的位置到相机的参考系中心的距离保持不变。（相机位置改变）

Name	Type	Description
`axis`	Cartesian3	以世界坐标表示的旋转轴。
`angle`	Number	optional 以弧度表示的旋转量，默认值为 `defaultRotateAmount`。

参考：

rotateDown(angle)

Scene/Camera.js 1747

围绕相机参考系的中心向下旋转相机。

Name	Type	Description
`angle`	Number	optional 以弧度表示的旋转量，默认值为 `defaultRotateAmount`。

参考：

rotateLeft(angle)

Scene/Camera.js 1820

围绕相机机参考系的中心向左旋转相机。

Name	Type	Description
`angle`	Number	optional 以弧度表示的旋转量，默认值为 `defaultRotateAmount`。

参考：

rotateRight(angle)

Scene/Camera.js 1807

围绕相机机参考系的中心向右旋转相机。

Name	Type	Description
`angle`	Number	optional 以弧度表示的旋转量，默认值为 `defaultRotateAmount`。

参考：

rotateUp(angle)

Scene/Camera.js 1759

围绕相机机参考系的中心向上旋转相机。

Name	Type	Description
`angle`	Number	optional 以弧度表示的旋转量，默认值为 `defaultRotateAmount`。

参考：

setView(options)

Scene/Camera.js 1233

设置相机的位置、方向和变换。

Name Type Description

options

Object

具有下列属性的对象:

Name	Type	Description
`destination`	Cartesian3 \| Rectangle	optional 相机的位置。
`orientation`	Object	optional 包含相机偏航角、俯仰角、翻滚角的对象。
`endTransform`	Matrix4	optional 相机的最终转换矩阵。
`convert`	Boolean	optional 是否将目标从世界坐标转换为场景坐标 (只有在不使用3D模式时才有意义)，默认是true。

示例：

// 1. 设置相机从上往下看时，相机的位置。
viewer.camera.setView({
    destination : Cesium.Cartesian3.fromDegrees(-117.16, 32.71, 15000.0)
});
// 2 设置相机的方位
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. 相机位置不变的情况下，改变偏航角、俯仰角、翻滚角。
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. 使用单位向量设置位置和方向。
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)
    }
});

switchToOrthographicFrustum()

Scene/Camera.js 3180

将截头/投影转换为正交投影。这个函数在2D中是无操作的，它必须总是正交的。

switchToPerspectiveFrustum()

Scene/Camera.js 3164

将视锥体/投影切换到透视图。这个函数在2D中是无操作的，它必须总是正交的。

twistLeft(amount)

Scene/Camera.js 1690

以弧度为单位围绕其方向矢量逆时针旋转相机。

Name	Type	Description
`amount`	Number	optional 旋转的量，以弧度为单位，默认是`defaultLookAmount`。

参考：

Camera#twistRight

twistRight(amount)

Scene/Camera.js 1702

以弧度为单位围绕其方向矢量顺时针旋转相机。

Name	Type	Description
`amount`	Number	optional 旋转的量，以弧度为单位，默认是`defaultLookAmount`。

参考：

Camera#twistLeft

viewBoundingSphere(boundingSphere, offset)

Scene/Camera.js 2916

设置像机，使当前视图包含提供的包围球。

偏移量是在以边界球中心为中心的局部东北向上参考框中的heading/pitch/range。

Name	Type	Description
`boundingSphere`	BoundingSphere	在世界坐标中的包围球。
`offset`	HeadingPitchRange	optional 在局部东北向上参考系中，以目标为中心与目标的偏移。