Camera

new Cesium.Camera(scene)

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

朝向通过视图、向上和向右 = 视图 x 向上单位向量形成正交基。

视锥体由 6 个平面定义。 每个平面由一个 Cartesian4 对象表示,其中 x、y 和 z 分量 定义垂直于平面的单位向量,w 分量是 平面与原点/相机位置的距离。
Name Type Description
scene Scene 场景。
Example:
// 创建一个沿负 z 轴向下看,位于原点,
// 视场角为 60 度,宽高比为 1:1 的相机。
const 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:

Members

static Cesium.Camera.DEFAULT_OFFSET : HeadingPitchRange

当相机飞到包含包围球的位置时使用的默认航向/俯仰/距离。

static Cesium.Camera.DEFAULT_VIEW_FACTOR : number

乘以相机位置的标量,在设置相机查看矩形后加回。 值为零表示相机将查看整个 Camera#DEFAULT_VIEW_RECTANGLE,大于零的值 将使其远离范围,小于零的值将使其靠近范围。

static Cesium.Camera.DEFAULT_VIEW_RECTANGLE : Rectangle

创建时相机默认查看的矩形。
获取相机改变量达到 percentageChanged 时将触发的事件。

constrainedAxis : Cartesian3|undefined

如果设置,相机将无法绕此轴旋转。
Default Value: undefined

defaultLookAmount : number

未向观察方法提供参数时旋转相机的默认量。
Default Value: Math.PI / 60.0

defaultMoveAmount : number

未向移动方法提供参数时移动相机的默认量。
Default Value: 100000.0;

defaultRotateAmount : number

未向旋转方法提供参数时旋转相机的默认量。
Default Value: Math.PI / 3600.0

defaultZoomAmount : number

未向缩放方法提供参数时移动相机的默认量。
Default Value: 100000.0;
相机的视图方向。
获取相机在世界坐标系中的视图方向。
可见的空间区域。
Default Value: PerspectiveFrustum()
See:

readonly heading : number

获取相机的航向角(弧度)。

readonly inverseTransform : Matrix4

获取相机的逆变换。
Default Value: Matrix4.IDENTITY

readonly inverseViewMatrix : Matrix4

获取逆视图矩阵。
See:

maximumZoomFactor : number

用于确定缩放时在哪里限制相机位置的地图大小的系数。 默认值为 1.5。仅对 2D 有效且地图可旋转。
Default Value: 1.5
获取相机停止移动时将触发的事件。
获取相机开始移动时将触发的事件。

percentageChanged : number

触发 changed 事件前相机必须改变的量。该值是 [0, 1] 范围内的百分比。
Default Value: 0.5

readonly pitch : number

获取相机的俯仰角(弧度)。
相机的位置。

readonly positionCartographic : Cartographic

获取相机的 Cartographic 位置,经度和纬度以弧度表示,高度以米表示。在 2D 和哥伦布视图中,当相机在地图外时,返回的经度和纬度可能超出有效范围。
获取相机在世界坐标系中的位置。
相机的向右方向。
获取相机的向右方向。

readonly roll : number

获取相机的翻滚角(弧度)。
获取相机的参考帧。此变换的逆矩阵被附加到视图矩阵上。
Default Value: Matrix4.IDENTITY
相机的向上方向。
获取相机在世界坐标系中的向上方向。
获取视图矩阵。
See:

Methods

cameraToWorldCoordinates(cartesian, result)Cartesian4

将向量或点从相机的参考帧变换到世界坐标系。
Name Type Description
cartesian Cartesian4 要变换的向量或点。
result Cartesian4 optional 存储结果的对象。
Returns:
变换后的向量或点。

cameraToWorldCoordinatesPoint(cartesian, result)Cartesian3

将点从相机的参考帧变换到世界坐标系。
Name Type Description
cartesian Cartesian3 要变换的点。
result Cartesian3 optional 存储结果的对象。
Returns:
变换后的点。

cameraToWorldCoordinatesVector(cartesian, result)Cartesian3

将向量从相机的参考帧变换到世界坐标系。
Name Type Description
cartesian Cartesian3 要变换的向量。
result Cartesian3 optional 存储结果的对象。
Returns:
变换后的向量。
取消当前相机飞行并将相机留在其当前位置。 如果没有飞行正在进行,此函数不执行任何操作。
完成当前相机飞行并立即将相机移动到其最终目的地。 如果没有飞行正在进行,此函数不执行任何操作。

