RadarWaveEffect 雷达放射波

3D 圆锥 + 表面扩散圆环/纵向渐变效果，用于雷达探测范围可视化。在雷达站位置渲染一个从地面向上扩展的圆锥：底面位于 position（雷达站），顶端收拢为一点并落在 position + up * height（卫星/实体位置，对齐源案例 topOnEllipsoid）。圆锥表面有两种源着色器（GLSL 不同）：RadarWave（变体1 密集细环）与 RadarWaveGradient（变体2 自上而下渐变），由 variant 选择，模拟雷达波束向上发射并向外传播。

---

能力定位

RadarWaveEffect 适合：

• 雷达探测：雷达站波束发射示意；
• 信号发射：垂直向上传播的扇形波束；
• 范围扫描：圆锥覆盖范围 + 圆环扩散动效。

与 RadarDomeEffect（半椭球穹顶 + 旋转切片）互补：穹顶表达覆盖范围，放射波表达波束发射方向与扩散过程。二者叠加可完整表达雷达态势。

构造函数

constructor(options: RadarWaveEffectOptions)

interface RadarWaveEffectOptions {
  position: Cartesian3    // 雷达站位置（地面，世界坐标）—— 圆锥底面所在
  variant?: 'ring' | 'gradient'  // 放射变体，默认 'ring'
  height?: number         // 波束圆锥高度（米），默认 100
  radius?: number         // 波束底部半径（米），默认 50
  color?: Color           // 波束颜色，默认 Color.CYAN
  repeat?: number         // 圆环数量，默认 30（ring）；gradient 默认 1.0
  thickness?: number      // 圆环粗细（0~1），默认 0.3（ring）；gradient 默认 0.8
  speed?: number          // 每帧偏移增量，默认 0.001（ring）；gradient 默认 0.015
}

参数	类型	默认值	描述
position	Cartesian3	—	雷达站位置（地面，世界坐标），必填，缺省抛错
variant	'ring' | 'gradient'	'ring'	放射变体：ring 用 RadarWave 着色器（密集细环，alpha=a*color.a）；gradient 用 RadarWaveGradient 着色器（自上而下渐变，alpha=a*color.a*dis*1.2）
height	number	100	波束圆锥高度（米）
radius	number	50	波束底部半径（米），圆锥从底部半径收拢到顶端为 0
color	Color	Color.CYAN	波束颜色
repeat	number	30（ring）/ 1.0（gradient）	圆环数量
thickness	number	0.3（ring）/ 0.8（gradient）	圆环粗细（0~1）
speed	number	0.001（ring）/ 0.015（gradient）	每帧偏移增量（扩散速度）

两个变体的 GLSL 不同（对齐源案例 initRadarRiationWave1/2 各自的着色器）：

• 变体1 RadarWave：alpha = a * color.a，均匀环、无纵向渐变；
• 变体2 RadarWaveGradient：alpha = a * color.a * dis * 1.2，自上而下渐变。

生命周期

实现 Lifecycle<Viewer> 契约，on/off/destroy 均幂等：

on(viewer: Viewer): void      // 创建 3D 圆锥实体（CylinderGraphics topRadius=0）
off(viewer: Viewer): void     // 移除本效果创建的圆锥实体
destroy(viewer: Viewer): void // 等价于 off

基础示例

import { RadarWaveEffect } from '@nexa/gis-cesium'
import { Cartesian3, Color } from 'cesium'

const effect = new RadarWaveEffect({
  position: Cartesian3.fromDegrees(112.39, 39.9, 0),
  height: 400000,
  radius: 120000,
  color: Color.GREEN,
})
effect.on(viewer)

圆锥顶点（topRadius=0）自动落在 position + up * height（卫星/实体位置），与源案例 topOnEllipsoid 一致。

进阶示例

两种放射变体组合展示（对齐源案例 initRadarRiationWave1 / initRadarRiationWave2）：

import { RadarWaveEffect } from '@nexa/gis-cesium'
import { Cartesian3, Color } from 'cesium'

// 变体 1（ring 着色器）：密集细环 —— variant='ring' 为默认，可省略
const dense = new RadarWaveEffect({
  position: Cartesian3.fromDegrees(112.39, 39.9, 0),
  height: 400000,
  radius: 120000,
  color: Color.fromCssColorString('#33ff00'),
  variant: 'ring',
})
dense.on(viewer)

// 变体 2（gradient 着色器）：自上而下渐变 —— 默认参数自动为源变体2 值
const gradient = new RadarWaveEffect({
  position: Cartesian3.fromDegrees(116.39, 39.9, 0),
  height: 400000,
  radius: 120000,
  color: Color.fromCssColorString('#33ff00'),
  variant: 'gradient',
})
gradient.on(viewer)

// 演示到期后统一销毁
window.setTimeout(() => {
  dense.destroy(viewer)
  gradient.destroy(viewer)
}, 120000)

实现说明

• 3D 圆锥：CylinderGraphics（length=height、topRadius=0 收拢为点、bottomRadius=radius）， 实体中心置于 position + up * height / 2，使底面落在 position（雷达站）、顶点落在 position + up * height（卫星/实体位置），等价源案例 CylinderGeometry + modelMatrix 几何；
• 扩散圆环：圆锥表面应用 RadarWaveMaterialProperty（variant 选择 RadarWave / RadarWaveGradient 两种材质）， offset 由 CallbackProperty 每帧递减驱动圆环扩散，替代源实现裸 preUpdate 改 uniforms 的方式， 生命周期随实体清理、无泄漏；
• 两种着色器（GLSL 不同）：对齐源案例 initRadarRiationWave1/2 各自的材质—— RadarWave（变体1 均匀环）：alpha = a * color.a； RadarWaveGradient（变体2 渐变）：alpha = a * color.a * dis * 1.2，由 variant 选择；
• 渐变原理：Cesium CylinderGeometry 的 st 为平面投影，圆锥面上 dis = distance(st, vec2(0.5)) 的角度项相互抵消、退化为纯高度函数 —— 底面（大半径）dis=0.5 最亮，顶点（topRadius=0）dis=0 全透明， 形成自上而下渐变；材质注册为 translucent: true，Entity 走半透明混合管线，alpha 真实生效；
• 资源所有权：本效果创建的实体由 off/destroy 移除，创建方无需单独清理。

清理责任

effect.destroy(viewer) // 或 effect.off(viewer)，等价且幂等

重复调用 destroy/off 安全（无实体时为空操作）。

Cesium 版本限制

• 依赖 Cesium Entity.cylinder（CylinderGraphics）、Ellipsoid.geodeticSurfaceNormal 与材质 CallbackProperty 驱动；
• 已验证目标版本：Cesium 1.133.1。