cesium-xs-sdk 1.0.0

package/src/modules/PlotGraphicType.js

@@ -0,0 +1,43 @@
+/**
+ * 标绘图元类型枚举
+ * 对应 cesium-plot-js 支持的军事标绘类型
+ */
+export const PlotGraphicType = {
+  // 面型标绘
+  TRIANGLE: 'triangle',
+  SECTOR: 'sector',
+  ELLIPSE: 'ellipse',
+  FINE_ARROW: 'fineArrow',
+  ASSAULT_DIRECTION: 'assaultDirection',
+  ATTACK_ARROW: 'attackArrow',
+  SWALLOWTAIL_ATTACK_ARROW: 'swallowtailAttackArrow',
+  SQUAD_COMBAT: 'squadCombat',
+  SWALLOWTAIL_SQUAD_COMBAT: 'swallowtailSquadCombat',
+  DOUBLE_ARROW: 'doubleArrow',
+
+  // 线型标绘
+  STRAIGHT_ARROW: 'straightArrow',
+  CURVED_ARROW: 'curvedArrow',
+  CURVE: 'curve'
+};
+
+/**
+ * 标绘图元分类
+ */
+export const PlotGraphicCategory = {
+  POLYGON: 'polygon',
+  LINE: 'line'
+};
+
+/**
+ * 判断标绘类型是否为线型
+ * @param {string} plotType PlotGraphicType
+ * @returns {boolean}
+ */
+export function isLinePlotType(plotType) {
+  return [
+    PlotGraphicType.STRAIGHT_ARROW,
+    PlotGraphicType.CURVED_ARROW,
+    PlotGraphicType.CURVE
+  ].includes(plotType);
+}

package/src/modules/SceneModule.js