computeViewRectangle(ellipsoid, result)Rectangle|undefined

计算椭球上近似可见的矩形。
Name Type Default Description
ellipsoid Ellipsoid Ellipsoid.default optional 要获取可见区域的椭球。
result Rectangle optional 存储结果的矩形。
Returns:
可见矩形,如果椭球完全不可见则返回 undefined。

distanceToBoundingSphere(boundingSphere)number

返回相机到包围球前部的距离。
Name Type Description
boundingSphere BoundingSphere 世界坐标系中的包围球。
Returns:
到包围球的距离。
将相机飞到主视图。使用 Camera#.DEFAULT_VIEW_RECTANGLE 设置 3D 场景的默认视图。2D 和哥伦布视图的主视图显示整个地图。
Name Type Description
duration number optional 飞行的持续时间(秒)。如果省略,Cesium 会尝试根据飞行距离计算理想的持续时间。请参阅 Camera#flyTo
将相机从当前位置飞行到新位置。
Name Type Description
options object 包含以下属性的对象:
Name Type Description
destination Cartesian3 | Rectangle 相机在世界坐标系中的最终位置,或从俯视角度可见的矩形。
orientation object optional 一个对象,包含 direction 和 up 属性,或 heading、pitch 和 roll 属性。默认情况下,方向将指向 3D 中帧的中心,在哥伦布视图中指向负 z 方向。向上方向将指向 3D 中的局部北方,在哥伦布视图中指向正 y 方向。在无限滚动模式的 2D 中不使用朝向。
duration number optional 飞行的持续时间(秒)。如果省略,Cesium 会尝试根据飞行距离计算理想的持续时间。
complete Camera.FlightCompleteCallback optional 飞行完成时执行的函数。
cancel Camera.FlightCancelledCallback optional 飞行取消时执行的函数。
endTransform Matrix4 optional 变换矩阵,表示飞行完成时相机所在的参考帧。
maximumHeight number optional 飞行高峰时的最大高度。
pitchAdjustHeight number optional 如果相机飞行高于此值,则在飞行期间调整俯仰角向下看,并保持地球在视口内。
flyOverLongitude number optional 地球上两点之间总有两条路。此选项强制相机选择飞行方向飞越该经度。
flyOverLongitudeWeight number optional 仅当通过 flyOverLongitude 指定的经度路径不长于短路径乘以 flyOverLongitudeWeight 时才飞越该经度。
convert boolean optional 是否将目标从世界坐标系转换到场景坐标系(仅在不使用 3D 时相关)。默认为 true
easingFunction EasingFunction.Callback optional 控制飞行持续时间内时间的插值方式。
Throws:
  • DeveloperError : 如果给出了 direction 或 up 中的任何一个,则两者都需要。
Example:
// 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)

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

偏移是包围球中心处局部东北天参考系中的航向/俯仰/距离。 航向和俯仰角在局部东北天参考系中定义。 航向是从 y 轴开始并向 x 轴方向增加的角度。俯仰是从 xy 平面的旋转。正俯仰角在平面下方。负俯仰角在平面上方。距离是到中心的距离。如果距离为 零,则将计算一个距离以使整个包围球可见。

在 2D 和哥伦布视图中,必须是俯视视角。相机将放置在目标上方俯视。目标上方的高度将是距离。航向将与局部北方对齐。

Name Type Description
boundingSphere BoundingSphere 要查看的包围球(世界坐标)。
options object optional 包含以下属性的对象:
Name Type Description
duration number optional 飞行的持续时间(秒)。如果省略,Cesium 会尝试根据飞行距离计算理想的持续时间。
offset HeadingPitchRange optional 目标处局部东北天参考系中的偏移。
complete Camera.FlightCompleteCallback optional 飞行完成时执行的函数。
cancel Camera.FlightCancelledCallback optional 飞行取消时执行的函数。
endTransform Matrix4 optional 变换矩阵,表示飞行完成时相机所在的参考帧。
maximumHeight number optional 飞行高峰时的最大高度。
pitchAdjustHeight number optional 如果相机飞行高于此值,则在飞行期间调整俯仰角向下看,并保持地球在视口内。
flyOverLongitude number optional 地球上两点之间总有两条路。此选项强制相机选择飞行方向飞越该经度。
flyOverLongitudeWeight number optional 仅当通过 flyOverLongitude 指定的经度路径不长于短路径乘以 flyOverLongitudeWeight 时才飞越该经度。
easingFunction EasingFunction.Callback optional 控制飞行持续时间内时间的插值方式。

