@metagl/sdk-render 1.0.8 → 1.0.10

package/lacdt.render.d.ts

@@ -1,5 +1,5 @@
 import * as Cesium from 'cesium';
-import { Cartesian3, Color, Viewer, PostProcessStage, Cartesian4, Rectangle, Cesium3DTileset, ClippingPolygonCollection } from 'cesium';
+import { Cartesian3, Color, Viewer, PostProcessStage, Cartesian4, Rectangle, Primitive, Cesium3DTileset, ClippingPolygonCollection } from 'cesium';
 import { Render as Render$1 } from '@/system/RenderCore';
 
 /**
@@ -104,6 +104,15 @@ declare class LightingSystem implements RenderSystem {
     destroy(): void;
 }
 
+/**
+ * 检测 Viewer 运行环境
+ *
+ * 判断依据：DC V5.0.0 移除了原生 cesiumWidget，改为自身的 widgetContainer。
+ * 保留 cesiumWidget → 'cesium'（原生或其他兼容封装）
+ * 缺少 cesiumWidget → 'dc'（DC.Viewer 或同类框架）
+ */
+type ViewerEnv = 'cesium' | 'dc';
+
 /**
  * 阴影系统配置
  */
@@ -128,6 +137,9 @@ declare class ShadowSystem implements RenderSystem {
     private config;
     private isEnabled;
     private originalSettings?;
+    private viewerEnv;
+    private shadowFrameListener?;
+    private originalGlobeShadows?;
     /**
      * 默认配置 - 从 EnvironmentDefaults 统一管理
      */
@@ -137,7 +149,7 @@ declare class ShadowSystem implements RenderSystem {
      * @param viewer -  Cesium Viewer 实例
      * @param config - 阴影系统配置
      */
-    constructor(viewer: Viewer, config?: ShadowConfig);
+    constructor(viewer: Viewer, config?: ShadowConfig, viewerEnv?: ViewerEnv);
     /**
      * 初始化
      */
@@ -150,6 +162,26 @@ declare class ShadowSystem implements RenderSystem {
      * 启用阴影系统
      */
     enable(): void;
+    /**
+     * DC 环境专用启用逻辑
+     *
+     * 问题根因：DC 初始化时 globe.shadows = RECEIVE_ONLY（地形接收阴影）。
+     * DC 环境下阴影相机视锥投影计算异常，深度比较全部失效，
+     * 导致视锥覆盖的整片地形全部变黑（图二中的巨型黑色矩形）。
+     *
+     * 修复：禁用地形阴影接收（globe.shadows = DISABLED），地形不参与阴影系统。
+     * 3D tileset 阴影独立配置（tileset.shadows），不受影响。
+     */
+    private enableDCMode;
+    /**
+     * DC 环境专用：保持 needsUpdate，确保 tileset 阴影每帧正常更新
+     * 不覆盖 _outOfView：Cesium 的高度/太阳角物理判断必须保留
+     */
+    private registerDCWorkaround;
+    /**
+     * 移除 DC 监听器（disable / destroy 时调用）
+     */
+    private removeDCWorkaround;
     /**
      * 禁用阴影系统
      */
@@ -201,6 +233,8 @@ interface VolumetricCloudsConfig {
     cloudThickness?: number;
     cloudLightIntensity?: number;
     cloudIntensity?: number;
+    cloudOpacityMin?: number;
+    cloudOpacityMax?: number;
     visibility?: CloudVisibilityConfig;
 }
 /**
@@ -342,9 +376,9 @@ declare class AtmosphereScatteringSystem implements RenderSystem {
     private getRealPlanetRadius;
     /**
      * 根据相机高度动态调节 skyAtmosphere.brightnessShift
-     *   低空（< 30km） ：-1.0（完全暗淡 = 等效关闭），自定义大气主导
-     *   30km → 200km  ：线性从 -1.0 → 0.0 平滑过渡
-     *   高空（> 200km）：0.0（正常亮度），Cesium 内置光晕完全接管
+     *   低空（< 100km，卡门线以下）：-1.0（完全暗淡），自定义大气主导，城市/宏观城市无光晕圈
+     *   100km → 500km           ：线性从 -1.0 → 0.0 平滑过渡（进入轨道空间）
+     *   高空（> 500km）          ：0.0（正常亮度），Cesium 内置光晕完全接管
      */
     private updateSkyAtmosphereIntensity;
     /**
@@ -700,6 +734,8 @@ declare class PostProcessingSystem implements RenderSystem {
     disable(): void;
     update(config: Partial<PostProcessingConfig>): void;
     getStatus(): boolean;
+    /** 返回当前已加入队列的自定义 Stage 列表（供 RenderCore 做顺序修正）*/
+    getCustomStages(): PostProcessStage[];
     getConfig(): PostProcessingConfig;
     saveConfig(): any;
     destroy(): void;
@@ -951,148 +987,256 @@ declare class CameraListenerSystem {
 }
 
 /**
- * 水体系统配置接口
+ * 水体配置接口
  */
 interface WaterConfig {
-    /** 是否启用水体系统 */
-    enabled: boolean;
-    /** 水体颜色 */
-    color?: Color;
-    /** 水体透明度 */
-    opacity?: number;
-    /** 水体反射强度 */
-    reflectivity?: number;
-    /** 水体折射率 */
-    refractivity?: number;
-    /** 水面波动强度 */
-    waveStrength?: number;
-    /** 水面波动频率 */
-    waveFrequency?: number;
-    /** 水面波动速度 */
-    waveSpeed?: number;
-    /** 法线纹理重复频率 */
-    normalRepeat?: number;
-    /** 浅滩深度 */
-    shallowWaterDepth?: number;
-    /** 深度衰减系数 */
-    depthAttenuation?: number;
+    /** 水体基础颜色 RGBA */
+    baseWaterColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /** 波纹频率 */
+    frequency?: number;
+    /** 动画速度 */
+    animationSpeed?: number;
+    /** 振幅 */
+    amplitude?: number;
+    /** 高光强度 */
+    specularIntensity?: number;
+    /** 法线贴图路径 */
+    normalMap?: string;
+}
+/**
+ * 水体加载进度
+ */
+interface WaterLoadProgress {
+    /** 总实体数 */
+    total: number;
+    /** 已加载数 */
+    loaded: number;
+    /** 百分比 */
+    percentage: number;
+}
+/**
+ * 水体加载选项
+ */
+interface WaterLoadOptions {
+    /** 每批处理数量，默认 10 */
+    batchSize?: number;
+    /** 进度回调 */
+    onProgress?: (progress: WaterLoadProgress) => void;
+    /** 取消信号 */
+    signal?: AbortSignal;
+}
+/**
+ * 水体加载状态
+ */
+interface WaterLoadState {
+    /** 是否正在加载 */
+    isLoading: boolean;
+    /** 当前加载的图层ID */
+    currentLayer?: string;
+    /** 加载进度 */
+    progress?: WaterLoadProgress;
+}
+/**
+ * 水体图层项
+ */
+interface WaterLayerItem {
+    id: string;
+    name: string;
+    url?: string;
+    source?: 'url' | 'file';
+    primitive: any;
+    visible: boolean;
 }
 /**
  * 水体系统类
- * 负责管理场景中的水体效果
+ * 负责管理场景中的水体效果，支持 GeoJSON 数据加载
+ */
+/**
+ * 水体事件类型
+ */
+type WaterEventType = 'waterLayer:add' | 'waterLayer:remove' | 'waterLayer:visible';
+/**
+ * 水体系统类
+ * 负责管理场景中的水体效果，支持 GeoJSON 数据加载
  */
 declare class WaterSystem implements RenderSystem {
     private viewer;
     private config;
-    private waterPrimitive?;
-    private waterPrimitives;
-    private isInitialized;
-    private isEnabled;
-    private morphCompleteListener;
-    private postRenderListener;
-    private lastWaterPrimitiveParams;
-    private lastWaterPrimitiveConfig;
+    private waterLayers;
+    private enabled;
+    private eventListeners;
+    /** 共享材质实例 */
+    private _sharedWaterMaterial;
+    /** 地形高度是否已初始化 */
+    private _terrainHeightsReady;
+    /** 地形高度初始化 Promise */
+    private _terrainHeightsPromise;
+    /** 加载状态 */
+    private _loadState;
+    /** 取消控制器 */
+    private _abortController;
     constructor(viewer: Viewer, config?: WaterConfig);
     /**
-     * 初始化水体系统
+     * 初始化事件系统
+     */
+    private initializeEvents;
+    /**
+     * 添加事件监听
+     */
+    on(event: WaterEventType, callback: (layer?: WaterLayerItem, data?: any) => void): void;
+    /**
+     * 移除事件监听
+     */
+    off(event: WaterEventType, callback: Function): void;
+    /**
+     * 触发事件
+     */
+    private emitEvent;
+    /**
+     * 初始化系统
      */
     initialize(): void;
     /**
-     * 创建水体几何
+     * 启用系统（不自动创建水面，水面通过 loadWaterFromUrl/loadWaterFromFile 添加）
+     * 水图层始终使用贴地模式
+     *
+     * 优化：地形高度初始化改为后台异步执行，enable() 立即返回
      */
-    private createWaterGeometry;
+    enable(): Promise<void>;
     /**
-     * 加载水体数据
+     * 异步初始化地形高度数据
+     * 在后台执行，不阻塞主线程
      */
-    private loadWaterData;
+    private initializeTerrainHeightsAsync;
     /**
-     * 创建调试用的水体
+     * 等待地形初始化完成
+     * 在加载水图层前调用，确保地形数据已准备好
      */
-    private createDebugWater;
+    waitForTerrainReady(): Promise<void>;
     /**
-     * 配置水体样式
+     * 检查地形是否已初始化
      */
-    private setupWaterStyling;
+    isTerrainReady(): boolean;
     /**
-     * 设置事件监听器
+     * 禁用系统
      */
-    private setupEventListeners;
+    disable(): void;
     /**
-     * 更新水体动画
+     * 更新配置（更新所有已加载水图层的外观参数）
      */
-    private updateWaterAnimation;
+    update(config: Partial<WaterConfig>): void;
     /**
-     * 启用水体系统（带配置恢复）
+     * 实时更新水图层效果（无需重新加载）
+     * 直接修改已存在水图元的材质参数
      */
-    enable(): void;
+    updateWaterLayerEffect(config: Partial<WaterConfig>): void;
     /**
-     * 清理可能残留的引用
+     * 更新单个图元的材质参数
      */
-    private cleanupRemnants;
+    private updateSinglePrimitiveMaterial;
     /**
-     * 重新加载水体数据
+     * 获取系统状态
      */
-    private reloadWaterData;
+    getStatus(): boolean;
     /**
-     * 应用水体配置
+     * 获取当前配置
      */
-    private applyWaterConfig;
+    getConfig(): WaterConfig;
     /**
-     * 重新创建水体图元，应用当前配置
+     * 从 URL 加载水体数据（优化版本，支持进度回调）
+     * @param url GeoJSON 数据地址
+     * @param name 水图层名称
+     * @param options 加载选项（包含进度回调）
+     * @returns 水图层ID
      */
-    private recreateWaterPrimitives;
+    loadWaterFromUrl(url: string, name?: string, options?: WaterLoadOptions): Promise<string>;
     /**
-     * 创建带配置的调试水体
+     * 从文件加载水体数据（优化版本，支持进度回调）
+     * @param file GeoJSON 文件
+     * @param name 水图层名称
+     * @param options 加载选项（包含进度回调）
+     * @returns 水图层ID
      */
-    private createDebugWaterWithConfig;
+    loadWaterFromFile(file: File, name?: string, options?: WaterLoadOptions): Promise<string>;
     /**
-     * 销毁水体图元但不重置配置
+     * 异步分批创建水体图元
+     * 使用 requestIdleCallback 分批处理，避免阻塞主线程
      */
-    private destroyWaterPrimitives;
+    private createWaterPrimitivesAsync;
     /**
-     * 禁用水体系统（强制完全销毁）
+     * 从 GeoJSON 数据源创建水体图元（同步版本，保留向后兼容）
+     * @deprecated 建议使用 createWaterPrimitivesAsync 异步版本
      */
-    disable(): void;
-    private stopAllAnimations;
-    private removeAllWaterPrimitives;
-    private isWaterPrimitive;
-    private clearAllReferences;
-    private triggerGarbageCollection;
-    private verifyShutdown;
+    private createWaterPrimitivesFromDataSource;
     /**
-     * 更新水体配置
+     * 获取或创建共享材质实例
      */
-    update(config: Partial<WaterConfig>): void;
+    private getOrCreateSharedMaterial;
     /**
-     * 更新水体样式
+     * 使用共享材质创建水体图元
      */
-    private updateWaterStyle;
+    private createWaterPrimitiveWithSharedMaterial;
     /**
-     * 获取系统状态
+     * 创建水体图元（保留向后兼容）
+     * @deprecated 建议使用 createWaterPrimitiveWithSharedMaterial
      */
-    getStatus(): boolean;
+    private createWaterPrimitive;
     /**
-     * 获取当前配置
+     * 创建图元集合
      */
-    getConfig(): WaterConfig;
+    private createPrimitiveCollection;
     /**
-     * 保存配置
+     * 让出主线程的工具方法
+     * 使用 requestIdleCallback 或 setTimeout 作为 fallback
      */
-    saveConfig(): WaterConfig;
+    private yieldToMain;
     /**
-     * 获取系统状态信息（调试用）
+     * 获取加载状态
      */
-    getDebugInfo(): any;
+    getLoadState(): WaterLoadState;
+    /**
+     * 取消当前加载
+     */
+    cancelLoad(): void;
+    /**
+     * 创建取消控制器
+     */
+    createAbortController(): AbortController;
     /**
-     * 检查图元是否在场景中（安全方法）
+     * 更新加载状态
      */
-    private isPrimitiveInScene;
+    private updateLoadState;
     /**
-     * 强制清理所有水体图元
+     * 移除指定水图层
      */
-    forceCleanup(): void;
+    removeWaterLayer(layerId: string): boolean;
     /**
-     * 销毁水体系统
+     * 清除所有用户添加的水图层
+     */
+    clearAllWaterLayers(): void;
+    /**
+     * 获取所有水图层
+     */
+    getWaterLayers(): WaterLayerItem[];
+    /**
+     * 获取指定水图层
+     */
+    getWaterLayer(layerId: string): WaterLayerItem | undefined;
+    /**
+     * 设置水图层可见性
+     */
+    setWaterLayerVisible(layerId: string, visible: boolean): boolean;
+    /**
+     * 生成唯一ID
+     */
+    private generateId;
+    /**
+     * 销毁系统
      */
     destroy(): void;
 }
@@ -1147,6 +1291,8 @@ declare class LayerSystem implements RenderSystem {
     private layers;
     private entities;
     private eventListeners;
+    private savedTerrainProvider;
+    private defaultTerrainProvider;
     constructor(render: Render);
     initialize(): void;
     enable(): void;
@@ -1157,6 +1303,7 @@ declare class LayerSystem implements RenderSystem {
     saveConfig?(): void;
     /**
      * 加载地球已有的图层
+     * 预设四个固定图层：影像地图、影像注记、矢量地图、高程
      */
     loadExistingLayers(): void;
     /**
@@ -1167,6 +1314,11 @@ declare class LayerSystem implements RenderSystem {
      * 递归加载子实体
      */
     private loadChildEntities;
+    /**
+     * 异步加载高程图层
+     * @param layer 高程图层配置
+     */
+    private loadTerrainLayer;
     /**
      * 获取所有实体和图元对象
      */
@@ -1245,8 +1397,21 @@ declare class LayerSystem implements RenderSystem {
     private removeFromCesium;
     /**
      * 设置图层可见性
+     * 支持底图互斥：当勾选矢量地图时，自动取消勾选影像地图和影像注记，反之亦然
+     * 支持高程图层可见性切换
      */
     setLayerVisible(layerId: string, visible: boolean): boolean;
+    /**
+     * 设置高程图层可见性
+     * @param visible 是否可见
+     */
+    private setTerrainLayerVisible;
+    /**
+     * 处理底图互斥逻辑
+     * 当勾选矢量地图时，取消勾选影像地图和影像注记
+     * 当勾选影像地图或影像注记时，取消勾选矢量地图
+     */
+    private handleBaseMapMutex;
     /**
      * 设置图层可见性（内部方法）
      */
@@ -2325,6 +2490,7 @@ declare class Render {
     engine: any;
     viewer: Viewer;
     config: RenderConfig;
+    viewerEnv: ViewerEnv;
     private lightingSystem;
     private shadowSystem;
     private volumetricCloudsSystem;
@@ -2353,6 +2519,9 @@ declare class Render {
      *
      * 修正方式：直接操作 PostProcessStageCollection 的内部 _stages 数组调整顺序，
      * 不调用 remove()（remove 会 destroy GPU 资源），不触发 Shader 重编译，无视觉闪烁。
+     *
+     * 目标顺序：云 → 大气 → 后处理(whiteBalance/colorAdjustment/...)
+     * 原因：后处理的 exposure 等效果作用在大气之后才正确；大气需读取未经后处理的原始场景。
      */
     private ensurePostProcessStageOrder;
     private registerSystems;
@@ -2377,6 +2546,11 @@ declare class Render {
      * 清除当前预设，关闭所有环境系统
      */
     clearPreset(): void;
+    /**
+     * 重置所有环境系统到默认配置（单一出口）
+     * 等效于 applyConfig(DEFAULT_CONFIG)，所有系统参数回到 DefaultConfig.ts 定义的值并禁用。
+     */
+    resetConfig(): void;
     /**
      * 获取当前激活的预设 ID，未激活时返回 null
      */
@@ -2385,6 +2559,19 @@ declare class Render {
      * 启用所有系统
      */
     enableAllSystems(): void;
+    /**
+     * 以 DefaultConfig 参数启用所有环境系统
+     *
+     * 与直接调用 enableSystem() 的区别：
+     *   - 先将所有系统参数重置为 DefaultConfig（清除预设残留）
+     *   - 再启用所有环境系统
+     *
+     * 解决问题：
+     *   "全部开启"按钮点击时，若之前曾应用过预设，系统内部仍持有预设参数
+     *   （如 ACES 色调映射 / exposure 1.20 / 暖色温），导致视觉结果与 DefaultConfig 不一致。
+     *   此方法保证"全部开启"始终以 DefaultConfig 参数运行。
+     */
+    enableAllWithDefaults(): void;
     /**
      * 禁用所有系统
      */
@@ -3040,11 +3227,11 @@ declare class WaterControl {
      */
     createPanel(container: HTMLElement): void;
     /**
-     * 创建面板内容
+     * 创建面板内容（不包含区域设置，区域通过 GeoJSON 文件指定）
      */
     private createPanelContent;
     /**
-     * 初始化事件监听器
+     * 初始化事件监听器（不包含区域设置，区域通过 GeoJSON 文件指定）
      */
     initEventListeners(container: HTMLElement): void;
     /**
@@ -3056,13 +3243,199 @@ declare class WaterControl {
      */
     applyDefaultPresets(): void;
     /**
-     * RGB颜色转十六进制
+     * RGBA 对象转十六进制
      */
-    private rgbToHex;
+    private rgbaToHex;
     /**
-     * 十六进制颜色转RGB
+     * 十六进制颜色转 RGBA 对象
      */
-    private hexToRgb;
+    private hexToRgba;
+}
+
+/**
+ * 海洋数据项接口
+ */
+interface SeaLayerItem {
+    id: string;
+    name: string;
+    url?: string;
+    source?: 'url' | 'file';
+    primitive: Primitive | null;
+    visible: boolean;
+}
+/**
+ * 海洋系统配置接口
+ */
+interface SeaConfig {
+    /** 是否启用海洋系统 */
+    enabled: boolean;
+    /** 海洋颜色 */
+    color?: Color;
+    /** 海洋透明度 */
+    opacity?: number;
+    /** 海洋反射强度 */
+    specularIntensity?: number;
+    /** 海洋波动振幅 */
+    amplitude?: number;
+    /** 海洋波动频率 */
+    frequency?: number;
+    /** 海洋动画速度 */
+    animationSpeed?: number;
+    /** 法线纹理路径 */
+    normalMapUrl?: string;
+    /** 海洋数据路径 */
+    dataUrl?: string;
+}
+/**
+ * 海洋系统类
+ * 负责管理场景中的海洋效果
+ * 参考 RenderSeaPolygon 实现
+ */
+declare class SeaSystem implements RenderSystem {
+    private viewer;
+    private config;
+    private seaPrimitive;
+    private isInitialized;
+    private isEnabled;
+    private morphCompleteListener;
+    private postRenderListener;
+    constructor(viewer: Viewer, config?: SeaConfig);
+    /**
+     * 初始化海洋系统
+     */
+    initialize(): void;
+    /**
+     * 创建海洋几何
+     */
+    private createSeaGeometry;
+    /**
+     * 加载海洋数据
+     */
+    private loadSeaData;
+    /**
+     * 从GeoJSON获取层级结构
+     */
+    private getHierarchies;
+    /**
+     * 从几何体获取层级结构
+     */
+    private getHierarchiesFromGeometry;
+    /**
+     * 从坐标数组获取层级结构
+     */
+    private getHierarchy;
+    /**
+     * 绘制海洋
+     */
+    private drawSea;
+    /**
+     * 创建水体材质
+     */
+    private createWaterMaterial;
+    /**
+     * 创建调试用的海洋
+     */
+    private createDebugSea;
+    /**
+     * 配置海洋样式
+     */
+    private setupSeaStyling;
+    /**
+     * 设置事件监听器
+     */
+    private setupEventListeners;
+    /**
+     * 更新海洋动画
+     */
+    private updateSeaAnimation;
+    /**
+     * 启用海洋系统
+     */
+    enable(): void;
+    /**
+     * 重新创建海洋图元
+     */
+    private recreateSeaPrimitives;
+    /**
+     * 禁用海洋系统
+     */
+    disable(): void;
+    /**
+     * 销毁海洋图元
+     */
+    private destroySeaPrimitives;
+    /**
+     * 更新海洋配置
+     */
+    update(config: Partial<SeaConfig>): void;
+    /**
+     * 更新海洋样式
+     */
+    private updateSeaStyle;
+    /**
+     * 获取系统状态
+     */
+    getStatus(): boolean;
+    /**
+     * 获取当前配置
+     */
+    getConfig(): SeaConfig;
+    /**
+     * 保存配置
+     */
+    saveConfig(): SeaConfig;
+    /**
+     * 获取系统状态信息（调试用）
+     */
+    getDebugInfo(): any;
+    /**
+     * 销毁海洋系统
+     */
+    destroy(): void;
+    /** 用户添加的海图层 */
+    private seaLayers;
+    /**
+     * 从 URL 加载海洋数据
+     * @param url GeoJSON 数据地址
+     * @param name 海图层名称
+     * @returns 海图层ID
+     */
+    loadSeaFromUrl(url: string, name?: string): Promise<string>;
+    /**
+     * 从文件加载海洋数据
+     * @param file GeoJSON 文件
+     * @param name 海图层名称
+     * @returns 海图层ID
+     */
+    loadSeaFromFile(file: File, name?: string): Promise<string>;
+    /**
+     * 从层级结构创建海洋图元
+     */
+    private createSeaPrimitivesFromHierarchies;
+    /**
+     * 获取所有用户添加的海图层
+     */
+    getSeaLayers(): SeaLayerItem[];
+    /**
+     * 获取指定海图层
+     */
+    getSeaLayer(layerId: string): SeaLayerItem | undefined;
+    /**
+     * 设置海图层可见性
+     */
+    setSeaLayerVisible(layerId: string, visible: boolean): boolean;
+    /**
+     * 移除指定海图层
+     */
+    removeSeaLayer(layerId: string): boolean;
+    /**
+     * 清除所有用户添加的海图层
+     */
+    clearAllSeaLayers(): void;
+    /**
+     * 获取脚本基础URL
+     */
+    private getScriptBaseUrl;
 }
 
 /**
@@ -3501,6 +3874,8 @@ interface SidebarManagerState {
  */
 declare class LayerControl extends PanelBase {
     private layerSystem;
+    private waterSystem;
+    private render;
     private folders;
     private searchTerm;
     private entityExpandedMap;
@@ -3565,6 +3940,18 @@ declare class LayerControl extends PanelBase {
      * 过滤实体和图元对象
      */
     private filterEntities;
+    /**
+     * 过滤水图层
+     */
+    private filterWaterLayers;
+    /**
+     * 渲染水图层文件夹
+     */
+    private renderWaterFolder;
+    /**
+     * 渲染水图层列表
+     */
+    private renderWaterLayerList;
     /**
      * 渲染实体和图元列表（支持递归）
      */
@@ -3589,6 +3976,22 @@ declare class LayerControl extends PanelBase {
      * 显示添加图层对话框
      */
     private showAddLayerDialog;
+    /**
+     * 添加对话框样式
+     */
+    private addDialogStyles;
+    /**
+     * 绑定对话框事件
+     */
+    private bindDialogEvents;
+    /**
+     * 处理水图层添加
+     */
+    private handleWaterLayerAdd;
+    /**
+     * 关闭对话框
+     */
+    private closeDialog;
     /**
      * 显示添加目录对话框
      */
@@ -3605,6 +4008,30 @@ declare class LayerControl extends PanelBase {
      * 切换实体展开/收起状态
      */
     private toggleEntityExpanded;
+    /**
+     * 显示水图层效果编辑对话框
+     */
+    private showWaterEffectDialog;
+    /**
+     * 添加水效果对话框样式
+     */
+    private addWaterEffectDialogStyles;
+    /**
+     * 绑定水效果对话框事件
+     */
+    private bindWaterEffectDialogEvents;
+    /**
+     * 关闭水效果编辑对话框
+     */
+    private closeWaterEffectDialog;
+    /**
+     * RGBA 对象转十六进制
+     */
+    private rgbaToHex;
+    /**
+     * 十六进制颜色转 RGBA 对象
+     */
+    private hexToRgba;
     /**
      * 刷新面板
      */
@@ -4097,227 +4524,71 @@ declare class CameraUrlManager {
     destroy(): void;
 }
 
-/**
- * 矩形区域定义
- */
-interface RainBounds {
-    /** 左上角经度 */
-    west: number;
-    /** 左上角纬度 */
-    north: number;
-    /** 右下角经度 */
-    east: number;
-    /** 右下角纬度 */
-    south: number;
+interface WeatherAreaData {
+    gger: string;
+    minLon: number;
+    maxLon: number;
+    minLat: number;
+    maxLat: number;
+    weatherType: 'rainy' | 'snowy' | 'foggy' | 'sunny';
 }
-/**
- * 下雨系统配置接口
- */
-interface RainConfig {
-    /** 是否启用下雨系统 */
-    enabled: boolean;
-    /** 雨滴发射率 (个/秒) */
-    emissionRate: number;
-    /** 雨滴大小 */
-    particleSize: number;
-    /** 最小生命周期(秒) */
-    minimumParticleLife: number;
-    /** 最大生命周期(秒) */
-    maximumParticleLife: number;
-    /** 最小速度 */
-    minimumSpeed: number;
-    /** 最大速度 */
-    maximumSpeed: number;
-    /** 雨滴颜色 */
-    color: Color;
-    /** 重力因子（负值向下，正值向上） */
-    gravity: number;
-    /** 下雨区域范围（矩形） */
-    bounds?: RainBounds;
-    /** 相机高度超过此值时隐藏雨滴（单位：米），默认5000 */
-    hideAltitude?: number;
-    /** 雨滴纹理图片路径，默认 './image/rain.png' */
-    imagePath?: string;
-    /** 雨滴纹理类型: 'rain' | 'hail' | 'snow' */
-    imageType?: 'rain' | 'hail' | 'snow';
-}
-/**
- * 默认下雨配置
- */
-declare const defaultRainConfig: RainConfig;
-/**
- * 下雨系统类
- * 负责管理场景中的局部下雨效果
- */
-declare class RainSystem implements RenderSystem {
-    private viewer;
-    private config;
-    private rainParticleSystems;
-    private isInitialized;
-    private isEnabled;
-    private rainImage;
-    private hideAltitude;
-    private lastAltitudeCheck;
-    private readonly altitudeCheckInterval;
-    private shaderRainStage;
-    private useShaderRain;
-    private shaderRainHeight;
-    private currentImageType;
-    private weatherIconElement;
-    private weatherIconVisible;
-    constructor(viewer: Viewer, config?: Partial<RainConfig>);
-    /**
-     * 初始化下雨系统
-     */
-    initialize(): void;
-    /**
-     * 在指定矩形范围内创建下雨效果
-     */
-    private createRainSystemsInBounds;
-    /**
-     * 创建网格点的下雨粒子系统
-     */
-    private createGridRainSystem;
-    /**
-     * 计算发射器模型矩阵
-     * 让发射方向向下（旋转使发射器朝向地面）
-     */
-    private computeEmitterModelMatrix;
-    /**
-     * 创建雨滴纹理图像 - 使用 Canvas 程序生成细长的雨丝
-       */
-    private createRainImage;
-    /**
-     * 创建 Canvas 雨滴纹理
-     */
-    private createCanvashailImage;
-    private createCanvasSnowImage;
-    /**
-     * 设置雨滴纹理类型
-     * @param type 纹理类型: 'rain' | 'hail' | 'snow'
-     */
-    setRainImageType(type: 'rain' | 'hail' | 'snow'): void;
-    /**
-     * 设置自定义雨滴纹理路径
-     * @param imagePath 纹理图片路径，如 './image/rain.png'
-     */
-    setRainImage(imagePath: string): void;
-    /**
-     * 创建着色器雨效（后期处理方式）
-     * 参考 natureSimulate.js 的 FS_Rain 实现，兼容 WebGL 2.0
-     */
-    private createShaderRainStage;
-    /**
-     * 根据相机高度切换雨效模式
-     * 500米以内使用着色器雨效，500米以上使用粒子系统
-     */
-    private switchRainEffectMode;
-    /**
-     * 获取相机正下方地形的海拔高度
-     */
-    private getTerrainHeightBelowCamera;
-    /**
-     * 应用重力效果 - 雨滴下落
-     */
-    private applyGravity;
-    /**
-     * 根据相机高度更新雨滴可见性
-     * 当相机高度超过 hideAltitude 时隐藏雨滴，拉近时重新显示
-     * 同时更新天气图标的显示状态
-     */
-    updateCameraVisibility(): void;
-    /**
-     * 创建天气图标 DOM 元素
-     */
-    private createWeatherIcon;
-    /**
-     * 获取当前天气类型的图标信息
-     */
-    private getWeatherIconInfo;
-    /**
-     * 显示天气图标
-     */
-    private showWeatherIcon;
-    /**
-     * 隐藏天气图标
-     */
-    private hideWeatherIcon;
-    /**
-     * 更新天气图标显示内容
-     */
-    private updateWeatherIconContent;
-    /**
-     * 启用下雨系统
-     */
-    enable(): void;
-    /**
-     * 设置相机高度追踪
-     * 在每一帧渲染后检测相机高度，超过阈值时隐藏雨滴
-     * 同时根据高度切换着色器雨效和粒子系统
-     */
-    private cameraTrackingCallback;
-    /**
-     * 设置相机追踪
-     */
-    private setupCameraTracking;
-    /**
-     * 禁用下雨系统
-     */
-    disable(): void;
-    /**
-     * 更新系统配置 - 实时天气数据更新的统一公共接口
-     * 支持不同天气状态间的动态平滑过渡（例如强度由小雨转大雨，或类型由雨转雪）
-     * @param config 部分配置参数，将与现有配置合并
-     */
-    update(config: Partial<RainConfig>): void;
-    /**
-     * 更新下雨区域范围
-     * @param bounds 新的区域范围
-     */
-    private updateBounds;
-    /**
-     * 平滑过渡到新的天气强度
-     * @param targetEmissionRate 目标发射率
-     * @param duration 过渡持续时间（毫秒）
-     */
-    transitionToIntensity(targetEmissionRate: number, duration?: number): void;
-    /**
-     * 平滑过渡到新的天气类型
-     * @param targetType 目标天气类型
-     * @param duration 过渡持续时间（毫秒）
-     */
-    transitionToType(targetType: 'rain' | 'hail' | 'snow', duration?: number): void;
-    /**
-     * 获取系统状态
-     */
-    getStatus(): boolean;
-    /**
-     * 设置相机隐藏高度
-     * @param altitude 相机高度超过此值时隐藏雨滴（单位：米）
-     */
-    setHideAltitude(altitude: number): void;
-    /**
-     * 获取当前相机高度
-     */
-    getCurrentCameraHeight(): number;
-    /**
-     * 设置是否启用着色器雨效模式
-     * @param enabled 是否启用着色器雨效（相机低于500米时自动切换）
-     */
-    setShaderRainEnabled(enabled: boolean): void;
-    /**
-     * 设置着色器雨效切换高度
-     * @param height 相机高度低于此值时切换到着色器雨效（单位：米）
-     */
-    setShaderRainHeight(height: number): void;
-    /**
-     * 销毁系统
-     */
-    destroy(): void;
-    /**
-     * 获取当前配置
-     */
-    getConfig(): RainConfig;
+declare class RainSystem {
+    private _viewer;
+    private _effects;
+    private _anchorEntities;
+    private _allAreas;
+    private _lastCameraPosition;
+    private _effectPaused;
+    private _isPageVisible;
+    private _isWindowFocused;
+    private _rainCanvas;
+    private _snowCanvas;
+    private _fogCanvas;
+    private readonly MAX_EFFECTS;
+    private readonly UPDATE_THRESHOLD;
+    private _pendingAdd;
+    private _pendingRemove;
+    private _isUpdating;
+    private _lastUpdateTime;
+    private readonly THROTTLE_MS;
+    private _tickHandler;
+    constructor(viewer: any, Cesium?: any);
+    /**
+     * 从JSON数组加载天气效果
+     */
+    loadFromJson(areas: WeatherAreaData[]): void;
+    private _setupVisibilityHandler;
+    private _updatePauseState;
+    private _setEffectsPaused;
+    private _pauseAllEffects;
+    private _resumeAllEffects;
+    private _startCameraWatch;
+    private _scheduleUpdate;
+    private _computePendingChanges;
+    private _processNextPending;
+    private _updateVisibleEffects;
+    private _getVisibleAreas;
+    /**
+     * 添加单个天气区域
+     */
+    addWeatherArea(area: WeatherAreaData): void;
+    /**
+     * 移除指定区域天气效果
+     */
+    removeWeatherArea(id: string): void;
+    /**
+     * 清空所有天气效果
+     */
+    clearAll(): void;
+    private _createSunnyEffect;
+    private _createRainEffect;
+    private _createSnowEffect;
+    private _createFogEffect;
+    private _createSunCoreCanvas;
+    private _createRainCanvas;
+    private _createSnowCanvas;
+    private _createFogCanvas;
+    private _getParticleSystemMatrix;
 }
 
 declare global {
@@ -4362,6 +4633,8 @@ declare const render: {
     CameraUrlManager: typeof CameraUrlManager;
     /** 下雨天气系统 */
     RainSystem: typeof RainSystem;
+    /** 海洋系统 */
+    SeaSystem: typeof SeaSystem;
 };
 
-export { AtmosphereControl, type AtmosphereScatteringConfig, AtmosphereScatteringSystem, BuildingControl, BuildingSystem, CameraListener, type CameraListenerConfig, CameraListenerSystem, type CameraListenerSystemConfig, type CameraParams, CameraUrlManager, type CameraUrlManagerConfig, type DirectionalLightConfig, type DistanceFogConfig, DistanceFogSystem, EnvironmentControl, FogControl, type HeightFogConfig, HeightFogSystem, LayerControl, LayerSystem, LightingControl, LightingSystem, PlottingControl, type PostProcessingConfig, PostProcessingControl, PostProcessingSystem, type RainBounds, type RainConfig, RainSystem, Render, type RenderConfig, RenderControl, type ShadowConfig, ShadowControl, ShadowSystem, SidebarControl, TilesetManager, TilesetSearchControl, ToolboxControl, ToolboxSystem, VolumetricCloudControl, type VolumetricCloudsConfig, VolumetricCloudsSystem, type WaterConfig, WaterControl, WaterSystem, defaultRainConfig, render };
+export { AtmosphereControl, type AtmosphereScatteringConfig, AtmosphereScatteringSystem, BuildingControl, BuildingSystem, CameraListener, type CameraListenerConfig, CameraListenerSystem, type CameraListenerSystemConfig, type CameraParams, CameraUrlManager, type CameraUrlManagerConfig, type DirectionalLightConfig, type DistanceFogConfig, DistanceFogSystem, EnvironmentControl, FogControl, type HeightFogConfig, HeightFogSystem, LayerControl, LayerSystem, LightingControl, LightingSystem, PlottingControl, type PostProcessingConfig, PostProcessingControl, PostProcessingSystem, RainSystem, Render, type RenderConfig, RenderControl, type SeaConfig, SeaSystem, type ShadowConfig, ShadowControl, ShadowSystem, SidebarControl, TilesetManager, TilesetSearchControl, ToolboxControl, ToolboxSystem, VolumetricCloudControl, type VolumetricCloudsConfig, VolumetricCloudsSystem, type WaterConfig, WaterControl, WaterSystem, type WeatherAreaData, render };