@soonspacejs/plugin-tiles 2.14.29 → 2.14.31

package/dist/terrain-tiles-renderer/OverlayManager.d.ts

@@ -0,0 +1,125 @@
+import { ImageOverlayPlugin, GeoJSONOverlay, CesiumIonOverlay, TMSTilesOverlay, XYZTilesOverlay, WMSTilesOverlay, WMTSTilesOverlay, UrlTemplateTilesOverlay } from 'um-3d-tiles-renderer/plugins';
+import { ResourceManager } from './ResourceManager';
+import { IGeoJSONOverlayOptions, ICesiumIonOverlayOptions, ITMSTilesOverlayOptions, IXYZTilesOverlayOptions, IWMSTilesOverlayOptions, IWMTSTilesOverlayOptions, IUrlTemplateOverlayOptions } from './types';
+/**
+ * OverlayManager - Overlay 实例管理器
+ *
+ * 职责：
+ * - 管理 Overlay 的运行时实例
+ * - 与 ResourceManager 配合：配置存储在 ResourceManager，实例由本类管理
+ * - 提供创建、删除、更新 Overlay 的方法
+ */
+export declare class OverlayManager {
+    private imageOverlayPlugin;
+    private resourceManager?;
+    /** 存储所有 overlay 实例 */
+    private _instances;
+    constructor(imageOverlayPlugin: ImageOverlayPlugin | undefined, resourceManager?: ResourceManager | undefined);
+    addGeoJSON(options: IGeoJSONOverlayOptions): GeoJSONOverlay | null;
+    updateGeoJSONColor(id: string, color: string): boolean;
+    updateGeoJSONStrokeStyle(id: string, strokeStyle: string): boolean;
+    updateGeoJSONStrokeWidth(id: string, strokeWidth: number): boolean;
+    updateGeoJSONFillStyle(id: string, fillStyle: string): boolean;
+    updateGeoJSONMode(id: string, mode: 'overlay' | 'mask' | 'invertMask'): boolean;
+    addCesiumIon(options: ICesiumIonOverlayOptions): CesiumIonOverlay | null;
+    addTMS(options: ITMSTilesOverlayOptions): TMSTilesOverlay | null;
+    addXYZ(options: IXYZTilesOverlayOptions): XYZTilesOverlay | null;
+    /**
+     * 添加 URL 模板 Overlay
+     *
+     * 这是一个通用的瓦片加载方式，支持多种 URL 模板变量：
+     * - `{z}`, `{x}`, `{y}` - 标准 XYZ 坐标
+     * - `{s}` - 子域名轮换
+     * - `{reverseY}` - TMS 风格的 Y 坐标
+     * - 地理边界框变量等
+     *
+     * @example
+     * // 标准 XYZ 瓦片
+     * addUrlTemplate({
+     *   id: 'osm',
+     *   url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'
+     * })
+     *
+     * @example
+     * // 带子域名的瓦片
+     * addUrlTemplate({
+     *   id: 'carto',
+     *   url: 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png',
+     *   subdomains: 'abcd'
+     * })
+     *
+     * @example
+     * // ESRI 风格（y/x 顺序）
+     * addUrlTemplate({
+     *   id: 'esri',
+     *   url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}'
+     * })
+     */
+    addUrlTemplate(options: IUrlTemplateOverlayOptions): UrlTemplateTilesOverlay | null;
+    addWMS(options: IWMSTilesOverlayOptions): Promise<WMSTilesOverlay | null>;
+    addWMTS(options: IWMTSTilesOverlayOptions): Promise<WMTSTilesOverlay | null>;
+    /**
+     * 移除 overlay
+     */
+    remove(id: string): boolean;
+    /**
+     * 获取 overlay 实例
+     */
+    get(id: string): any | undefined;
+    /**
+     * 检查 overlay 是否存在
+     */
+    has(id: string): boolean;
+    /**
+     * 设置 overlay 可见性
+     */
+    setVisible(id: string, visible: boolean): boolean;
+    /**
+     * 设置 overlay 透明度
+     */
+    setOpacity(id: string, opacity: number): boolean;
+    /**
+     * 设置 overlay 层级
+     */
+    setOrder(id: string, order: number): boolean;
+    /**
+     * 获取 overlay 层级
+     */
+    getOrder(id: string): number;
+    /**
+     * 将 overlay 移到最顶层
+     */
+    bringToFront(id: string): boolean;
+    /**
+     * 将 overlay 移到最底层
+     */
+    sendToBack(id: string): boolean;
+    /**
+     * 从 ResourceManager 恢复所有资源
+     */
+    restoreFromResourceManager(): void;
+    /**
+     * 根据资源配置创建 overlay（不保存到 ResourceManager）
+     */
+    private _createOverlayFromResource;
+    /**
+     * 获取所有 overlay ID
+     */
+    getIds(): string[];
+    /**
+     * 获取 overlay 数量
+     */
+    get count(): number;
+    /**
+     * 获取本地影像数量（不依赖 ResourceManager）
+     */
+    private _getLocalImageryCount;
+    /**
+     * 只清理实例（保留 ResourceManager 中的配置）
+     */
+    disposeInstances(): void;
+    /**
+     * 完全销毁（清理实例和配置）
+     */
+    dispose(): void;
+}