getMagnitude()number

获取相机位置的模长。在 3D 中,这是向量模长。在 2D 和哥伦布视图中,这是到地图的距离。
Returns:
位置的模长。

getPickRay(windowPosition, result)Ray|undefined

从相机位置穿过 windowPosition 处的像素创建一条射线(世界坐标)。
Name Type Description
windowPosition Cartesian2 像素的 x 和 y 坐标。
result Ray optional 存储结果的对象。
Returns:
返回射线的 Cartesian3 位置和方向,如果无法确定拾取射线则返回 undefined。

getPixelSize(boundingSphere, drawingBufferWidth, drawingBufferHeight)number

返回以米为单位的像素大小。
Name Type Description
boundingSphere BoundingSphere 世界坐标系中的包围球。
drawingBufferWidth number 绘图缓冲区宽度。
drawingBufferHeight number 绘图缓冲区高度。
Returns:
以米为单位的像素大小。

getRectangleCameraCoordinates(rectangle, result)Cartesian3

获取查看椭球或地图上矩形所需的相机位置。
Name Type Description
rectangle Rectangle 要查看的矩形。
result Cartesian3 optional 查看矩形所需的相机位置。
Returns:
查看矩形所需的相机位置。
将相机的每个朝向向量绕 axis 轴旋转 angle 角度。
Name Type Description
axis Cartesian3 要绕其旋转的轴。
angle number optional 旋转角度(弧度)。默认为 defaultLookAmount
See:

lookAt(target, offset)

使用目标和偏移设置相机的位置和朝向。目标必须以世界坐标给出。偏移可以是笛卡尔坐标或目标处的局部东北天参考系中的航向/俯仰/距离。 如果偏移是笛卡尔坐标,则是从变换矩阵定义的参考系中心的偏移。如果偏移是航向/俯仰/距离,则航向和俯仰角在变换矩阵定义的参考系中定义。 航向是从 y 轴开始并向 x 轴方向增加的角度。俯仰是从 xy 平面的旋转。正俯仰角在平面下方。负俯仰角在平面上方。距离是到中心的距离。 在 2D 中,必须是俯视视角。相机将放置在目标上方俯视。目标上方的高度将是偏移的模长。航向将由偏移确定。如果无法从偏移确定航向,则航向将为北方。
Name Type Description
target Cartesian3 目标位置(世界坐标)。
offset Cartesian3 | HeadingPitchRange 目标处局部东北天参考系中的偏移。
Throws:
Example:
// 1. 使用笛卡尔偏移
const center = Cesium.Cartesian3.fromDegrees(-98.0, 40.0);
viewer.camera.lookAt(center, new Cesium.Cartesian3(0.0, -4790000.0, 3930000.0));

// 2. 使用航向/俯仰/距离偏移
const center = Cesium.Cartesian3.fromDegrees(-72.0, 40.0);
const heading = Cesium.Math.toRadians(50.0);
const pitch = Cesium.Math.toRadians(-20.0);
const range = 5000.0;
viewer.camera.lookAt(center, new Cesium.HeadingPitchRange(heading, pitch, range));

lookAtTransform(transform, offset)

