Plugins（插件系统）

gis-cesium 基于 Mixin 模式 扩展 Cesium 的 Viewer 实例，通过 viewer.extend() 方法注入功能。所有插件使用 Object.defineProperties 将方法挂载到 viewer 对象上，保持命名空间干净统一。

核心模式

typescript

import { viewerGridMixin } from './plugins/viewerGridMixin'

// 通过 extend 方法注入功能
viewer.extend(viewerGridMixin)

// 之后即可通过 viewer 访问插件方法
viewer.grid.show = true

1. viewerGridMixin — 经纬网格

在三维场景中绘制基于 LOD（细节层次）的经纬度网格，并根据相机高度自动切换网格密度。

挂载方法：

属性/方法	类型	说明
`viewer.grid.show`	`boolean`	控制网格显示/隐藏
`viewer.grid.destroy()`	`() => void`	销毁网格及标签

内部类型： LatLonGrid（Primitive 网格）、GridLabelManager（经纬度标签）

LOD 层级： 0→30°（>20000km）、1→10°（8000~20000km）、2→5°（3000~8000km）、3→2°（1000~3000km）、4→1°（<1000km）

2. viewerMaterialMixin — 材质注册

注册自定义 GLSL 材质到 Cesium Material 缓存，供 Entity 或 Primitive 使用。

挂载方法：

属性/方法	类型	说明
`viewer.getMaterial()`	`() => void`	获取材质管理器（占位）

注册的材质类型：

EllipsoidMove — 椭球移动虚线材质（注册为 Cesium.Material.EllipsoidMoveType）
PolylineDashMove — 折线移动虚线材质（注册为 Cesium.Material.PolylineDashMoveType）

底层 Shader 文件位于 Shaders/EllipsoidMoveMaterial.glsl 和 Shaders/PolylineDashMoveMaterial.glsl。

3. viewerScenarioConfigMixin — 场景时间配置

设置 Cesium Viewer 的场景时钟（Clock + Timeline）并支持北京时间显示。

挂载方法：

方法签名	说明
`viewer.setSceneClock(options)`	设置场景时钟范围
`viewer.displayBeijingTime()`	将动画面板和 Timeline 的时间改为北京时间(UTC+8)

类型：

typescript

interface SceneClockOptions {
  start: string | Date    // 开始时间
  stop: string | Date     // 结束时间
  currentTime: string | Date  // 当前时间
}

4. viewerAnimationPanelMixin — 动画面板压缩

将 Cesium 默认动画控制面板压缩为紧凑的迷你控制栏，适合嵌入小界面场景。

挂载方法：

方法签名	说明
`viewer.animationComPress()`	压缩动画面板为 165×28px 的迷你控制栏

控制功能包括：加速、减速、反向播放、暂停/播放、正向播放，并实时显示时间和速率倍数。

5. viewerOffscreenRenderMixin — 离屏渲染

实现独立相机离屏渲染，支持将场景渲染到 Framebuffer（FBO）并输出到 HTML Canvas。使用 Cesium 内部 API，需在 WebGL 初始化后调用。

挂载方法：

方法签名	说明
`viewer.renderToCanvas(fbo, camera, canvas)`	单次渲染场景到 Canvas
`viewer.startRealTimeRenderToCanvas(fbo, camera, canvas)`	开始实时帧同步渲染
`viewer.endRealTimeRenderToCanvas()`	停止实时渲染

参数说明：

fbo: Cesium.Framebuffer — 通过 createFrameBuffer(scene) 创建
camera: Cesium.Camera — 通过 createFboCamera(scene) 创建，支持透视投影
canvas: HTMLCanvasElement — 目标输出 Canvas

6. viewerAxisVectorMixin — 坐标轴与矢量

在实体上绘制卫星本体系（Body Frame）、LVLH 轨道系、太阳/月球/地心方向矢量。

挂载方法：

方法签名	返回类型	说明
`viewer.addBodyFrame(target, options?)`	`FrameGroup`	添加本体系坐标轴（RGB: X/Y/Z）
`viewer.addLVLHFrame(target, options?)`	`FrameGroup`	添加 LVLH 轨道系坐标轴
`viewer.addSunVector(target, options?)`	`VectorGroup`	添加太阳方向矢量
`viewer.addMoonVector(target, options?)`	`VectorGroup`	添加月球方向矢量
`viewer.addNadirVector(target, options?)`	`VectorGroup`	添加地心方向（Nadir）矢量