package/dist/terrain-tiles-renderer/ResourceManager.d.ts

@@ -0,0 +1,78 @@
+import { IGeoJSONOverlayOptions, ICesiumIonOverlayOptions, ITMSTilesOverlayOptions, IXYZTilesOverlayOptions, IWMSTilesOverlayOptions, IWMTSTilesOverlayOptions, OverlayType } from './types';
+/**
+ * Overlay 资源配置
+ */
+export interface IOverlayResource {
+    id: string;
+    type: OverlayType;
+    options: IGeoJSONOverlayOptions | ICesiumIonOverlayOptions | ITMSTilesOverlayOptions | IXYZTilesOverlayOptions | IWMSTilesOverlayOptions | IWMTSTilesOverlayOptions;
+}
+/**
+ * ResourceManager 资源管理器
+ * 负责记录和管理所有资源的配置信息（不持有实例引用）
+ *
+ * 设计理念：
+ * - 只存储配置数据，不存储运行时实例
+ * - 切换地形时，通过配置数据重建所有资源
+ * - 解耦配置管理和实例管理
+ */
+export declare class ResourceManager {
+    /** Overlay 资源配置 */
+    private _overlays;
+    /**
+     * 添加 Overlay 资源配置
+     */
+    addOverlay(resource: IOverlayResource): void;
+    /**
+     * 获取 Overlay 资源配置
+     */
+    getOverlay(id: string): IOverlayResource | undefined;
+    /**
+     * 移除 Overlay 资源配置
+     */
+    removeOverlay(id: string): boolean;
+    /**
+     * 检查 Overlay 是否存在
+     */
+    hasOverlay(id: string): boolean;
+    /**
+     * 获取所有 Overlay 资源配置
+     */
+    getAllOverlays(): IOverlayResource[];
+    /**
+     * 获取指定类型的 Overlay 资源配置
+     */
+    getOverlaysByType(type: OverlayType): IOverlayResource[];
+    /**
+     * 获取所有 Overlay 的 ID 列表
+     */
+    getOverlayIds(): string[];
+    /**
+     * 获取 Overlay 数量
+     */
+    get overlayCount(): number;
+    /**
+     * 获取影像类型的 Overlay 数量
+     */
+    getImageryOverlayCount(): number;
+    /**
+     * 更新 Overlay 配置
+     */
+    updateOverlay(id: string, updates: Partial<IOverlayResource['options']>): boolean;
+    /**
+     * 清空所有资源配置
+     */
+    clear(): void;
+    /**
+     * 导出所有资源配置（用于调试或持久化）
+     */
+    export(): {
+        overlays: IOverlayResource[];
+    };
+    /**
+     * 导入资源配置
+     */
+    import(data: {
+        overlays?: IOverlayResource[];
+    }): void;
+}

package/dist/terrain-tiles-renderer/TerrainManager.d.ts