使用目标位置和变换矩阵设置相机的位置和朝向。偏移可以是笛卡尔坐标或航向/俯仰/距离。 如果偏移是笛卡尔坐标,则是从变换矩阵定义的参考系中心的偏移。如果偏移是航向/俯仰/距离,则航向和俯仰角在变换矩阵定义的参考系中定义。 航向是从 y 轴开始并向 x 轴方向增加的角度。俯仰是从 xy 平面的旋转。正俯仰角在平面下方。负俯仰角在平面上方。距离是到中心的距离。 在 2D 中,必须是俯视视角。相机将放置在参考帧中心上方。目标上方的高度将是偏移的模长。航向将由偏移确定。如果无法从偏移确定航向,则航向将为北方。
Name Type Description
transform Matrix4 定义参考系的变换矩阵。
offset Cartesian3 | HeadingPitchRange optional 目标处局部参考系中的偏移。
Throws:
Example:
// 1. 使用笛卡尔偏移
const 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. 使用航向/俯仰/距离偏移
const transform = Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(-72.0, 40.0));
const heading = Cesium.Math.toRadians(50.0);
const pitch = Cesium.Math.toRadians(-20.0);
const range = 5000.0;
viewer.camera.lookAtTransform(transform, new Cesium.HeadingPitchRange(heading, pitch, range));
在非 2D 模式下,相机绕其向右向量旋转 amount 弧度,方向与其向上向量相反。
Name Type Description
amount number optional 旋转量(弧度)。默认为 defaultLookAmount
See:
在非 2D 模式下,相机绕其向上向量旋转 amount 弧度,方向与其向右向量相反。
Name Type Description
amount number optional 旋转量(弧度)。默认为 defaultLookAmount
See:
在非 2D 模式下,相机绕其向上向量旋转 amount 弧度,方向与其向右向量相同。
Name Type Description
amount number optional 旋转量(弧度)。默认为 defaultLookAmount
See:
在非 2D 模式下,相机绕其向右向量旋转 amount 弧度,方向与其向上向量相同。
Name Type Description
amount number optional 旋转量(弧度)。默认为 defaultLookAmount
See:

move(direction, amount)

沿 direction 方向将相机位置平移 amount 距离。
Name Type Description
direction Cartesian3 移动方向。
amount number optional 移动量(米)。默认为 defaultMoveAmount
See:

moveBackward(amount)

沿相机视图向量反方向将相机位置平移 amount 距离。 在 2D 模式下,这将缩放相机而不是平移相机位置。
Name Type Description
amount number optional 移动量(米)。默认为 defaultMoveAmount
See:
沿相机向上向量反方向将相机位置平移 amount 距离。
Name Type Description
amount number optional 移动量(米)。默认为 defaultMoveAmount
See:
沿相机视图向量方向将相机位置平移 amount 距离。 在 2D 模式下,这将缩放相机而不是平移相机位置。
Name Type Description
amount number optional 移动量(米)。默认为 defaultMoveAmount
See:
沿相机向右向量反方向将相机位置平移 amount 距离。
Name Type Description
amount number optional 移动量(米)。默认为 defaultMoveAmount
See:
沿相机向右向量方向将相机位置平移 amount 距离。
Name Type Description
amount number optional 移动量(米)。默认为 defaultMoveAmount
See:
沿相机向上向量方向将相机位置平移 amount 距离。
Name Type Description
amount number optional 移动量(米)。默认为 defaultMoveAmount
See:

pickEllipsoid(windowPosition, ellipsoid, result)Cartesian3|undefined

拾取椭球或地图。
Name Type Default Description
windowPosition Cartesian2 像素的 x 和 y 坐标。
ellipsoid Ellipsoid Ellipsoid.default optional 要拾取的椭球。
result Cartesian3 optional 存储结果的对象。
Returns:
如果拾取了椭球或地图,则返回世界坐标系中椭球或地图表面上的点。如果未拾取椭球或地图,则返回 undefined。
Example:
const canvas = viewer.scene.canvas;
const center = new Cesium.Cartesian2(canvas.clientWidth / 2.0, canvas.clientHeight / 2.0);
const ellipsoid = viewer.scene.ellipsoid;
const result = viewer.camera.pickEllipsoid(center, ellipsoid);
相机绕 axis 轴旋转 angle 角度。相机位置到相机参考帧中心的距离保持不变。
Name Type Description
axis Cartesian3 要绕其旋转的轴(世界坐标)。
angle number optional 旋转角度(弧度)。默认为 defaultRotateAmount
See:
相机绕其参考帧中心向下旋转 angle 角度。
Name Type Description
angle number optional 旋转角度(弧度)。默认为 defaultRotateAmount
See:
相机绕其参考帧中心向左旋转 angle 角度。
Name Type Description
angle number optional 旋转角度(弧度)。默认为 defaultRotateAmount
See:
相机绕其参考帧中心向右旋转 angle 角度。
Name Type Description
angle number optional 旋转角度(弧度)。默认为 defaultRotateAmount
See:
相机绕其参考帧中心向上旋转 angle 角度。
Name Type Description
angle number optional 旋转角度(弧度)。默认为 defaultRotateAmount
See:
设置相机的位置、朝向和变换。
Name Type Description
options object 包含以下属性的对象:
Name Type Description
destination Cartesian3 | Rectangle optional 相机在世界坐标系中的最终位置,或从俯视角度可见的矩形。
orientation HeadingPitchRollValues | DirectionUp optional 一个对象,包含 direction 和 up 属性,或 heading、pitch 和 roll 属性。默认情况下,方向将指向 3D 中帧的中心,在哥伦布视图中指向负 z 方向。向上方向将指向 3D 中的局部北方,在哥伦布视图中指向正 y 方向。在无限滚动模式的 2D 中不使用朝向。
endTransform Matrix4 optional 变换矩阵,表示相机的参考帧。
convert boolean optional 是否将目标从世界坐标系转换到场景坐标系(仅在不使用 3D 时相关)。默认为 true
Example:
// 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), // 东,默认值为 0.0(北)
        pitch : Cesium.Math.toRadians(-90),    // 默认值(向下看)
        roll : 0.0                             // 默认值
    }
});

