cesium-xs-sdk 1.0.0

package/src/modules/tools/SelectTool.js

@@ -0,0 +1,526 @@
+import { BaseTool } from './BaseTool.js';
+
+/**
+ * 选择类型枚举
+ */
+export const SelectType = {
+  POINT: 'point',       // 点选
+  RECTANGLE: 'rectangle', // 矩形框选
+  CIRCLE: 'circle'        // 圆形框选
+};
+
+/**
+ * 选择工具
+ * 支持点选和框选（矩形、圆形）
+ */
+export class SelectTool extends BaseTool {
+  constructor(editorModule, options = {}) {
+    super(editorModule, options);
+    this._selectType = options.selectType || SelectType.POINT;
+    this._isSelecting = false;
+    this._startPos = null;
+    this._tempEntities = [];
+    this._selectedIds = new Set();
+    this._selectionRect = null;
+    this._originalStyles = new Map(); // 记录选中前的原始样式
+  }
+
+  /**
+   * 设置选择类型
+   * @param {string} type SelectType
+   */
+  setSelectType(type) {
+    this._selectType = type;
+    return this;
+  }
+
+  getSelectType() {
+    return this._selectType;
+  }
+
+  onActivate() {
+    this.registerObserver('mouse:click', this._onClick.bind(this));
+    this.registerObserver('mouse:move', this._onMove.bind(this));
+    this.registerObserver('mouse:down', this._onMouseDown.bind(this));
+    this.registerObserver('mouse:up', this._onMouseUp.bind(this));
+  }
+
+  onDeactivate() {
+    this._cancelSelection();
+    this._clearSelectionRect();
+  }
+
+  _onMouseDown(data) {
+    // mouse:down passes movement object from BaseTool
+    const screenPos = data.position || data.endPosition;
+    if (!screenPos) return;
+
+    if (this._selectType !== SelectType.POINT) {
+      const lonLat = this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
+      if (lonLat) {
+        this._startPos = lonLat;
+        this._isSelecting = true;
+        this._createSelectionStartMarker(lonLat);
+      }
+    }
+  }
+
+  _onMouseUp(data) {
+    const screenPos = data.position || data.endPosition;
+    if (!screenPos) return;
+
+    if (this._isSelecting && this._startPos) {
+      const lonLat = this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
+      if (lonLat) {
+        this._finishSelection(lonLat);
+      }
+    }
+  }
+
+  _onClick(_lngLat, _entity, movement) {
+    if (this._selectType !== SelectType.POINT) return;
+
+    const screenPos = movement.position || (movement && movement.endPosition);
+    if (!screenPos) return;
+
+    const picked = this._viewer.scene.pick({ x: screenPos.x, y: screenPos.y });
+
+    if (Cesium.defined(picked) && Cesium.defined(picked.id)) {
+      const entityId = picked.id.id;
+
+      // 忽略临时图元
+      if (entityId && entityId.startsWith('__temp_')) return;
+      if (entityId && entityId.startsWith('__edit_handle_')) return;
+
+      if (this._isSelected(entityId)) {
+        this._deselect(entityId);
+      } else {
+        this._select(entityId);
+      }
+    } else {
+      // 点击空白处，清除所有选择
+      this._clearAllSelections();
+    }
+  }
+
+  _onMove(data) {
+    // mouse:move passes movement object from BaseTool
+    const screenPos = data.position || data.endPosition;
+    if (!screenPos) return;
+
+    if (!this._isSelecting || !this._startPos) return;
+
+    const lonLat = this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
+    if (!lonLat) return;
+
+    this._updateSelectionRectPreview(lonLat);
+
+    // 实时框选
+    if (this._selectType === SelectType.RECTANGLE) {
+      const insideIds = this._getEntitiesInRectangle(this._startPos, lonLat);
+      this._highlightEntitiesInSelection(insideIds);
+    } else if (this._selectType === SelectType.CIRCLE) {
+      const insideIds = this._getEntitiesInCircle(this._startPos, lonLat);
+      this._highlightEntitiesInSelection(insideIds);
+    }
+  }
+
+  _createSelectionStartMarker(pos) {
+    const marker = this.createTempEntity(this.generateId('sel_start'), {
+      position: Cesium.Cartesian3.fromDegrees(...pos),
+      point: {
+        color: Cesium.Color.GREEN,
+        pixelSize: 10
+      }
+    });
+    this._tempEntities.push(marker);
+  }
+
+  _updateSelectionRectPreview(currentPos) {
+    if (this._selectType === SelectType.RECTANGLE) {
+      this._updateRectPreview(currentPos);
+    } else if (this._selectType === SelectType.CIRCLE) {
+      this._updateCirclePreview(currentPos);
+    }
+  }
+
+  _updateRectPreview(currentPos) {
+    const corner1 = this._startPos;
+    const corner2 = currentPos;
+
+    if (!corner1 || !corner2) return;
+
+    if (!this._selectionRect) {
+      this._selectionRect = this.createTempEntity(this.generateId('sel_rect'), {
+        polyline: {
+          positions: new Cesium.CallbackProperty(() => {
+            const pos = this._getRectPositions(corner1, corner2);
+            return Cesium.Cartesian3.fromDegreesArrayHeights(pos.flatMap(c => [c[0], c[1], 0]));
+          }, false),
+          material: Cesium.Color.CYAN,
+          width: 2
+        },
+        polygon: {
+          hierarchy: new Cesium.CallbackProperty(() => {
+            const pos = this._getRectPositions(corner1, corner2);
+            return new Cesium.PolygonHierarchy(
+              Cesium.Cartesian3.fromDegreesArrayHeights(pos.flatMap(c => [c[0], c[1], 0]))
+            );
+          }, false),
+          material: Cesium.Color.CYAN.withAlpha(0.2),
+          outline: false
+        }
+      });
+      this._selectionRect._isPreview = true;
+      this._tempEntities.push(this._selectionRect);
+    }
+  }
+
+  _updateCirclePreview(currentPos) {
+    const center = this._startPos;
+
+    if (!center || !currentPos) return;
+
+    if (!this._selectionRect) {
+      this._selectionRect = this.createTempEntity(this.generateId('sel_circle'), {
+        polygon: {
+          hierarchy: new Cesium.CallbackProperty(() => {
+            const radius = this._calcDistance(center, currentPos);
+            const positions = this._generateCirclePositions(center, radius, 36);
+            return new Cesium.PolygonHierarchy(
+              Cesium.Cartesian3.fromDegreesArrayHeights(
+                positions.flatMap(c => [c[0], c[1], 0])
+              )
+            );
+          }, false),
+          material: Cesium.Color.CYAN.withAlpha(0.2),
+          outline: true,
+          outlineColor: Cesium.Color.CYAN
+        }
+      });
+      this._selectionRect._isPreview = true;
+      this._tempEntities.push(this._selectionRect);
+    }
+  }
+
+  _getRectPositions(corner1, corner2) {
+    return [
+      [corner1[0], corner1[1]],
+      [corner2[0], corner1[1]],
+      [corner2[0], corner2[1]],
+      [corner1[0], corner2[1]],
+      [corner1[0], corner1[1]]
+    ];
+  }
+
+  _clearSelectionRect() {
+    this._tempEntities.forEach(entity => {
+      if (entity._isPreview) {
+        this.removeTempEntity(entity);
+      }
+    });
+    this._tempEntities = this._tempEntities.filter(e => !e._isPreview);
+    this._selectionRect = null;
+  }
+
+  _finishSelection(endPos) {
+    let selectedIds = [];
+
+    if (this._selectType === SelectType.RECTANGLE) {
+      selectedIds = this._getEntitiesInRectangle(this._startPos, endPos);
+    } else if (this._selectType === SelectType.CIRCLE) {
+      selectedIds = this._getEntitiesInCircle(this._startPos, endPos);
+    }
+
+    // 框选模式：选中框内所有图元
+    selectedIds.forEach(id => {
+      this._select(id, false); // 不触发事件
+    });
+
+    this._cancelSelection();
+    this._emitSelectionComplete(Array.from(this._selectedIds));
+  }
+
+  _cancelSelection() {
+    this._isSelecting = false;
+    this._startPos = null;
+    this._isSelecting = false;
+    this._selectionRect = null;
+    this._tempEntities.forEach(entity => {
+      this.removeTempEntity(entity);
+    });
+    this._tempEntities = [];
+  }
+
+  _select(entityId, emitEvent = true) {
+    if (this._selectedIds.has(entityId)) return;
+
+    this._selectedIds.add(entityId);
+    this._highlightEntity(entityId, true);
+
+    if (emitEvent) {
+      this._emitSelect(entityId);
+    }
+  }
+
+  _deselect(entityId) {
+    if (!this._selectedIds.has(entityId)) return;
+
+    this._selectedIds.delete(entityId);
+    this._highlightEntity(entityId, false);
+  }
+
+  _clearAllSelections() {
+    this._selectedIds.forEach(id => {
+      this._highlightEntity(id, false);
+    });
+    this._selectedIds.clear();
+    this._emitSelectionChange([]);
+  }
+
+  _highlightEntity(entityId, highlight) {
+    const entity = this._graphicModule.getGraphic(entityId);
+    if (!entity) return;
+
+    const styleKey = entityId;
+
+    if (Cesium.defined(entity.point)) {
+      if (highlight) {
+        if (!this._originalStyles.has(styleKey)) {
+          this._originalStyles.set(styleKey, {
+            point: {
+              outlineColor: entity.point.outlineColor,
+              outlineWidth: entity.point.outlineWidth
+            }
+          });
+        }
+        entity.point.outlineColor = Cesium.Color.YELLOW;
+        entity.point.outlineWidth = 2;
+      } else {
+        const original = this._originalStyles.get(styleKey)?.point;
+        if (original) {
+          entity.point.outlineColor = original.outlineColor;
+          entity.point.outlineWidth = original.outlineWidth;
+        } else {
+          entity.point.outlineColor = Cesium.Color.WHITE;
+          entity.point.outlineWidth = 1;
+        }
+      }
+    }
+
+    if (Cesium.defined(entity.polyline)) {
+      if (highlight) {
+        if (!this._originalStyles.has(styleKey)) {
+          this._originalStyles.set(styleKey, {
+            polyline: {
+              material: entity.polyline.material
+            }
+          });
+        }
+        entity.polyline.material = Cesium.Color.CYAN;
+      } else {
+        const original = this._originalStyles.get(styleKey)?.polyline;
+        entity.polyline.material = original?.material || Cesium.Color.BLUE;
+      }
+    }
+
+    if (Cesium.defined(entity.polygon)) {
+      if (highlight) {
+        if (!this._originalStyles.has(styleKey)) {
+          this._originalStyles.set(styleKey, {
+            polygon: {
+              outlineColor: entity.polygon.outlineColor
+            }
+          });
+        }
+        entity.polygon.outlineColor = Cesium.Color.CYAN;
+      } else {
+        const original = this._originalStyles.get(styleKey)?.polygon;
+        entity.polygon.outlineColor = original?.outlineColor || Cesium.Color.WHITE;
+      }
+    }
+
+    if (!highlight) {
+      this._originalStyles.delete(styleKey);
+    }
+  }
+
+  _highlightEntitiesInSelection(entityIds) {
+    // 先取消所有选择的高亮
+    this._selectedIds.forEach(id => {
+      if (!entityIds.includes(id)) {
+        this._highlightEntity(id, false);
+        this._selectedIds.delete(id);
+      }
+    });
+
+    // 高亮框内图元
+    entityIds.forEach(id => {
+      if (!this._selectedIds.has(id)) {
+        this._selectedIds.add(id);
+        this._highlightEntity(id, true);
+      }
+    });
+  }
+
+  _getOriginalColor(entity) {
+    // 已废弃：原始样式由 _originalStyles 统一维护
+    return null;
+  }
+
+  _getEntitiesInRectangle(corner1, corner2) {
+    const minLon = Math.min(corner1[0], corner2[0]);
+    const maxLon = Math.max(corner1[0], corner2[0]);
+    const minLat = Math.min(corner1[1], corner2[1]);
+    const maxLat = Math.max(corner1[1], corner2[1]);
+
+    const allIds = this._getAllGraphicIds();
+    return this._filterEntitiesInBounds(allIds, minLon, maxLon, minLat, maxLat);
+  }
+
+  _getEntitiesInCircle(center, edge) {
+    const radius = this._calcDistance(center, edge);
+    const allIds = this._getAllGraphicIds();
+    const result = [];
+
+    allIds.forEach(id => {
+      const entity = this._graphicModule.getGraphic(id);
+      if (!entity) return;
+
+      const entityPos = this._getEntityPosition(entity);
+      if (!entityPos) return;
+
+      const distance = this._calcDistance(center, entityPos);
+      if (distance <= radius) {
+        result.push(id);
+      }
+    });
+
+    return result;
+  }
+
+  _getAllGraphicIds() {
+    // 从 GraphicModule 获取所有图元 ID
+    const ids = [];
+    this._graphicModule.graphicMap.forEach((entity, id) => {
+      if (!id.startsWith('__temp_') && !id.startsWith('__edit_handle_')) {
+        ids.push(id);
+      }
+    });
+    return ids;
+  }
+
+  _filterEntitiesInBounds(ids, minLon, maxLon, minLat, maxLat) {
+    const result = [];
+
+    ids.forEach(id => {
+      const entity = this._graphicModule.getGraphic(id);
+      if (!entity) return;
+
+      const positions = this._getEntityPositions(entity);
+      if (!positions || positions.length === 0) return;
+
+      // 检查是否所有点都在范围内
+      let allInBounds = true;
+      for (const pos of positions) {
+        const c = Cesium.Cartographic.fromCartesian(pos);
+        const lon = Cesium.Math.toDegrees(c.longitude);
+        const lat = Cesium.Math.toDegrees(c.latitude);
+
+        if (lon < minLon || lon > maxLon || lat < minLat || lat > maxLat) {
+          allInBounds = false;
+          break;
+        }
+      }
+
+      if (allInBounds) {
+        result.push(id);
+      }
+    });
+
+    return result;
+  }
+
+  _getEntityPosition(entity) {
+    if (Cesium.defined(entity.position)) {
+      const pos = entity.position.getValue(Cesium.JulianDate.now());
+      if (pos) {
+        const c = Cesium.Cartographic.fromCartesian(pos);
+        return [
+          Cesium.Math.toDegrees(c.longitude),
+          Cesium.Math.toDegrees(c.latitude)
+        ];
+      }
+    }
+    return null;
+  }
+
+  _getEntityPositions(entity) {
+    if (Cesium.defined(entity.polyline) && Cesium.defined(entity.polyline.positions)) {
+      return entity.polyline.positions.getValue(Cesium.JulianDate.now());
+    }
+    if (Cesium.defined(entity.polygon) && Cesium.defined(entity.polygon.hierarchy)) {
+      const hierarchy = entity.polygon.hierarchy.getValue(Cesium.JulianDate.now());
+      return hierarchy ? hierarchy.positions : [];
+    }
+    return [];
+  }
+
+  _calcDistance(coord1, coord2) {
+    const earthRadius = 6371000;
+    const [lon1, lat1] = coord1.map(d => d * Math.PI / 180);
+    const [lon2, lat2] = coord2.map(d => d * Math.PI / 180);
+
+    const dLat = lat2 - lat1;
+    const dLon = lon2 - lon1;
+
+    const a = Math.sin(dLat / 2) ** 2 +
+              Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+
+    return earthRadius * c;
+  }
+
+  _generateCirclePositions(center, radius, segments) {
+    const positions = [];
+    const [lon, lat] = center;
+    const radPerDeg = Math.PI / 180;
+
+    for (let i = 0; i <= segments; i++) {
+      const angle = (i / segments) * Math.PI * 2;
+      const dLon = (radius / 111320) * Math.cos(angle) / radPerDeg;
+      const dLat = (radius / 110540) / radPerDeg;
+      positions.push([lon + dLon, lat + dLat]);
+    }
+    return positions;
+  }
+
+  _isSelected(entityId) {
+    return this._selectedIds.has(entityId);
+  }
+
+  /**
+   * 获取当前所有选中的图元 ID
+   */
+  getSelectedIds() {
+    return Array.from(this._selectedIds);
+  }
+
+  _emitSelect(entityId) {
+    if (this._options.onSelect) {
+      this._options.onSelect({ entityId });
+    }
+  }
+
+  _emitSelectionChange(ids) {
+    if (this._options.onSelectionChange) {
+      this._options.onSelectionChange({ selectedIds: ids });
+    }
+  }
+
+  _emitSelectionComplete(ids) {
+    if (this._options.onSelectionComplete) {
+      this._options.onSelectionComplete({ selectedIds: ids });
+    }
+  }
+}