@@ -0,0 +1,600 @@
+import { Config } from '../core/Config.js';
+
+/**
+ * 图层类型枚举
+ * @readonly
+ * @enum {string}
+ */
+export const LayerType = Object.freeze({
+    /** XYZ 瓦片服务 */
+    XYZ: 'xyz',
+    /** WMTS 瓦片服务 */
+    WMTS: 'wmts',
+    /** WMS 动态地图服务 */
+    WMS: 'wms',
+    /** TMS 瓦片服务 */
+    TMS: 'tms',
+    /** 单张图片 */
+    SINGLE_IMAGE: 'single_image',
+    /** 地形数据 */
+    TERRAIN: 'terrain',
+    /** 3D Tiles 模型数据集 */
+    '3DTILES': '3dtiles'
+});
+
+
+// ========== 私有工厂函数（文件内部） ==========
+
+/**
+ * 根据 URL 自动推断图层类型
+ * @param {string} url 服务地址
+ * @returns {string} LayerType 值
+ */
+function autoDetectType(url) {
+    const u = url.toLowerCase();
+
+    // 1. 3DTiles — 以 .json 结尾或包含 3dtiles/3d_tiles
+    if (/\.json(?:[?#]|$)/.test(u) || u.includes('3dtiles') || u.includes('3d_tiles')) {
+        return LayerType['3DTILES'];
+    }
+
+    // 2. 地形 — 包含 terrain / dem / gdem / 水深 / elevation 关键词
+    if (/\/(?:terrain|dem|gdem|水深|elevation|ele)(\/|$)/.test(u) || /[?&#]terrain=/.test(u)) {
+        return LayerType.TERRAIN;
+    }
+
+    // 3. WMTS — 包含 wmts 关键词 或 TileMatrixSet 参数
+    if (u.includes('wmts') || u.includes('tilematrixset')) {
+        return LayerType.WMTS;
+    }
+
+    // 4. WMS — 包含 wms 关键词 或 GetMap 请求参数
+    if (u.includes('wms') || u.includes('getmap') || u.includes('request=getmap')) {
+        return LayerType.WMS;
+    }
+
+    // 5. TMS — 包含 tms 关键词 或 {-y} 反转瓦片
+    if (u.includes('tms') || u.includes('{-y}')) {
+        return LayerType.TMS;
+    }
+
+    // 6. XYZ — URL 模板包含 {z} {x} {y}
+    if (/\{[xyz]\}/.test(u)) {
+        return LayerType.XYZ;
+    }
+
+    // 7. 单张影像 — 有常见图片后缀且无瓦片模板
+    if (/\.(?:png|jpe?g|tiff?|gif|bmp|img)(?:[?#]|$)/.test(u)) {
+        return LayerType.SINGLE_IMAGE;
+    }
+
+    // 默认按 XYZ 处理（最常见的瓦片格式）
+    return LayerType.XYZ;
+}
+
+/**
+ * 根据类型创建对应的 Cesium Provider
+ * @param {string} type  LayerType 值
+ * @param {string} url   服务地址
+ * @param {Object} opts  用户传入的配置
+ * @returns {Object}     Cesium Provider 实例
+ */
+function createProviderByType(type, url, opts) {
+    switch (type) {
+        case LayerType.XYZ:
+        case LayerType.TMS:
+            // XYZ / TMS 均使用 UrlTemplateImageryProvider
+            return new Cesium.UrlTemplateImageryProvider({ url, ...opts });
+
+        case LayerType.WMTS:
+            return new Cesium.WebMapTileServiceImageryProvider({
+                url,
+                layer: opts.layer,
+                style: opts.style || 'default',
+                format: opts.format || 'image/jpeg',
+                tileMatrixSetID: opts.tileMatrixSetID || 'EPSG:4326',
+                ...opts
+            });
+
+        case LayerType.WMS:
+            return new Cesium.WebMapServiceImageryProvider({
+                url,
+                layers: opts.layers || '',
+                parameters: { transparent: true, format: 'image/png', ...opts.parameters },
+                ...opts
+            });
+
+        case LayerType.SINGLE_IMAGE:
+            return new Cesium.SingleTileImageryProvider({
+                url,
+                rectangle: opts.extent ? Cesium.Rectangle.fromDegrees(...opts.extent) : undefined,
+                credit: opts.credit || '',
+                ...opts
+            });
+
+        case LayerType.TERRAIN:
+            // fromUrl 返回 Promise，由 addProviderToViewer 统一 await
+            return Cesium.CesiumTerrainProvider.fromUrl(url, {
+                requestWaterMask: opts.requestWaterMask ?? false,
+                requestVertexNormals: opts.requestVertexNormals ?? false,
+                ...opts
+            });
+
+        case LayerType['3DTILES']:
+            return new Cesium.Cesium3DTileset({
+                url,
+                maximumScreenSpaceError: opts.maximumScreenSpaceError ?? 16,
+                maximumMemoryUsage: opts.maximumMemoryUsage ?? 512,
+                ...opts
+            });
+
+        default:
+            throw new Error(`SceneModule: 不支持的图层类型 "${type}"，可用值: ${Object.values(LayerType).join(', ')}`);
+    }
+}
+
+/**
+ * 将 Provider 添加到 Viewer 并返回句柄
+ * terrain 类型返回 provider 自身（不是 layer）
+ * 3dtiles 类型返回 tileset
+ * 其余返回 ImageryLayer
+ * @param {string} type    LayerType
+ * @param {Object} viewer  Cesium.Viewer
+ * @param {Object} providerType Cesium Provider
+ * @param {boolean} visible 是否可见
+ * @returns {Object} layer/tileset/provider
+ */
+async function addProviderToViewer(type, viewer, providerType, visible) {
+    if (type === LayerType.TERRAIN) {
+        const provider = await providerType
+        viewer.terrainProvider = provider;
+        return provider;
+    }
+    if (type === LayerType['3DTILES']) {
+        const tileset = viewer.scene.primitives.add(providerType);
+        tileset.show = visible ?? true;
+        return tileset;
+    }
+    const layer = viewer.imageryLayers.addImageryProvider(providerType);
+    layer.show = visible ?? true;
+    return layer;
+}
+
+
+// ========== 图层包装器 ==========
+
+/**
+ * 影像图层包装器
+ */
+class ImageryLayerWrapper {
+    constructor(sceneModule, layer, layerId) {
+        this._layer = layer;
+        this._sceneModule = sceneModule;
+        this._layerId = layerId;
+        this._pickable = true;
+        this._eventEnabled = true;
+    }
+
+    setVisible(visible) {
+        this._layer.show = visible;
+        return this;
+    }
+
+    setAlpha(alpha) {
+        this._layer.alpha = alpha;
+        return this;
+    }
+
+    setBrightness(brightness) {
+        this._layer.brightness = brightness;
+        return this;
+    }
+
+    setContrast(contrast) {
+        this._layer.contrast = contrast;
+        return this;
+    }
+
+    setHue(hue) {
+        this._layer.hue = hue;
+        return this;
+    }
+
+    setSaturation(saturation) {
+        this._layer.saturation = saturation;
+        return this;
+    }
+
+    setGamma(gamma) {
+        this._layer.gamma = gamma;
+        return this;
+    }
+
+    enableEdit(enabled) {
+        this._pickable = enabled;
+        return this;
+    }
+
+    enableEvent(enabled) {
+        this._eventEnabled = enabled;
+        if (this._layer.imageryProvider && this._layer.imageryProvider.enablePickFeatures) {
+            this._layer.imageryProvider.enablePickFeatures = enabled;
+        }
+        return this;
+    }
+
+    getExtent() {
+        const provider = this._layer.imageryProvider;
+        if (provider && provider.rectangle) {
+            const rect = provider.rectangle;
+            return {
+                west: Cesium.Math.toDegrees(rect.west),
+                south: Cesium.Math.toDegrees(rect.south),
+                east: Cesium.Math.toDegrees(rect.east),
+                north: Cesium.Math.toDegrees(rect.north)
+            };
+        }
+        return null;
+    }
+
+    getRange() {
+        const provider = this._layer.imageryProvider;
+        return {
+            minLevel: provider.minimumLevel || 0,
+            maxLevel: provider.maximumLevel || 18
+        };
+    }
+
+    getLayer() {
+        return this._layer;
+    }
+
+    remove() {
+        this._sceneModule.removeLayer(this._layerId);
+        return this;
+    }
+}
+
+/**
+ * 地形图层包装器
+ */
+class TerrainLayerWrapper {
+    constructor(sceneModule, provider, layerId) {
+        this._provider = provider;
+        this._sceneModule = sceneModule;
+        this._layerId = layerId;
+        this._visible = true;
+    }
+
+    setVisible(visible) {
+        this._visible = visible;
+        return this;
+    }
+
+    getExtent() {
+        if (this._provider.rectangle) {
+            const rect = this._provider.rectangle;
+            return {
+                west: Cesium.Math.toDegrees(rect.west),
+                south: Cesium.Math.toDegrees(rect.south),
+                east: Cesium.Math.toDegrees(rect.east),
+                north: Cesium.Math.toDegrees(rect.north)
+            };
+        }
+        return { west: -180, south: -85, east: 180, north: 85 };
+    }
+
+    getProvider() {
+        return this._provider;
+    }
+
+    remove() {
+        this._sceneModule.removeLayer(this._layerId);
+        return this;
+    }
+}
+
+/**
+ * 3DTiles 图层包装器
+ */
+class TilesetLayerWrapper {
+    constructor(sceneModule, tileset, layerId) {
+        this._tileset = tileset;
+        this._sceneModule = sceneModule;
+        this._layerId = layerId;
+    }
+
+    setVisible(visible) {
+        this._tileset.show = visible;
+        return this;
+    }
+
+    setStyle(style) {
+        this._tileset.style = style;
+        return this;
+    }
+
+    getExtent() {
+        if (this._tileset.boundingSphere) {
+            const bs = this._tileset.boundingSphere;
+            const cartographic = Cesium.Cartographic.fromCartesian(bs.center);
+            const rect = this._tileset.rectangle;
+            if (rect) {
+                return {
+                    west: Cesium.Math.toDegrees(rect.west),
+                    south: Cesium.Math.toDegrees(rect.south),
+                    east: Cesium.Math.toDegrees(rect.east),
+                    north: Cesium.Math.toDegrees(rect.north),
+                    center: [
+                        Cesium.Math.toDegrees(cartographic.longitude),
+                        Cesium.Math.toDegrees(cartographic.latitude)
+                    ]
+                };
+            }
+        }
+        return null;
+    }
+
+    locateTo() {
+        return this._sceneModule.viewer.zoomTo(this._tileset);
+    }
+
+    getTileset() {
+        return this._tileset;
+    }
+
+    remove() {
+        this._sceneModule.removeLayer(this._layerId);
+        return this;
+    }
+}
+
+
+// ========== SceneModule ==========
+
+/**
+ * 场景+图层管理模块
+ */
+export class SceneModule {
+    constructor(viewer) {
+        this.viewer = viewer;
+        this.config = Config.getInstance().getConfig();
+        this.layerMap = new Map(); // 图层缓存（ID -> Wrapper 实例）
+    }
+
+    // ========== 坐标转换 ==========
+
+    lonLatToWorld(lon, lat, height = 0) {
+        return Cesium.Cartesian3.fromDegrees(lon, lat, height);
+    }
+
+    worldToLonLat(cartesian) {
+        const cartographic = Cesium.Cartographic.fromCartesian(cartesian);
+        return [
+            Cesium.Math.toDegrees(cartographic.longitude),
+            Cesium.Math.toDegrees(cartographic.latitude),
+            cartographic.height
+        ];
+    }
+
+    screenToWorld(x, y) {
+        const screenPosition = new Cesium.Cartesian2(x, y);
+        if (this.viewer.scene.pickPositionSupported) {
+            const precisePosition = this.viewer.scene.pickPosition(screenPosition);
+            if (precisePosition) return precisePosition;
+        }
+        const ray = this.viewer.camera.getPickRay(screenPosition);
+        const globePosition = this.viewer.scene.globe.pick(ray, this.viewer.scene);
+        if (globePosition) return globePosition;
+        return this.viewer.camera.pickEllipsoid(screenPosition, Cesium.Ellipsoid.WGS84);
+    }
+
+    worldToScreen(cartesian) {
+        return this.viewer.scene.cartesianToCanvasCoordinates(cartesian);
+    }
+
+    screenToLonLat(x, y) {
+        const worldCoord = this.screenToWorld(x, y);
+        return worldCoord ? this.worldToLonLat(worldCoord) : null;
+    }
+
+    lonLatToScreen(lon, lat, height = 0) {
+        const worldCoord = this.lonLatToWorld(lon, lat, height);
+        return this.worldToScreen(worldCoord);
+    }
+
+    lonLatToCartographic(lon, lat, height = 0) {
+        return new Cesium.Cartographic(Cesium.Math.toRadians(lon), Cesium.Math.toRadians(lat), height);
+    }
+
+    cartographicToLonLat(cartographic) {
+        return [
+            Cesium.Math.toDegrees(cartographic.longitude),
+            Cesium.Math.toDegrees(cartographic.latitude),
+            cartographic.height
+        ];
+    }
+
+    // ========== 统一图层工厂 ==========
+
+    /**
+     * 通用图层创建工厂（自动从 URL 推断类型）
+     * @param {string} url          服务地址
+     * @param {Object} [options={}] 配置选项
+     * @param {string} [options.type]               强制指定图层类型，见 {@link LayerType}，不提供则自动推断
+     * @param {string} [options.layerId]             图层唯一 ID，不提供则自动生成
+     * @param {boolean} [options.visible=true]       是否可见
+     * @param {number} [options.minimumLevel=0]      最小层级
+     * @param {number} [options.maximumLevel=18]     最大层级
+     * @param {string} [options.credit='']          版权信息
+     * @param {Array<number>} [options.extent]       范围 [west, south, east, north]（单张影像用）
+     * @param {string} [options.layer]               WMTS 层名
+     * @param {string} [options.style]               WMTS 样式
+     * @param {string} [options.format]              WMTS 格式
+     * @param {string} [options.tileMatrixSetID]     WMTS 瓦片矩阵集
+     * @param {string} [options.layers]              WMS 图层名
+     * @param {Object} [options.parameters]          WMS 额外参数
+     * @param {boolean} [options.requestWaterMask]        地形请求水面遮罩
+     * @param {boolean} [options.requestVertexNormals]    地形请求顶点法线
+     * @param {number} [options.maximumScreenSpaceError]  3DTiles 最大屏幕空间误差
+     * @param {number} [options.maximumMemoryUsage]        3DTiles 最大内存占用（MB）
+     * @param {boolean} [options.autoLocate=true]          3DTiles 创建后自动定位
+     * @returns {ImageryLayerWrapper|TerrainLayerWrapper|TilesetLayerWrapper} 图层包装器
+     * @example
+     * // 自动推断类型（推荐）
+     * sceneModule.createLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', { layerId: 'osm' });
+     * sceneModule.createLayer('https://example.com/tileset.json');
+     * sceneModule.createLayer('https://example.com/terrain');
+     *
+     * // 显式指定类型（覆盖自动推断）
+     * sceneModule.createLayer('https://example.com/wmts', { type: LayerType.WMTS, layer: 'vec' });
+     */
+    async createLayer(url, options = {}) {
+        const type = options.type ?? autoDetectType(url);
+        const layerId = options.layerId || `${type}_${Date.now()}`;
+
+        if (this.layerMap.has(layerId)) {
+            console.warn(`图层 ${layerId} 已存在`);
+            return this.layerMap.get(layerId);
+        }
+
+        const visible = options.visible !== false;
+        const provider = createProviderByType(type, url, options);
+        const layerOrEntity = await addProviderToViewer(type, this.viewer, provider, visible);
+        const wrapper = this.#wrapLayer(type, layerOrEntity, layerId);
+
+        // 3DTiles 自动定位（readyPromise 已移除，改用 initialTilesLoaded 一次性事件）
+        if (type === LayerType['3DTILES'] && options.autoLocate !== false) {
+            const removeListener = layerOrEntity.initialTilesLoaded.addEventListener(() => {
+                removeListener();
+                this.viewer.zoomTo(layerOrEntity);
+            });
+        }
+
+        this.layerMap.set(layerId, wrapper);
+        console.log(`${type} 图层 ${layerId} 创建成功`);
+        return wrapper;
+    }
+
+    /** 根据类型实例化对应包装器 */
+    #wrapLayer(type, layerOrEntity, layerId) {
+        if (type === LayerType.TERRAIN) {
+            return new TerrainLayerWrapper(this, layerOrEntity, layerId);
+        }
+        if (type === LayerType['3DTILES']) {
+            return new TilesetLayerWrapper(this, layerOrEntity, layerId);
+        }
+        return new ImageryLayerWrapper(this, layerOrEntity, layerId);
+    }
+
+    // ========== 图层管理 ==========
+
+    /**
+     * 删除图层
+     * @param {string} layerId 图层 ID
+     * @returns {boolean} 是否删除成功
+     */
+    removeLayer(layerId) {
+        if (!this.layerMap.has(layerId)) {
+            console.warn(`图层 ${layerId} 不存在`);
+            return false;
+        }
+
+        const layer = this.layerMap.get(layerId);
+
+        if (layer instanceof ImageryLayerWrapper) {
+            this.viewer.imageryLayers.remove(layer.getLayer());
+        } else if (layer instanceof TerrainLayerWrapper) {
+            // 地形无法直接删除，重置为默认椭球地形
+            this.viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider();
+        } else if (layer instanceof TilesetLayerWrapper) {
+            this.viewer.scene.primitives.remove(layer.getTileset());
+        }
+
+        this.layerMap.delete(layerId);
+        return true;
+    }
+
+    /**
+     * 获取图层
+     * @param {string} layerId 图层 ID
+     * @returns {ImageryLayerWrapper|TerrainLayerWrapper|TilesetLayerWrapper|undefined}
+     */
+    getLayer(layerId) {
+        return this.layerMap.get(layerId);
+    }
+
+    // ========== 场景定位 ==========
+
+    /**
+     * 相机飞到指定经纬度
+     * @param {Object} params 飞行参数
+     * @param {number} params.lon       经度
+     * @param {number} params.lat       纬度
+     * @param {number} [params.height=2000]   相机高度
+     * @param {number} [params.heading=0]      偏航角
+     * @param {number} [params.pitch=-90]      俯仰角
+     * @param {number} [params.roll=0]          翻滚角
+     * @param {number} [params.duration=3.0]   飞行时长（秒）
+     * @returns {Promise<boolean>}
+     */
+    flyToLonLat(params = {}) {
+        const {
+            lon, lat,
+            height = 2000,
+            heading = 0,
+            pitch = -90,
+            roll = 0,
+            duration = 3.0
+        } = params;
+
+        if (!Cesium.defined(lon) || !Cesium.defined(lat)) {
+            console.warn('flyToLonLat: 必须提供 lon、lat');
+            return Promise.resolve(false);
+        }
+
+        return this.viewer.camera.flyTo({
+            destination: Cesium.Cartesian3.fromDegrees(lon, lat, height),
+            orientation: {
+                heading: Cesium.Math.toRadians(heading),
+                pitch: Cesium.Math.toRadians(pitch),
+                roll: Cesium.Math.toRadians(roll)
+            },
+            duration
+        });
+    }
+
+    /**
+     * 设置相机视角（立即跳转，无飞行动画）
+     * @param {Object} params
+     * @param {number} params.lon       经度
+     * @param {number} params.lat       纬度
+     * @param {number} [params.height=500]    相机高度
+     * @param {number} [params.heading=0]      偏航角（默认北向）
+     * @param {number} [params.pitch=-90]       俯仰角（默认俯视）
+     * @param {number} [params.roll=0]         翻滚角
+     */
+    setView(params = {}) {
+        const {
+            lon, lat,
+            height = 500,
+            heading = 0,
+            pitch = -90,
+            roll = 0
+        } = params;
+
+        if (!Cesium.defined(lon) || !Cesium.defined(lat)) {
+            console.warn('setView: 必须提供 lon、lat');
+            return;
+        }
+
+        this.viewer.camera.setView({
+            destination: Cesium.Cartesian3.fromDegrees(lon, lat, height),
+            orientation: {
+                heading: Cesium.Math.toRadians(heading),
+                pitch: Cesium.Math.toRadians(pitch),
+                roll: Cesium.Math.toRadians(roll)
+            }
+        });
+    }
+}