CloudEffect 全球云层

全球云层效果：创建覆盖全球经纬的 Rectangle 图层，应用 Cloud 材质（云层纹理随时间滚动）， 并按距离显示条件在远观时可见、近地时隐藏，模拟高空视角下的大气云层。

---

能力定位

CloudEffect 适合：

• 大气云层：高空远观视角下覆盖全球的滚动云层；
• 全球气象可视化底景：作为地球环境的云层背景；
• 高空氛围：配合遥感、全球态势等远距离视界。

与天气类效果不同——WeatherEffect 是屏幕空间天气后处理（雨/雪/雾），本效果是全球几何云层 （Rectangle 实体 + Cloud 材质），仅在远观距离（默认 3000000–100000000 米）显示，近地自动隐藏。

构造函数

constructor(options: CloudEffectOptions)

interface CloudEffectOptions {
  color?: Color        // 云层颜色，默认 WHITE.withAlpha(0.8)
  duration?: number    // 纹理滚动周期（毫秒），默认 100000
  image?: string       // 云层纹理图片 URL
  height?: number      // 云层高度（米），默认 6000
  minimumDistance?: number // 最近显示距离（米），默认 3000000
  maximumDistance?: number // 最远显示距离（米），默认 100000000
}

参数	类型	默认值	描述
color	Color	Color.WHITE.withAlpha(0.8)	云层颜色
duration	number	100000	纹理滚动周期（毫秒），墙钟驱动
image	string	''	云层纹理图片 URL（建议 /static/images/effects/earth_cloud.png）
height	number	6000	云层高度（米），高于地形的全球图层
minimumDistance	number	3000000	最近显示距离（米），低于此距离隐藏
maximumDistance	number	100000000	最远显示距离（米），超过此距离隐藏

生命周期

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

on(viewer: Viewer): void      // 创建全球 Rectangle 实体 + Cloud 材质
off(viewer: Viewer): void     // 移除本效果创建的实体
destroy(viewer: Viewer): void // 等价于 off

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

基础示例

import { CloudEffect } from '@nexa/gis-cesium'
import { Color } from 'cesium'

const cloud = new CloudEffect({
  color: Color.WHITE.withAlpha(0.8), // 云层颜色
  duration: 100000,                  // 纹理滚动周期（毫秒）
  image: '/static/images/effects/earth_cloud.png', // 云层纹理
  height: 6000,                      // 云层高度（米）
})
cloud.on(viewer)

进阶示例

切换到高空远观视角，并按需调节显示距离：

import { CloudEffect } from '@nexa/gis-cesium'
import { Color } from 'cesium'

viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(116.3, 39.9, 18000000),
})

const cloud = new CloudEffect({
  color: Color.WHITE.withAlpha(0.8),
  duration: 100000,
  image: '/static/images/effects/earth_cloud.png',
  height: 6000,
  minimumDistance: 1000000,  // 相机距地 1000km 内隐藏云层
  maximumDistance: 200000000,
})
cloud.on(viewer)

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

实现说明

• 几何：RectangleGraphics 全球覆盖（Rectangle.fromDegrees(-180, -90, 180, 90)）， height 对齐源案例（6000 米），distanceDisplayCondition 对齐源案例（3000000–100000000 米）。
• 渲染：全部收敛在既有 CloudMaterialProperty（shader 与源逐字节一致）： time = (Date.now() - start) % duration / duration，shader 以 fract(st.s + time) 滚动云纹理。
• 墙钟驱动：滚动时间由 Date.now() 驱动，与帧率无关（与 RadarSweepEffect 一致）。
• 资源所有权：本效果创建的实体由 off/destroy 移除，创建方无需单独清理。
• 纹理资产：源案例 earth_cloud.png 已随迁移收录至 public/static/images/effects/earth_cloud.png，可直接引用。

清理责任

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

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

Cesium 版本限制

• 依赖 Cesium Entity.rectangle（RectangleGraphics）与既有 CloudMaterialProperty；
• 已验证目标版本：Cesium 1.133.1。