首页 / Cesium / API 文档

Camera

先看结论

场景的观察者。位置是地心坐标，朝向是四元数，对外表现成 heading、pitch、roll 三个角。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-27 · 引用本文

viewer.camera → Cesium.Camera

Camera 由 Viewer 创建，不要自己 new Cesium.Camera(scene)，否则会和 Viewer 内部持有的实例不一致。

位置与朝向

成员	类型	说明
`position`	Cartesian3	相机位置，ECEF 米
`positionCartographic`	Cartographic	经纬高，弧度
`direction`	Cartesian3	视线方向的单位向量
`up` / `right`	Cartesian3	相机的上、右方向
`heading`	弧度	方位角，正北为 0，顺时针增大
`pitch`	弧度	俯仰角，-π/2 为垂直向下
`roll`	弧度	绕视线的自转
`frustum`	PerspectiveFrustum	视锥，改 `fov` 可以换镜头

heading、pitch、roll 是只读的派生值，不能直接赋值，改朝向必须走 setView 或 lookAt。

setView

camera.setView({ destination, orientation })

参数	类型	说明
`destination`	Cartesian3 \| Rectangle	相机位置；传 Rectangle 时按范围取景
`orientation`	object	`direction` + `up`，或者 `heading` + `pitch` + `roll`
`endTransform`	Matrix4	局部参照系，用于把相机挂到模型上

viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(116.391263, 39.907359, 2500),
  orientation: {
    heading: Cesium.Math.toRadians(30),
    pitch: Cesium.Math.toRadians(-50),
    roll: 0
  }
});

flyTo

camera.flyTo({ destination, orientation, duration, complete, cancel, easingFunction, maximumHeight })

参数	默认	说明
`duration`	3	秒。0 表示瞬间跳转，不产生动画
`maximumHeight`	—	飞行过程中相机的最高高度，远景跳近景时用来抬高弧线
`pitchAdjustHeight`	—	低于该高度时自动调整 pitch，保持地平线可见
`flyOverLongitude`	—	跨经度飞行时指定从哪一侧绕行，避免绕远路
`easingFunction`	1 - (1-t)²	缓动，`Cesium.EasingFunction.QUINTIC_IN_OUT` 更柔和
`complete`	—	飞行结束回调
`cancel`	—	飞行被取消（用户操作或新的 flyTo）时回调

飞行被截断不算 bug。新的 flyTo 或用户拖动都会取消当前飞行，触发 cancel 而不是 complete。依赖回调做后续动作时，两个回调都要处理。

lookAt

camera.lookAt(target, offset)

target 是 Cartesian3，offset 是 new Cesium.HeadingPitchRange(heading, pitch, range)。调用后相机进入「以目标为中心」的局部参照系，鼠标拖动变成绕目标旋转。退出用 camera.lookAtTransform(Cesium.Matrix4.IDENTITY)。

var target = Cesium.Cartesian3.fromDegrees(116.391263, 39.907359, 0);

viewer.camera.lookAt(target, new Cesium.HeadingPitchRange(
  Cesium.Math.toRadians(45),
  Cesium.Math.toRadians(-30),
  800
));

// 退出局部参照系，恢复正常的地球浏览
viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);

忘了退出会出现「鼠标拖不动地球」的现象：拖动只在目标点附近旋转，平移和缩放的中心被锁在 target 上。

屏幕坐标拾取

camera.pickEllipsoid(windowPosition, ellipsoid, result) → Cartesian3

从相机发一条射线与椭球面求交，返回交点的三维坐标。画面里有地形时，射线可能打在山上而不是椭球面，需要改用 viewer.scene.globe.pick(ray, scene) 才能拿到真实地表位置。

var ray = viewer.camera.getPickRay(movement.position);
var onTerrain = viewer.scene.globe.pick(ray, viewer.scene);
var onEllipsoid = viewer.camera.pickEllipsoid(
  movement.position, viewer.scene.globe.ellipsoid
);

其他常用方法

方法	作用
`zoomIn(amount)` / `zoomOut(amount)`	沿视线前后移动，单位米
`moveForward(amount)`	朝视线方向平移
`rotate(axis, angle)`	绕指定轴旋转相机
`computeViewRectangle(ellipsoid)`	当前画面覆盖的经纬范围，用来判断可视区域
`flyToBoundingSphere(sphere, options)`	按包围球自动算距离
`cancelFlight()`	立即结束正在进行的飞行

引用本文

经纬志（2026）。《Camera》。https://www.jingweizhi.com/cesium/api/camera.html（访问日期 2026-11-03）。