类型定义：

typescript

interface FrameOptions {
  length?: number  // 坐标轴长度（默认 300000/500000）
  width?: number   // 线宽（默认 3）
}

interface VectorOptions extends FrameOptions {
  color?: Cesium.Color  // 矢量颜色
}

interface FrameGroup {
  xLine: Cesium.Entity; yLine: Cesium.Entity; zLine: Cesium.Entity
  xLabel: Cesium.Entity; yLabel: Cesium.Entity; zLabel: Cesium.Entity
  destroy: () => void
}

interface VectorGroup {
  line: Cesium.Entity; label: Cesium.Entity
  destroy: () => void
}

示例：

typescript

viewer.addBodyFrame(satelliteEntity, { length: 500000 })
viewer.addSunVector(satelliteEntity, { color: Cesium.Color.YELLOW })

7. viewerToolMixin — 工具集

提供 TLE 卫星管理、轨道追踪、距离标尺等实用工具。

挂载方法：

方法签名	说明
`viewer.tleSatelliteManager(options)`	创建/管理 TLE 卫星实体（含模型、标签、轨迹）
`viewer.tleSatelliteTrack(options)`	生成 TLE 卫星轨道轨迹（彩色渐变路径）
`viewer.rangeMarker(options)`	绘制两实体间的距离标尺（带实时距离标签）
`viewer.getPositionProperty(positions)`	从采样点数组创建 SampledPositionProperty

类型定义：

typescript

interface TleSatelliteManagerOptions {
  positionProperty: Cesium.PositionProperty
  availability: Cesium.TimeIntervalCollection
  color?: string; id?: string; leadTime?: number
}

interface TleSatelliteTrackOptions {
  positionProperty: Cesium.PositionProperty
  colors: string[]; start: string | Date; end: string | Date
  id?: string; posList?: number[]; leadTime?: number
}

interface RangeMarkerOptions {
  sourceId: string; targetId: string; color?: string
  tracks: RangeMarkerTrack[]
  eventCallback: (inRange: boolean) => void
}

interface PositionSample {
  px: number | string; py: number | string; pz: number | string
  dateTime: string | Date
}

导出的独立方法： Material1() — 注册一个支持 10 色渐变的自定义材质 Material1。

示例：

typescript

const { positionProperty, availability } =
  viewer.getPositionProperty(samples)
viewer.tleSatelliteManager({ positionProperty, availability, id: 'sat-1' })
viewer.rangeMarker({ sourceId: 'sat-1', targetId: 'sat-2', tracks, eventCallback })

8. viewerNodeToTransformMixin — 模型节点变换

计算 glTF 模型节点与 Entity 之间的相对变换矩阵，实现节点位置跟随（保持节点自身旋转/缩放）。

挂载方法：

方法签名	返回类型	说明
`viewer.computeNodeToEntityTransform(options)`	`NodeEntityTransformResult`	计算模型节点到 Entity 的相对变换
`viewer.computeNodeToNodeTransform(options)`	`NodeToNodeTransformResult`	计算两个模型节点间的相对变换

类型定义：

typescript

interface NodeOptions {
  node: unknown           // glTF 模型节点（_runtimeNode）
  entity: Cesium.Entity   // 目标 Entity
  time: Cesium.JulianDate
}

interface NodeToNodeOptions {
  fromNode: unknown
  toNode: unknown
}

interface NodeEntityTransformResult {
  matrix: Cesium.Matrix4
  translation: Cesium.Cartesian3
  nodeRotation: Cesium.Quaternion
  nodeScale: Cesium.Cartesian3
}

9. viewerRelativePathMixin — 相对路径

计算两个实体间的相对轨道路径，用于编队飞行等场景的可视化。

挂载方法：

方法签名	说明
`viewer.getRelativePath(options)`	计算 source 相对 target 的相对轨迹

类型定义：

typescript