@@ -0,0 +1,75 @@
+import { ITerrainConfig } from './types';
+/**
+ * 地形列表项（面向前端展示）
+ */
+export interface ITerrainListItem {
+    /** 唯一标识符 */
+    id: string;
+    /** 地形配置 */
+    config: ITerrainConfig;
+    /** 是否为当前激活的地形 */
+    active: boolean;
+}
+/**
+ * TerrainManager 地形管理器
+ * 纯数据注册表，记录已添加的地形配置并跟踪当前激活项，供前端列表展示。
+ * 不持有运行时实例，不触发切换逻辑。
+ */
+export declare class TerrainManager {
+    /** 地形配置映射表 */
+    private _terrains;
+    /** 当前激活的地形 ID */
+    private _currentId;
+    /**
+     * 获取当前激活的地形 ID
+     */
+    get currentId(): string | null;
+    /**
+     * 获取已注册的地形数量
+     */
+    get count(): number;
+    /**
+     * 添加地形配置
+     */
+    add(config: ITerrainConfig): void;
+    /**
+     * 移除地形配置
+     */
+    remove(id: string): boolean;
+    /**
+     * 设置当前激活的地形 ID
+     */
+    setCurrentId(id: string | null): void;
+    /**
+     * 检查地形是否已注册
+     */
+    has(id: string): boolean;
+    /**
+     * 获取指定地形配置
+     */
+    get(id: string): ITerrainConfig | undefined;
+    /**
+     * 获取当前激活的地形配置
+     */
+    getCurrent(): ITerrainConfig | undefined;
+    /**
+     * 获取所有地形配置列表（用于前端列表渲染）
+     */
+    getList(): ITerrainListItem[];
+    /**
+     * 获取所有地形配置
+     */
+    getAll(): ITerrainConfig[];
+    /**
+     * 获取所有地形 ID
+     */
+    getIds(): string[];
+    /**
+     * 清空所有地形配置
+     */
+    clear(): void;
+    /**
+     * 销毁管理器
+     */
+    dispose(): void;
+}

package/dist/terrain-tiles-renderer/TerrainTilesRenderer.d.ts

