RadarSweepEffect 雷达扫描（后处理）

屏幕空间 PostProcessStage 雷达扫描：以指定位置为圆心的圆形扫描环贴合地形 / 3D Tiles 表面，环内一条扫描线绕垂直轴持续旋转，模拟雷达/传感器的搜索过程。适合空间查询、目标搜索等“搜索过程”可视化。

---

能力定位

RadarSweepEffect 适合：

• 空间查询：搜索过程动态展示；
• 雷达搜索：探测范围 + 扫描线旋转示意；
• 目标发现：在地形/3D Tiles 上叠加扫描动效。

与实体类雷达效果的区别：

效果	渲染路径	扫描环是否贴合地形
RadarDomeEffect（半椭球穹顶 + 旋转切片）	实体几何（EllipsoidGraphics）	否（几何穹顶）
RadarWaveEffect（3D 圆锥扩散）	实体几何（CylinderGraphics + 材质）	否（几何圆锥）
CircleSpreadScanEffect 等实体扫描	实体/椭圆扫掠	否
RadarSweepEffect（本效果）	屏幕空间后处理（PostProcessStage + GLSL）	是（深度重建贴合表面）

构造函数

constructor(options: RadarSweepEffectOptions)

interface RadarSweepEffectOptions {
  position: Cartesian3    // 扫描中心位置（世界坐标），必填
  radius?: number         // 扫描半径（米），默认 200
  color?: Color           // 扫描颜色，默认 Color.GREEN
  duration?: number       // 扫描线旋转周期（毫秒），默认 3000
}

参数	类型	默认值	描述
position	Cartesian3	—	扫描中心（世界坐标），必填，缺省抛错
radius	number	200	扫描半径（米）
color	Color	Color.GREEN	扫描环与扫描线颜色
duration	number	3000	扫描线旋转周期（毫秒），扫描相位由真实时间驱动

生命周期

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

on(viewer: Viewer): void      // 创建 PostProcessStage 并加入 viewer.scene.postProcessStages
off(viewer: Viewer): void     // 移除本效果创建的 PostProcessStage
destroy(viewer: Viewer): void // 等价于 off（并释放内部引用）

源案例（RadarsEffects）需要手动调用 clearRadarScans() 清理全部 stage 且无销毁钩子；本效果改为实例自持单个 stage，destroy 即清理，多实例各自独立，无泄漏。

基础示例

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

const effect = new RadarSweepEffect({
  position: Cartesian3.fromDegrees(120, 30, 0),
  radius: 500,
  color: Color.GREEN,
  duration: 3000,
})
effect.on(viewer)

进阶示例

多实例共存（不同颜色 / 半径 / 周期），演示源案例 addRadarScan 多扫描场景：

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

const sweeps = [
  new RadarSweepEffect({ position: Cartesian3.fromDegrees(120, 30, 0), radius: 500, color: Color.GREEN }),
  new RadarSweepEffect({ position: Cartesian3.fromDegrees(120.02, 30.01, 0), radius: 300, color: Color.CYAN, duration: 2000 }),
  new RadarSweepEffect({ position: Cartesian3.fromDegrees(119.98, 29.99, 0), radius: 400, color: Color.ORANGE, duration: 4000 }),
]
sweeps.forEach(fx => fx.on(viewer))

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

实现说明

• 屏幕空间后处理：全屏 PostProcessStage，片段着色器从深度缓冲区重建眼空间坐标（czm_unpackDepth → czm_reverseLogDepth → czm_depthRange → czm_inverseProjection），把扫描中心投影到扫描平面，按到中心距离绘制扫描环（pow(f, 64) 抗锯齿）与扫描线扇形（pow(f, 3)），再混合 u_scanColor。扫描环贴合地形/3D Tiles 凹凸表面，这是实体几何效果不具备的；
• 扫描线旋转：u_scanLineNormalEC uniform 以真实时间（wall clock，Date.now()）驱动（(elapsed % duration) / duration 相位），用 Quaternion.fromAxisAngle 绕平面法线旋转起始方向向量，扫描始终匀速旋转、不依赖场景时钟是否在走；
• 版本迁移：源实现访问私有 camera._viewMatrix，已按目标版本替换为公开 camera.viewMatrix（Cesium 1.133 公开只读 getter）；着色器由 GLSL 1.00 语法（varying/gl_FragColor/texture2D）迁移至 1.133 GLSL 3.00（in/out_FragColor/texture）；
• 资源所有权：本效果创建的 stage 由 off/destroy 移除，创建方无需单独清理；多实例各自持有独立 scratch/uniform，互不干扰；
• stage 名称唯一：Cesium PostProcessStageCollection 要求集合内 stage 名称唯一，每个实例使用自增唯一名 radar_sweep_N，多实例可安全共存（曾共用固定名导致二次添加抛 DeveloperError）。

清理责任

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

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

Cesium 版本限制

• 依赖 Cesium PostProcessStage（公开 API，WeatherEffect 同族）与着色器 builtins czm_inverseProjection / czm_unpackDepth / czm_reverseLogDepth / czm_depthRange；
• 后处理着色器需真实浏览器/WebGL 验证（编译、深度语义、扫描环贴合）；已验证目标版本：Cesium 1.133.1。