Cesium 如何旋转与控制 3D 视角

WebGIS
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

在 Cesium 中旋转与控制 3D 视角,核心是操作 viewer.camera(设置 position、heading、pitch、roll)以及 scene.screenSpaceCameraController(开关与限制鼠标/触控行为)。默认交互为:左键拖动平移、右键拖动或滚轮缩放、中键拖动围绕地表点旋转/倾斜;代码侧可用 setView、flyTo、lookAt、rotate、look 等立即或动画地改视角。截至 2026 年 11 月,CesiumJS 最新版为 1.147,上述接口稳定可用,角度一律用弧度。

Cesium 3D 视角旋转与绕点倾斜示意

默认鼠标与触控如何操作 3D 视角

创建 Viewer 后,3D 模式下的交互由 ScreenSpaceCameraController 接管,无需额外写代码即可完成常见浏览。鼠标与触控对应关系如下:

  • 左键拖动(或单指拖动):沿地表平移场景
  • 右键拖动或滚轮:缩放远近
  • 中键拖动(或双指/Ctrl+拖动等):围绕当前地表点旋转与倾斜
  • NavigationHelpButton 可弹出操作提示,方便给最终用户说明

若暂时不希望用户乱动视角(例如正在 flyTo),可把 screenSpaceCameraController.enableInputs 设为 false,结束后再打开。更多交互细节与示例见 Cesium 官方 Camera 教程。

用代码精确设置相机位置与朝向

需要固定到某个经纬度高度、或带动画飞过去时,直接调 Camera API。heading 为 0 表示正北、顺时针增大;pitch 负值表示向下看;roll 一般保持 0。常用写法:

  1. 立即到位(无动画):viewer.camera.setView({ destination: Cesium.Cartesian3.fromDegrees(经度, 纬度, 高度), orientation: { heading: 弧度, pitch: 弧度, roll: 0 } })。destination 也可传 Rectangle。
  2. 带动画飞行:viewer.camera.flyTo({ destination, orientation, duration, complete })。也可用 viewer.flyTo(entity 或 tileset) 自动框选目标。
  3. 回到默认全球视图:调用 viewer.camera.flyHome()。
  4. 只读状态:通过 camera.heading、camera.pitch、camera.roll、camera.positionCartographic 读取当前姿态;监听 moveStart/moveEnd/changed 做联动。

orientation 也可写成 direction/up 向量形式。不确定具体数值时,先在 Sandcastle 里试,再固化到业务代码。获取当前稳定版本可到 Cesium 官方下载页(1.147 ZIP)或使用 npm install cesium。

Cesium 官方 Camera 教程页面截图
Cesium 官方 Camera 教程页面截图(截图来源:cesium.com)

如何实现旋转、倾斜与绕点观察

除 setView/flyTo 外,还有两类“相对运动”方法,适合键盘微调或自动环绕:

  • rotate*(绕参考帧中心转,距离不变):rotate(axis, angle)、rotateLeft/Right/Up/Down(angle)。默认步长约 Math.PI / 3600。
  • look*(原地转头):look(axis, angle)、lookLeft/Right/Up/Down,以及 twistLeft/Right。默认步长约 Math.PI / 60。
  • lookAt / lookAtTransform:锁定到目标点或变换矩阵。常用 lookAt(target, new Cesium.HeadingPitchRange(heading, pitch, range))。锁定后自由拖拽会被约束;要恢复自由导航,执行 camera.lookAtTransform(Cesium.Matrix4.IDENTITY)。

绕某点持续旋转的典型写法:先 lookAtTransform 到目标,再在 viewer.clock.onTick 里每帧调用 camera.rotateRight(0.005)(角度按帧率微调)。结束后务必解除 lookAt,否则用户无法正常平移。

用 ScreenSpaceCameraController 限制交互与防穿地

需要“只能平移不能倾斜”“禁止钻地下”“限制最近距离”时,改控制器属性即可,不必重写事件。

属性 默认/常见值 作用说明
enableInputs true 总开关;飞行中可临时关闭
enableRotate true 是否允许旋转类输入(3D 中与平移式旋转相关)
enableTilt true 是否允许倾斜;设 false 可禁止俯仰
enableZoom / enableTranslate / enableLook true 分别控制缩放、平移、原地观察
enableCollisionDetection true 防止相机穿入地形;设 false 才允许进地下
minimumZoomDistance 1.0 最近距离(米)
maximumZoomDistance Infinity 最远距离
maximumTiltAngle undefined 可设为 Math.PI / 2 等限制最大倾斜

事件类型也可改:例如 rotateEventTypes、tiltEventTypes(默认含中键拖动、双指捏合、Ctrl+拖动等)。改完后在真机和触屏上各测一遍,确认手势没有冲突。运行环境需浏览器支持 WebGL(可用 get.webgl.org 自检);更高端显卡有利于保持流畅帧率,无硬性最低 CPU/RAM 规格。

常见问题

如何禁止用户倾斜或旋转?

将 viewer.scene.screenSpaceCameraController.enableTilt = false 可关掉倾斜;需要更严时再关 enableRotate。若只想改手势映射,用 ScreenSpaceEventHandler 重新绑定,而不是简单关开关。

相机钻进地下或被卡住怎么办?

保持 enableCollisionDetection = true(默认)一般可避免穿地。必须进地下查看时再临时设为 false,并同时检查 minimumZoomDistance,避免贴得过近导致抖动。

heading、pitch 为什么看起来“不对”?

单位必须是弧度,不是角度。可用 Cesium.Math.toRadians(度) 转换。lookAt 锁定期间读到的姿态会受约束,先解除 lookAtTransform 再判断。

绕点动画结束后拖不动了?

说明仍处于 lookAt 锁定状态。调用 viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY) 并视情况恢复 enableInputs,即可回到默认自由导航。

总结:先用默认中键/双指完成旋转倾斜,再用 setView/flyTo/lookAt 做精确到位,用 ScreenSpaceCameraController 限制手势与防穿地;绕点动画务必在结束时解除 lookAt。建议先在官方 Camera 教程里跑通一组 setView 与 lookAt 示例,再按业务关掉 enableTilt 或加上碰撞检测,用真实数据验收“能否回到自由导航、会不会钻地”。