EllipsoidFadeEffect 扩散圆环

扩散圆环效果：在指定位置创建平铺椭圆，应用 EllipsoidFade 材质，圆环从圆心向四周扩散、边缘随扩散衰减透明度并循环播放，模拟冲击波 / 区域扩散淡出。

---

能力定位

EllipsoidFadeEffect 适合：

• 冲击波 / 波及范围可视化：爆炸、撞击波及范围扩散示意；
• 区域扩散淡出：信号、污染、辐射扩散范围标记；
• 交互点选后地面标记：在指定坐标放置扩散圆提示范围。

与现有圆类效果不同——本效果是单圈扩散淡出（圆环从圆心向外扩散且边缘渐隐）， 区别于 CircleWaveEffect（多圈声呐波纹）、CircleSpreadScanEffect（纹理扫描脉冲）、 ExpandingCircle（EllipsoidMove 外壳扩散）。

构造函数

constructor(options: EllipsoidFadeEffectOptions)

interface EllipsoidFadeEffectOptions {
  position: Cartesian3   // 效果位置（世界坐标）
  radius?: number        // 扩散圆半径（米），默认 100
  color?: Color          // 扩散颜色，默认 RED
  duration?: number      // 扩散周期（毫秒），默认 2000
  height?: number        // 圆高度（米），默认 20
}

参数	类型	默认值	描述
position	Cartesian3	—	效果位置（世界坐标），必填，缺省抛错
radius	number	100	扩散圆半径（米），即椭圆半轴
color	Color	Color.RED	扩散圆颜色
duration	number	2000	扩散动画周期（毫秒），墙钟驱动
height	number	20	圆高度（米），平铺在地面上方

生命周期

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

on(viewer: Viewer): void      // 创建平铺椭圆实体 + EllipsoidFade 材质
off(viewer: Viewer): void     // 移除本效果创建的实体
destroy(viewer: Viewer): void // 等价于 off

清理完整性：off/destroy 移除本效果创建的实体。源案例实现仅提供整体 destroy()（removeAll 清空全部实体），本实现收敛为单一实体的幂等生命周期管理。

基础示例

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

const effect = new EllipsoidFadeEffect({
  position: Cartesian3.fromDegrees(116.3, 39.9, 0),
  radius: 130,       // 扩散圆半径（米）
  color: Color.RED,
  duration: 2000,    // 扩散周期（毫秒）
  height: 20,        // 圆高度（米）
})
effect.on(viewer)

进阶示例

多位置、多颜色扩散圆并行播放：

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

const configs = [
  { lon: 116.3, lat: 39.9, color: Color.RED },
  { lon: 116.306, lat: 39.9, color: Color.YELLOW },
  { lon: 116.3, lat: 39.906, color: Color.LIME },
]

const effects = configs.map(cfg => {
  const fx = new EllipsoidFadeEffect({
    position: Cartesian3.fromDegrees(cfg.lon, cfg.lat, 0),
    radius: 130,
    color: cfg.color,
    duration: 2000,
  })
  fx.on(viewer)
  return fx
})

// 演示到期后统一销毁，释放全部实体
window.setTimeout(() => {
  effects.forEach(fx => fx.destroy(viewer))
}, 120000)

实现说明

• 几何：EllipseGraphics 平铺椭圆，semiMajorAxis = semiMinorAxis = radius，height 对齐源案例（半轴 130 米、高度 20 米）。
• 渲染：全部收敛在既有 EllipsoidFadeMaterialProperty（shader 与源逐字节一致）： time = (Date.now() - start) % duration / duration，shader 以 fract(time) 为扩散半径、 discard 圆外片元、alpha = color.a * dis / per 实现边缘渐隐。
• 墙钟驱动：扩散时间由 Date.now() 驱动，与帧率无关（与 RadarSweepEffect 一致）。
• 资源所有权：本效果创建的实体由 off/destroy 移除，创建方无需单独清理。

清理责任

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

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

Cesium 版本限制

• 依赖 Cesium Entity.ellipse（EllipseGraphics）与既有 EllipsoidFadeMaterialProperty；
• 已验证目标版本：Cesium 1.133.1。