interface RelativePathOptions {
  targetId: string
  sourceId: string
  step?: number  // 采样点数，默认 100
}

10. viewerSimulationBusMixin — 爆炸粒子效果

别名：explosionParticleSystemMixin。创建火焰+烟雾的粒子爆炸效果。

挂载方法：

方法签名	说明
`viewer.createExplosion(options)`	在指定位置创建爆炸效果
`viewer.createExplosionAtCoordinates(lon, lat, height?, config?)`	在经纬度坐标创建爆炸

类型定义：

typescript

interface ExplosionOptions {
  position: Cesium.Cartesian3
  config?: Partial<ExplosionConfig>
}

interface ExplosionConfig {
  duration: number        // 持续时间（秒），默认 8
  particleCount: number   // 粒子数量，默认 200
  scale: number           // 缩放比例，默认 1.0
  explosionSize: number   // 爆炸体积，默认 50.0
  gravity: number         // 重力，默认 -9.8
  smokeColor: Cesium.Color
  fireColor: Cesium.Color
}

示例：

typescript

viewer.createExplosionAtCoordinates(120.13, 30.27, 1000, {
  scale: 2.0,
  particleCount: 500
})

11. viewerCameraMixin — 相机控制

详见 camera-control.md（独立文档）。核心功能：飞行定位 flyTo、视角锁定 lockView、相机跟随 cameraFollow、场景模式切换。

12. viewerEntityMixin — 实体管理

详见 entity-management.md（独立文档）。核心功能：通过 viewer.entityManager 管理实体生命周期，提供 createEntity 工厂方法。

综合示例

typescript

import { viewerGridMixin } from './plugins/viewerGridMixin'
import { viewerScenarioConfigMixin } from './plugins/viewerScenarioConfigMixin'
import { viewerAxisVectorMixin } from './plugins/viewerAxisVectorMixin'
import { viewerSimulationBusMixin } from './plugins/viewerSimulationBusMixin'

// 扩展 Viewer
viewer.extend(viewerGridMixin)
viewer.extend(viewerScenarioConfigMixin)
viewer.extend(viewerAxisVectorMixin)
viewer.extend(viewerSimulationBusMixin)

// 配置场景时间
viewer.setSceneClock({
  start: '2024-01-01T00:00:00Z',
  stop: '2024-01-02T00:00:00Z',
  currentTime: '2024-01-01T12:00:00Z'
})

// 显示经纬网格
viewer.grid.show = true

// 在卫星实体上添加 LVLH 坐标系
viewer.addLVLHFrame(satelliteEntity, { length: 500000 })

// 创建爆炸效果
viewer.createExplosionAtCoordinates(120.13, 30.27, 500)

Plugins（插件系统） ​

核心模式 ​

1. viewerGridMixin — 经纬网格 ​

2. viewerMaterialMixin — 材质注册 ​

3. viewerScenarioConfigMixin — 场景时间配置 ​

4. viewerAnimationPanelMixin — 动画面板压缩 ​

5. viewerOffscreenRenderMixin — 离屏渲染 ​

6. viewerAxisVectorMixin — 坐标轴与矢量 ​

7. viewerToolMixin — 工具集 ​

8. viewerNodeToTransformMixin — 模型节点变换 ​

9. viewerRelativePathMixin — 相对路径 ​

10. viewerSimulationBusMixin — 爆炸粒子效果 ​

11. viewerCameraMixin — 相机控制 ​

12. viewerEntityMixin — 实体管理 ​

综合示例 ​

Plugins（插件系统）

核心模式

1. viewerGridMixin — 经纬网格

2. viewerMaterialMixin — 材质注册

3. viewerScenarioConfigMixin — 场景时间配置

4. viewerAnimationPanelMixin — 动画面板压缩

5. viewerOffscreenRenderMixin — 离屏渲染

6. viewerAxisVectorMixin — 坐标轴与矢量

7. viewerToolMixin — 工具集

8. viewerNodeToTransformMixin — 模型节点变换

9. viewerRelativePathMixin — 相对路径

10. viewerSimulationBusMixin — 爆炸粒子效果

11. viewerCameraMixin — 相机控制

12. viewerEntityMixin — 实体管理

综合示例