SkyBoxEffect 天空盒切换效果

1 组远景深空 + 3 组近景天空盒，以相机高度为阈值在「当前激活近景组」与「远景组」间自动切换，对齐源案例 Scene/SkyBox。库缺省由程序化纹理工厂零资产生成贴图（PNG data-URI，无需任何外部图片资产）；SkyBox 案例模板则直接使用源仓库同款天空盒原图（对齐源案例 4 组 24 张图片，见资产来源与授权）。

能力定位

SkyBoxEffect 适合：

近景/远景一体切换：从地面起飞穿越平流层进入太空时，天顶由蓝天渐变切换为星空，大屏/演示的"穿越"观感；
多组近景切换：3 组近景天空盒（晴空/夕照/阴云）随 setNearSkybox() 切换，对齐源案例 changeSkyBox 在 3 组近景间选择；
自定义天空盒：以任意 6 面贴图（URL / data-URI / Image 对象）替换远、近天空盒；
运行时换肤：swapSkybox() 动态替换远景 / 近景贴图组。

与 CloudEffect（全球云层 Rectangle 图层）不同，SkyBoxEffect 直接接管 scene.skyBox（Cesium 原生天空盒），不创建实体。

构造函数

constructor(options: SkyBoxEffectOptions)

interface SkyBoxEffectOptions {
  farSources?: SkyboxSources;    // 远景（太空/夜）6 面贴图，缺省程序化生成深空贴图
  nearSources?: SkyboxSources[]; // 近景（地面）贴图组数组，缺省程序化生成 3 组（晴空/夕照/阴云）
  nearIndex?: number;            // 初始激活的近景组下标，默认 0
  switchHeight?: number;         // 相机高度切换阈值（米），默认 2500（对齐源案例）
}

SkyboxSources 为 6 面贴图集合（键与 Cesium SkyBox sources 契约一致）：

interface SkyboxSources {
  positiveX: string;  // +X 面（右）
  negativeX: string;  // -X 面（左）
  positiveY: string;  // +Y 面（上/天顶）
  negativeY: string;  // -Y 面（下/脚底）
  positiveZ: string;  // +Z 面（前）
  negativeZ: string;  // -Z 面（后）
}

每面值可为 URL / data-URI / HTMLImageElement（Cesium SkyBox.sources 支持"URLs or Image objects"）。

基础示例

import { SkyBoxEffect } from '@nexa/gis-cesium'

const effect = new SkyBoxEffect({
  switchHeight: 2500, // 相机高度低于 2500m 显示当前近景组，高于则显示远景深空
})
effect.on(viewer)

// 在 3 组近景天空盒间切换（缺省为程序化 晴空/夕照/阴云 三组）
effect.setNearSkybox(1)

on() 之后 postRender 每帧按相机高度自动切换天空盒，无需额外调用。

零资产生成纹理

SkyBoxEffect 未传 farSources/nearSources 时，缺省调用程序化纹理工厂 SkyBoxTextureFactory（utils-gis，随 SkyBoxEffect 一起导出）零资产生成 1 远景 + 3 近景天空盒：

import {
  createSpaceSkyboxSources,
  createDaySkyboxSources,
  createSunsetSkyboxSources,
  createOvercastSkyboxSources,
} from '@nexa/gis-cesium'

// 远景深空（04 组）：暗蓝渐变 + 星点（种子化伪随机，输出可复现）
const far = createSpaceSkyboxSources()
// 3 组程序化近景缺省：晴空 / 夕照 / 阴云（库缺省语义，与源案例原图内容无一一对应）
const near = [
  createDaySkyboxSources(1024),      // 晴空
  createSunsetSkyboxSources(1024),   // 夕照
  createOvercastSkyboxSources(1024), // 阴云
]

const effect = new SkyBoxEffect({ farSources: far, nearSources: near })
effect.on(viewer)

默认 512px/面，可按需传入更大尺寸；
星点/云位置由每面种子化伪随机（mulberry32）生成，同尺寸下输出确定可复现；
非浏览器环境（Node 测试）回退 1×1 透明占位图，避免运行时异常。