@@ -0,0 +1,218 @@
+import { TilesRenderer } from 'um-3d-tiles-renderer';
+import { TilesFadePlugin, UpdateOnChangePlugin, ImageOverlayPlugin, ReorientationPlugin } from 'um-3d-tiles-renderer/plugins';
+import { default as SoonSpace } from 'soonspacejs';
+import { TileCustomMaterialPlugin } from './plugins';
+import { OverlayManager } from './OverlayManager';
+import { ResourceManager } from './ResourceManager';
+import { TerrainManager } from './TerrainManager';
+import { ITerrainTilesRendererOptions, IGeoJSONOverlayOptions, ICesiumIonOverlayOptions, ITMSTilesOverlayOptions, IXYZTilesOverlayOptions, IWMSTilesOverlayOptions, IWMTSTilesOverlayOptions, IUrlTemplateOverlayOptions, AlphaClipMode, ITerrainConfig } from './types';
+/**
+ * TerrainTilesRenderer 地形渲染器
+ * 支持多种地形源和多个叠加层
+ *
+ * 注意：切换地形时会创建新的 TilesRenderer 实例以避免状态残留问题
+ */
+export declare class TerrainTilesRenderer {
+    readonly ssp: SoonSpace;
+    readonly defaultTerrainId = "__default_terrain__";
+    readonly defaultImageryId = "__default_imagery__";
+    tiles: TilesRenderer;
+    tilesFadePlugin?: TilesFadePlugin;
+    updateOnChangePlugin?: UpdateOnChangePlugin;
+    customMaterialPlugin?: TileCustomMaterialPlugin;
+    imageOverlayPlugin?: ImageOverlayPlugin;
+    reorientationPlugin?: ReorientationPlugin;
+    /** 资源管理器（存储配置） */
+    resourceManager: ResourceManager;
+    /** 地形管理器（记录地形列表） */
+    terrainManager: TerrainManager;
+    /** Overlay 管理器（管理实例） */
+    overlayManager: OverlayManager;
+    /** 当前地形配置 */
+    private _currentTerrainConfig;
+    /** Alpha 裁剪模式 */
+    private _alphaClipMode;
+    /** 是否已启用（添加到场景） */
+    private _enabled;
+    loedTilesSets: Set<() => void>;
+    options: ITerrainTilesRendererOptions;
+    /**
+     * 是否使用 Cesium Ion 地形
+     */
+    get isCesiumIon(): boolean;
+    /**
+     * 获取当前地形配置
+     */
+    get currentTerrainConfig(): ITerrainConfig;
+    /**
+     * 获取/设置最大深度（GUI 可控）
+     */
+    get maxDepth(): number;
+    set maxDepth(value: number);
+    /**
+     * 获取/设置误差目标（GUI 可控）
+     */
+    get errorTarget(): number;
+    set errorTarget(value: number);
+    /**
+     * 获取/设置地形显示状态（GUI 可控）
+     */
+    get showTerrain(): boolean;
+    set showTerrain(value: boolean);
+    /**
+     * 获取/设置 Alpha 裁剪模式（GUI 可控）
+     * - 用于支持 GeoJSON mask 功能
+     */
+    get alphaClipMode(): AlphaClipMode;
+    set alphaClipMode(value: AlphaClipMode);
+    constructor(ssp: SoonSpace, options?: ITerrainTilesRendererOptions);
+    private _initTilesRenderer;
+    /**
+     * 创建 TilesRenderer（统一方法，支持自定义地形和 Cesium Ion 地形）
+     * @param config 地形配置
+     */
+    private _initPlugins;
+    /**
+     * 销毁当前 tiles 实例
+     */
+    private _disposeTilesRenderer;
+    /**
+     * 更新所有已加载模型的 alpha 裁剪模式
+     */
+    private _updateAlphaClipMode;
+    /**
+     * 设置地形
+     * 会创建新的 TilesRenderer 实例以避免状态残留问题
+     * @param config 地形配置
+     * @example
+     * // 设置量化网格地形
+     * tilesRenderer.setTerrain({
+     *   type: TerrainType.QUANTIZED_MESH,
+     *   url: 'https://terrain.example.com/'
+     * })
+     *
+     * // 设置 Cesium Ion 地形
+     * tilesRenderer.setTerrain({
+     *   type: TerrainType.CESIUM_ION,
+     *   apiToken: 'your-token',
+     *   assetId: '1'
+     * })
+     */
+    setTerrain(config: ITerrainConfig, options?: ITerrainTilesRendererOptions | undefined): void;
+    /**
+     * 添加 GeoJSON Overlay
+     * @example
+     * tilesRenderer.addGeoJSON({
+     *   id: 'china-boundary',
+     *   url: './data/china.geojson',
+     *   color: '#ff0000',
+     *   opacity: 0.8
+     * })
+     */
+    addGeoJSON(options: IGeoJSONOverlayOptions): import('um-3d-tiles-renderer/plugins').GeoJSONOverlay | null;
+    /**
+     * 添加 Cesium Ion Overlay
+     */
+    addCesiumIonOverlay(options: ICesiumIonOverlayOptions): import('um-3d-tiles-renderer/plugins').CesiumIonOverlay | null;
+    /**
+     * 添加 TMS Tiles Overlay
+     */
+    addTMSOverlay(options: ITMSTilesOverlayOptions): import('um-3d-tiles-renderer/plugins').TMSTilesOverlay | null;
+    /**
+     * 添加 XYZ Tiles Overlay
+     */
+    addXYZOverlay(options: IXYZTilesOverlayOptions): import('um-3d-tiles-renderer/plugins').XYZTilesOverlay | null;
+    /**
+     * 添加 URL Template Overlay
+     *
+     * 支持多种 URL 模板变量：
+     * - `{z}`, `{x}`, `{y}` - 标准 XYZ 坐标
+     * - `{s}` - 子域名轮换
+     * - `{reverseY}` - TMS 风格的 Y 坐标
+     * - `{westDegrees}`, `{southDegrees}`, `{eastDegrees}`, `{northDegrees}` - 地理边界框
+     *
+     * @example
+     * tilesPlugin.addUrlTemplateOverlay({
+     *   id: 'osm',
+     *   url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'
+     * })
+     *
+     * @example
+     * tilesPlugin.addUrlTemplateOverlay({
+     *   id: 'carto',
+     *   url: 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png',
+     *   subdomains: 'abcd'
+     * })
+     */
+    addUrlTemplateOverlay(options: IUrlTemplateOverlayOptions): import('um-3d-tiles-renderer/plugins').UrlTemplateTilesOverlay | null;
+    /**
+     * 添加 WMS Tiles Overlay
+     */
+    addWMSOverlay(options: IWMSTilesOverlayOptions): Promise<import('um-3d-tiles-renderer/plugins').WMSTilesOverlay | null>;
+    /**
+     * 添加 WMTS Tiles Overlay
+     */
+    addWMTSOverlay(options: IWMTSTilesOverlayOptions): Promise<import('um-3d-tiles-renderer/plugins').WMTSTilesOverlay | null>;
+    /**
+     * 移除指定 overlay
+     */
+    removeOverlay(id: string): boolean;
+    /**
+     * 更新 GeoJSON 颜色
+     */
+    updateGeoJSONColor(id: string, color: string): boolean;
+    /**
+     * 更新 GeoJSON 模式
+     * - overlay: 普通叠加显示
+     * - mask: 只显示 GeoJSON 区域内的地形
+     * - invertMask: 只显示 GeoJSON 区域外的地形
+     */
+    updateGeoJSONMode(id: string, mode: 'overlay' | 'mask' | 'invertMask'): boolean;
+    /**
+     * 更新 GeoJSON 描边样式
+     */
+    updateGeoJSONStrokeStyle(id: string, strokeStyle: string): boolean;
+    /**
+     * 更新 GeoJSON 描边宽度
+     */
+    updateGeoJSONStrokeWidth(id: string, strokeWidth: number): boolean;
+    /**
+     * 更新 GeoJSON 填充样式
+     */
+    updateGeoJSONFillStyle(id: string, fillStyle: string): boolean;
+    /**
+     * 设置 overlay 层级顺序
+     * @param id overlay ID
+     * @param order 层级顺序，数值越大越靠上
+     * @example
+     * tilesRenderer.setOverlayOrder('china-boundary', 10)
+     */
+    setOverlayOrder(id: string, order: number): boolean;
+    /**
+     * 获取 overlay 当前的层级顺序
+     * @param id overlay ID
+     */
+    getOverlayOrder(id: string): number;
+    /**
+     * 将 overlay 移动到最顶层
+     */
+    bringOverlayToFront(id: string): boolean;
+    /**
+     * 将 overlay 移动到最底层
+     */
+    sendOverlayToBack(id: string): boolean;
+    /**
+     * 设置 overlay 可见性
+     */
+    setOverlayVisible(id: string, visible: boolean): boolean;
+    /**
+     * 设置 overlay 透明度
+     */
+    setOverlayOpacity(id: string, opacity: number): boolean;
+    render: () => void;
+    beforeRenderHandler: () => void;
+    enable(): void;
+    disable(): void;
+    invalidate(lon: number, lat: number, alt: number): () => void;
+    dispose(): void;
+}