// 3. 在相机位置不变的情况下更改航向角、俯仰角和翻滚角。
viewer.camera.setView({
    orientation: {
        heading : Cesium.Math.toRadians(90.0), // 东,默认值为 0.0(北)
        pitch : Cesium.Math.toRadians(-90),    // 默认值(向下看)
        roll : 0.0                             // 默认值
    }
});


// 4. 俯视查看矩形
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()

将视锥/投影切换到正交。 此函数在 2D 中为无操作,2D 将始终为正交。

switchToPerspectiveFrustum()

将视锥/投影切换到透视。 此函数在 2D 中为无操作,2D 必须始终为正交。
相机绕其方向向量逆时针旋转 amount 弧度。
Name Type Description
amount number optional 旋转量(弧度)。默认为 defaultLookAmount
See:
相机绕其方向向量顺时针旋转 amount 弧度。
Name Type Description
amount number optional 旋转量(弧度)。默认为 defaultLookAmount
See:

viewBoundingSphere(boundingSphere, offset)

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

偏移是目标处局部东北天参考系中的航向/俯仰/距离。 航向和俯仰角在局部东北天参考系中定义。 航向是从 y 轴开始并向 x 轴方向增加的角度。俯仰是从 xy 平面的旋转。正俯仰角在平面下方。负俯仰角在平面上方。距离是到中心的距离。如果距离为 零,则将计算一个距离以使整个包围球可见。

在 2D 中,必须是俯视视角。相机将放置在目标上方俯视。目标上方的高度将是距离。航向将由偏移确定。如果无法从偏移确定航向,则航向将为北方。

Name Type Description
boundingSphere BoundingSphere 要查看的包围球(世界坐标)。
offset HeadingPitchRange optional 目标处局部东北天参考系中的偏移。
Throws:

worldToCameraCoordinates(cartesian, result)Cartesian4

将向量或点从世界坐标系变换到相机的参考帧。
Name Type Description
cartesian Cartesian4 要变换的向量或点。
result Cartesian4 optional 存储结果的对象。
Returns:
变换后的向量或点。

worldToCameraCoordinatesPoint(cartesian, result)Cartesian3

将点从世界坐标系变换到相机的参考帧。
Name Type Description
cartesian Cartesian3 要变换的点。
result Cartesian3 optional 存储结果的对象。
Returns:
变换后的点。

worldToCameraCoordinatesVector(cartesian, result)Cartesian3

将向量从世界坐标系变换到相机的参考帧。
Name Type Description
cartesian Cartesian3 要变换的向量。
result Cartesian3 optional 存储结果的对象。
Returns:
变换后的向量。
沿相机视图向量方向缩放 amount 距离。
Name Type Description
amount number optional 移动量。默认为 defaultZoomAmount
See:
沿相机视图向量反方向缩放 amount 距离。
Name Type Description
amount number optional 移动量。默认为 defaultZoomAmount
See:

Type Definitions

Cesium.Camera.FlightCancelledCallback()

飞行取消时将执行的回调函数。

Cesium.Camera.FlightCompleteCallback()

飞行完成时将执行的回调函数。
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.