资产来源与授权

SkyBox 案例模板（examples/templates/SkyBox）不走程序化缺省，而是直接使用源案例同款天空盒原图，与源案例 index.js 的 4 组 24 张图片一一对应：

组	语义（图片实际内容）	扩展名	源路径
04	远景星空（`farSkyBox`）	jpg	`public/static/images/skybox/04/*`
01	近景1（暖色黄昏，`groundSkyBoxs[0]`）	png	`public/static/images/skybox/01/*`
02	近景2（灰蓝阴云，`groundSkyBoxs[1]`）	jpg	`public/static/images/skybox/02/*`
03	近景3（亮蓝晴空，`groundSkyBoxs[2]`）	jpg	`public/static/images/skybox/03/*`

命名与源案例 UI 一致：近景组按近景1/近景2/近景3 中性编号（源案例 index.jsx 按钮文案），不对图片内容臆造天气语义；上表「实际内容」仅描述图片观感供排查参考。

模板按 loadSources(group, ext) 拼出 /static/images/skybox/{group}/{px,py,pz,nx,ny,nz}.{ext} 6 面 URL，传入 SkyBoxEffect 的 farSources/nearSources；
源资产拷贝自 cesium-example 源仓库 src/static/images/skybox/（与 BillboardGif 案例同款"源案例资产"约定）；源仓库无 LICENSE、package.json 无 license 字段，授权待明确，请勿在未确认授权前将该组图片用于商业闭源分发。

切换近景组（对齐源案例 changeSkyBox）

// 在 3 组近景天空盒间切换（下标越界按组数取模回绕；下一帧自动应用）
effect.setNearSkybox(0) // 晴空
effect.setNearSkybox(1) // 夕照
effect.setNearSkybox(2) // 阴云

运行时替换贴图

// 飞行过程中动态替换远景/近景贴图组（下一帧 postRender 自动应用）
effect.swapSkybox(createSpaceSkyboxSources(1024), [
  createDaySkyboxSources(1024),
  createSunsetSkyboxSources(1024),
  createOvercastSkyboxSources(1024),
])

swapSkybox(farSources?, nearSources?) 仅更新传入的参数（undefined 保留当前值），支持在 on() 前调用（影响后续挂载）。

清理与生命周期

// 页面或场景退出时：移除高度切换监听并还原进入前的原 skyBox（幂等）
effect.off(viewer)
// 或等价销毁
effect.destroy(viewer)

on() 保存进入前 scene.skyBox，off() 还原（修复源案例 destroy 不还原天空盒的副作用泄漏）；
原值为 undefined（无天空盒）时同样还原为 undefined；
on/off/destroy 均幂等，重复调用安全。

与原生 Cesium API 的组合方式

SkyBoxEffect 直接读写 viewer.scene.skyBox / viewer.scene.postRender，是 SkyBox 的封装，可与其他接管 scene.skyBox 的逻辑共存（进入/退出即接管/还原）；
手动替换 6 面贴图等价于：
ts
```
viewer.scene.skyBox = new Cesium.SkyBox({ sources: createSpaceSkyboxSources() })
```
但 SkyBoxEffect 额外提供高度联动切换与幂等还原。

Cesium 版本限制

目标版本基于 Cesium SkyBox（sources 支持 URL / Image 对象）；
GroundSkyBox 已在目标版本移除：源案例的近景"地面天空盒"以标准 SkyBox + 地面朝向的程序化贴图重建（GroundSkyBox 的贴地语义由贴图内容承载）；
已验证目标版本：Cesium 1.133.1。

SkyBoxEffect 天空盒切换效果 ​

能力定位 ​

构造函数 ​

基础示例 ​

零资产生成纹理 ​

资产来源与授权 ​

切换近景组（对齐源案例 changeSkyBox） ​

运行时替换贴图 ​

清理与生命周期 ​

与原生 Cesium API 的组合方式 ​

Cesium 版本限制 ​