package/dist/terrain-tiles-renderer/index.d.ts

@@ -0,0 +1,6 @@
+export { TerrainTilesRenderer, } from './TerrainTilesRenderer';
+export { OverlayManager, } from './OverlayManager';
+export { ResourceManager, } from './ResourceManager';
+export { TerrainManager, } from './TerrainManager';
+export { TileCustomMaterialPlugin, } from './plugins';
+export * from './types';

package/dist/terrain-tiles-renderer/plugins/TileCustomMaterialPlugin.d.ts

@@ -0,0 +1,26 @@
+import { Object3D } from 'three';
+import { TilesRenderer } from 'um-3d-tiles-renderer';
+export type AlphaClipMode = 'alphaTest' | 'transparent' | 'alphaToCoverage';
+/**
+ * 自定义材质插件
+ * 参考 ionExample.js：只修改材质的 alpha 属性，不替换材质
+ * 支持设置 alpha 裁剪模式（用于 GeoJSON mask）
+ */
+export declare class TileCustomMaterialPlugin {
+    priority: number;
+    /** Alpha 裁剪模式 */
+    alphaClipMode: AlphaClipMode;
+    /**
+     * um-3d-tiles-renderer 插件接口：处理新加载的瓦片模型
+     */
+    processTileModel(scene: Object3D): void;
+    /**
+     * 更新所有已加载模型的材质
+     * @param tiles TilesRenderer 实例
+     */
+    updateAllLoadedModels(tiles: TilesRenderer): void;
+    /**
+     * 应用配置到单个材质
+     */
+    private _applyToMaterial;
+}

package/dist/terrain-tiles-renderer/plugins/index.d.ts

@@ -0,0 +1 @@
+export { TileCustomMaterialPlugin, } from './TileCustomMaterialPlugin';