package/src/react.d.ts

@@ -0,0 +1,18 @@
+import type { ModuleManager, SceneModule, GraphicModule, EventModule, EditorModule } from './index.js';
+
+export interface UseXs3dResult {
+  sdk: ModuleManager | null;
+  viewer: any;
+  sceneModule: SceneModule | null;
+  graphicModule: GraphicModule | null;
+  eventModule: EventModule | null;
+  editorModule: EditorModule | null;
+  isReady: boolean;
+}
+
+export function useXs3d(
+  containerId: string,
+  options?: Record<string, any>
+): UseXs3dResult;
+
+export default useXs3d;

package/src/react.js

@@ -0,0 +1,49 @@
+/**
+ * React 适配器
+ * 提供 useXs3d Hook，管理 SDK 初始化与销毁生命周期
+ */
+import { useEffect, useRef, useState } from 'react';
+import xs3d from './index.js';
+
+/**
+ * 在 React 组件中使用 XS 3D SDK
+ * @param {string} containerId 容器元素 ID
+ * @param {Object} options 初始化配置（同 xs3d.init）
+ * @returns {Object}
+ *   - sdk: SDK 根实例
+ *   - viewer: Cesium Viewer
+ *   - sceneModule, graphicModule, eventModule, editorModule: 各模块
+ *   - isReady: 是否初始化完成
+ */
+export function useXs3d(containerId, options = {}) {
+  const sdkRef = useRef(null);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    if (!containerId || typeof window === 'undefined') {
+      return;
+    }
+
+    const instance = xs3d.init(containerId, options);
+    sdkRef.current = instance;
+    setIsReady(true);
+
+    return () => {
+      xs3d.destroy();
+      sdkRef.current = null;
+      setIsReady(false);
+    };
+  }, [containerId, JSON.stringify(options)]);
+
+  return {
+    sdk: sdkRef.current,
+    viewer: sdkRef.current?.viewer ?? null,
+    sceneModule: sdkRef.current?.sceneModule ?? null,
+    graphicModule: sdkRef.current?.graphicModule ?? null,
+    eventModule: sdkRef.current?.eventModule ?? null,
+    editorModule: sdkRef.current?.editorModule ?? null,
+    isReady
+  };
+}
+
+export default useXs3d;

