相机控制

提供飞行定位、视角锁定、相机跟随、场景模式切换等相机控制能力

概述

viewerCameraMixin 是一个 Viewer 插件，通过 viewer.extend() 注入后，为 Viewer 提供 cameraControl 命名空间，包含以下核心能力：

• 飞行定位 — 相机飞行至指定经纬度坐标或实体
• 视角锁定 — 相机对准并跟踪指定实体
• 相机跟随 — 相机持续跟随运动实体（顶视/侧视/自由模式）
• 场景模式切换 — 2D/3D/2.5D（Columbus View）场景模式切换

快速开始

import { CesiumViewer, viewerCameraMixin } from '@space-air/gis-cesium'

const airGis = new CesiumViewer('container')
const viewer = airGis.viewer

// 加载相机控制插件
viewer.extend(viewerCameraMixin)

// 飞行至北京
viewer.cameraControl.flyTo({ lon: 116.39, lat: 39.91 })

API 接口

插件函数：viewerCameraMixin

function viewerCameraMixin(viewer: Cesium.Viewer, options?: ViewerCameraMixinOptions): void

viewer.cameraControl.flyTo(options)

飞行至指定经纬度坐标。

参数名	类型	默认值	描述
options.lon	number	-	目标经度（度）
options.lat	number	-	目标纬度（度）
options.height	number	0	目标高度（米）
options.range	number	10000	相机距离目标的距离（米）
options.heading	number	0	相机偏航角（度）
options.pitch	number	-90	相机俯仰角（度）
options.duration	number	3	飞行持续时间（秒）
options.complete	() => void	-	飞行完成回调
options.cancel	() => void	-	飞行取消回调

viewer.cameraControl.flyToEntity(entity, options?)

飞行至指定实体。

参数名	类型	默认值	描述
entity	Cesium.Entity	-	目标实体
options.range	number	5000	相机偏移距离（米）
options.heading	number	0	偏航角（度）
options.pitch	number	-30	俯仰角（度）
options.duration	number	2	飞行持续时间（秒）
options.complete	() => void	-	飞行完成回调

viewer.cameraControl.lockView(options)

锁定视角跟踪实体。相机始终对准指定实体，但不自动跟随移动。

参数名	类型	默认值	描述
options.entityId	string	-	目标实体 ID
options.range	number	5000	相机偏移距离（米）
options.heading	number	0	偏航角（度）
options.pitch	number	-30	俯仰角（度）

viewer.cameraControl.unlockView()

解除视角锁定。

viewer.cameraControl.followEntity(entity, mode?, options?)

相机跟随实体运动，支持三种跟随模式：

模式	说明
'top'	顶视跟随 — 正上方俯视
'side'	侧视跟随 — 斜后方视角
'free'	自由跟随 — 仅跟踪位置，不强制视角

参数名	类型	默认值	描述
entity	Cesium.Entity	-	目标实体
mode	'top' | 'side' | 'free'	'free'	跟随模式
options.range	number	5000	相机偏移距离（米）
options.heading	number	0	偏航角（度），仅 side 模式
options.pitch	number	-30	俯仰角（度），仅 side 模式

viewer.cameraControl.stopFollow()

停止相机跟随。

viewer.cameraControl.setSceneMode(mode)

切换场景模式。

模式	说明
'3D'	三维场景（默认）
'2D'	二维平面地图
'2.5D'	Columbus View（哥伦布视图）

viewer.cameraControl.getSceneMode()

获取当前场景模式，返回 '3D' | '2D' | '2.5D'。

viewer.cameraControl.destroy()

销毁插件，解除所有锁定和跟随状态。

---

接口：FlyToOptions

interface FlyToOptions {
  lon: number
  lat: number
  height?: number
  range?: number
  heading?: number
  pitch?: number
  duration?: number
  complete?: () => void
  cancel?: () => void
}

接口：LockViewOptions

interface LockViewOptions {
  entityId: string
  range?: number
  heading?: number
  pitch?: number
}

类型：CameraFollowMode

type CameraFollowMode = 'top' | 'side' | 'free'

使用案例

案例1：飞行至目标点

viewer.cameraControl.flyTo({
  lon: 116.39,
  lat: 39.91,
  height: 0,
  range: 50000,
  heading: 30,
  pitch: -45,
  duration: 3,
  complete: () => console.log('飞行完成'),
})

案例2：飞行至实体并锁定视角

const entity = airGis.addEntity({
  position: Cesium.Cartesian3.fromDegrees(121.47, 31.23, 0),
  point: { pixelSize: 12, color: Cesium.Color.RED },
})

viewer.cameraControl.flyToEntity(entity, { range: 30000, pitch: -30 })
viewer.cameraControl.lockView({ entityId: entity.id, range: 10000, pitch: -20 })

案例3：跟随运动实体

// 顶视跟随（正上方俯视）
viewer.cameraControl.followEntity(entity, 'top', { range: 8000 })

// 侧视跟随（斜后方视角）
viewer.cameraControl.followEntity(entity, 'side', { range: 10000, pitch: -20 })

// 停止跟随
viewer.cameraControl.stopFollow()

案例4：场景模式切换

viewer.cameraControl.setSceneMode('2D')
viewer.cameraControl.setSceneMode('3D')
const mode = viewer.cameraControl.getSceneMode()

注意事项

• 使用 followEntity 的 top 或 side 模式时，内部通过 clock.onTick 更新相机位置，需要确保时钟正在运行（viewer.clock.shouldAnimate = true）
• lockView 使用 viewer.zoomTo 实现，不会随实体移动而更新；如需持续跟踪，请使用 followEntity
• 调用 flyTo 或 flyToEntity 会取消当前的跟随状态
• 场景模式切换会重置相机位置，建议在切换后重新调用 flyTo 定位
• 销毁插件时需调用 viewer.cameraControl.destroy() 释放资源