package/src/utils/CoordinateUtil.js

@@ -0,0 +1,63 @@
+/**
+ * 坐标转换工具（对齐平台 屏幕/世界/地理坐标转换）
+ */
+export class CoordinateUtil {
+    /**
+     * 坐标转换核心方法
+     * @param {Cesium.Viewer} viewer Cesium 实例
+     * @param {Cesium.Cartesian3|Array<number>} coord 源坐标
+     * @param {string} from 源类型（screen/world/scene）
+     * @param {string} to 目标类型（screen/world/scene）
+     * @returns {Cesium.Cartesian3|Cesium.Cartographic} 转换后坐标
+     */
+    static transform(viewer, coord, from, to) {
+        // 统一坐标格式
+        let sourceCoord = coord;
+        if (Array.isArray(coord)) {
+            if (from === 'scene') {
+                // 地理坐标转世界坐标
+                sourceCoord = Cesium.Cartesian3.fromDegrees(...coord);
+            } else if (from === 'world') {
+                sourceCoord = new Cesium.Cartesian3(coord[0], coord[1], coord[2]);
+            } else if (from === 'screen') {
+                // 屏幕坐标数组需先转为 Cartesian2
+                sourceCoord = new Cesium.Cartesian2(coord[0], coord[1]);
+            }
+        }
+
+        // 转换逻辑
+        switch (`${from}_${to}`) {
+            // 屏幕坐标 -> 世界坐标
+            case 'screen_world':
+                return viewer.camera.pickEllipsoid(sourceCoord);
+            // 屏幕坐标 -> 地理坐标
+            case 'screen_scene':
+                const worldCoord = viewer.camera.pickEllipsoid(sourceCoord);
+                const cartographic = Cesium.Cartographic.fromCartesian(worldCoord);
+                return [
+                    Cesium.Math.toDegrees(cartographic.longitude),
+                    Cesium.Math.toDegrees(cartographic.latitude),
+                    cartographic.height
+                ];
+            // 世界坐标 -> 屏幕坐标
+            case 'world_screen':
+                return Cesium.SceneTransforms.wgs84ToWindowCoordinates(viewer.scene, sourceCoord);
+            // 世界坐标 -> 地理坐标
+            case 'world_scene':
+                const carto = Cesium.Cartographic.fromCartesian(sourceCoord);
+                return [
+                    Cesium.Math.toDegrees(carto.longitude),
+                    Cesium.Math.toDegrees(carto.latitude),
+                    carto.height
+                ];
+            // 地理坐标 -> 世界坐标（已在入参处理）
+            case 'scene_world':
+                return sourceCoord;
+            // 地理坐标 -> 屏幕坐标
+            case 'scene_screen':
+                return Cesium.SceneTransforms.wgs84ToWindowCoordinates(viewer.scene, sourceCoord);
+            default:
+                return sourceCoord;
+        }
+    }
+}