cesium-xs-sdk 1.0.18 → 1.0.20

package/dist/cesium-xs-sdk.cjs.js

@@ -845,6 +845,24 @@ class SceneModule {
             }
         });
     }
+
+    /**
+     * 是否开启南北极轴约束
+     * 开启时（Cesium 默认行为）鼠标旋转/缩放无法让相机越过南北极点；
+     * 关闭时（viewer.camera.constrainedAxis = undefined）相机可穿越极点。
+     * @param {boolean} [enabled=true] true 开启约束，false 关闭约束
+     */
+    setPolarAxisConstraint(enabled = true) {
+        this.viewer.camera.constrainedAxis = enabled ? Cesium$h.Cartesian3.UNIT_Z : undefined;
+    }
+
+    /**
+     * 查询南北极轴约束是否开启
+     * @returns {boolean} true 已开启（相机不可穿越极点），false 已关闭
+     */
+    isPolarAxisConstraintEnabled() {
+        return Cesium$h.defined(this.viewer.camera.constrainedAxis);
+    }
 }
 
 const Cesium$g = getCesium();
@@ -2032,6 +2050,22 @@ function isLinePlotType(plotType) {
   ].includes(plotType);
 }
 
+/**
+ * 控制 SDK 内 LabelGraphics / BillboardGraphics / PointPrimitive 的
+ * disableDepthTestDistance 默认值。
+ *
+ * 语义：相机距离图元小于等于 distance（米）时不进行深度测试，
+ *      即近处观察时图元始终绘制在前景，避免被地形/建筑局部遮挡；
+ *      大于 distance 时恢复正常深度测试，避免地球背面透视。
+ *
+ * 默认 8000 米；可在运行时改写：
+ *   import { LabelDepthConfig } from 'cesium-xs-sdk'
+ *   LabelDepthConfig.distance = 4000
+ */
+const LabelDepthConfig = {
+  distance: 8000,
+};
+
 const Cesium$f = getCesium();
 
 /**
@@ -2069,7 +2103,7 @@ class PointWrapper {
   }
 
   setDisableDepthTestDistance(distance) {
-    this._entity.point.disableDepthTestDistance = distance;
+    this._entity.point.disableDepthTestDistance = LabelDepthConfig.distance;
     return this;
   }
 
@@ -2105,7 +2139,7 @@ class PointWrapper {
     this._entity.label.text = text;
 
     // 应用配置选项
-    this._entity.label.disableDepthTestDistance = options.disableDepthTestDistance ?? Number.POSITIVE_INFINITY;
+    this._entity.label.disableDepthTestDistance = options.disableDepthTestDistance ?? LabelDepthConfig.distance;
     this._entity.label.verticalOrigin = options.verticalOrigin ?? Cesium$f.VerticalOrigin.BOTTOM;
     this._entity.label.eyeOffset = options.eyeOffset ?? new Cesium$f.Cartesian3(0, 0, -10);
     this._entity.label.heightReference = options.heightReference ?? Cesium$f.HeightReference.RELATIVE_TO_GROUND;
@@ -2694,7 +2728,7 @@ class BillboardWrapper {
   }
 
   setDisableDepthTestDistance(distance) {
-    this._entity.billboard.disableDepthTestDistance = distance;
+    this._entity.billboard.disableDepthTestDistance = LabelDepthConfig.distance;
     return this;
   }
 
@@ -3635,6 +3669,9 @@ class BaseTool {
     this._handlers = []; // 注册的事件处理器 ID
     // 自维护双击判定器（DOM dblclick 在移动端经常不合成，见 DoubleClickDetector 注释）
     this._doubleClickDetector = new DoubleClickDetector();
+    // mousemove rAF 节流状态：多次 move 之间只保留最新一次，与 render 帧同步
+    this._moveRafId = null;
+    this._movePendingCb = null;
   }
 
   /**
@@ -3655,6 +3692,12 @@ class BaseTool {
     if (!this._isActive) return;
     this._isActive = false;
     this._doubleClickDetector.reset();
+    // 取消 pending 的 mousemove rAF，避免停用后仍执行预览逻辑
+    if (this._moveRafId != null) {
+      cancelAnimationFrame(this._moveRafId);
+      this._moveRafId = null;
+      this._movePendingCb = null;
+    }
     this.onDeactivate();
     this.clearHandlers();
   }
@@ -3690,17 +3733,36 @@ class BaseTool {
    */
   registerObserver(eventType, callback) {
     const observerId = this._eventModule.registerObserver(eventType, (lngLat, entity, movement) => {
-      // mouse:move 事件没有 lngLat，直接传递 movement 对象
-      if (eventType === 'mouse:move') {
-        callback(movement);
-      } else {
-        callback(lngLat, entity, movement);
-      }
+      // 统一转发：mouse:move 也带上 EventModule 已计算的 lngLat / pickedEntity，
+      // 避免工具层再调 scene.pickPosition / scene.pick 造成 2× 调用。
+      callback(lngLat, entity, movement);
     });
     this._handlers.push({ eventType, observerId });
     return observerId;
   }
 
+  /**
+   * 将高频 mousemove 处理合并到下一帧：多次调用之间只保留最新一次的回调，
+   * 与 Cesium render 帧对齐（~60Hz），避免全球视角下 pickPosition / CallbackProperty
+   * 在 100+ Hz 浏览器原生频率下成为热点。
+   *
+   * 使用方式（仅对"非交互关键 + 计算密集"的预览路径）：
+   *   this._scheduleMoveWork(() => this._updatePreview(this._mousePos));
+   *
+   * 注意：callback 应在闭包里读取 this 上的最新字段（_currentMousePos 等），
+   * 不要传参；参数会被合并掉的多次调用的中间值覆盖。
+   */
+  _scheduleMoveWork(callback) {
+    this._movePendingCb = callback;
+    if (this._moveRafId != null) return;
+    this._moveRafId = requestAnimationFrame(() => {
+      const cb = this._movePendingCb;
+      this._moveRafId = null;
+      this._movePendingCb = null;
+      if (cb) cb();
+    });
+  }
+
   /**
    * 清除所有已注册的事件处理器
    */
@@ -4059,39 +4121,66 @@ class DrawTool extends BaseTool {
     }
   }
 
-  _onMove(data) {
-    // mouse:move 事件的 movement 对象使用 endPosition
-    const screenPos = data.position || data.endPosition;
+  _onMove(lngLat, entity, movement) {
+    const screenPos = movement.position || movement.endPosition;
     if (!screenPos) return;
-    const lonLat = this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
+    // 优先使用 EventModule 已计算的 lngLat（避免重复 scene.pickPosition）；
+    // 拾取失败（如鼠标移到地球外）时回退到 screenToLonLat。
+    const lonLat = lngLat || this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
     if (!lonLat) return;
 
     this._currentMousePos = lonLat;
 
     if (this._drawType === DrawType.POINT) return;
 
+    // 预览几何更新是计算密集路径（CallbackProperty / 经纬度→ECEF / 标绘算法），
+    // 在全球视角下每帧都跑成本高，合并到下一帧（~60Hz），丢弃中间 move 事件。
+    this._scheduleMoveWork(() => this._applyPreviewUpdate());
+
+    // 鼠标光标类反馈保持同步（每次 mousemove 都要响应，不走 rAF 合并）
+    if (
+      (this._drawType === DrawType.LINE || this._drawType === DrawType.POLYGON) &&
+      this._isDrawing
+    ) {
+      this._updatePreviewCursor();
+    }
+  }
+
+  /**
+   * 真正执行预览更新：由 _scheduleMoveWork 在下一帧调用一次，读取
+   * this._currentMousePos / _startPos / _tempPositions 等最新字段。
+   */
+  _applyPreviewUpdate() {
+    const lonLat = this._currentMousePos;
+    if (!lonLat) return;
+
     // 标绘类型预览
     const plotConfig = PLOT_DRAW_CONFIG[this._drawType];
     if (plotConfig) {
       if (this._isDrawing && this._tempPositions.length >= plotConfig.minPoints - 1) {
-        this._updatePlotPreview(plotConfig, lonLat);
+        this._updatePlotPreview(plotConfig);
       }
       return;
     }
 
     if (this._isDrawing) {
       if (this._drawType === DrawType.LINE) {
-        this._updateTempLine(lonLat);
+        this._updateTempLine();
       } else if (this._drawType === DrawType.POLYGON) {
-        this._updateTempPolygon(lonLat);
+        this._updateTempPolygon();
       }
     }
 
     if (this._startPos) {
-      this._updateRectOrCirclePreview(lonLat);
+      this._updateRectOrCirclePreview();
     }
   }
 
+  _updatePreviewCursor() {
+    // 简化占位：原 _onMove 中没有显式 cursor 处理，保留 hook 以备后用。
+    // 真正的鼠标光标样式由 _onMove 主流程维护，这里无副作用。
+  }
+
   _onKeyDown(data) {
     // ESC 取消绘制
     if (data.key === 'Escape') {
@@ -4238,7 +4327,7 @@ class DrawTool extends BaseTool {
       .setScale(0.5)
       .setVerticalOrigin(Cesium$c.VerticalOrigin.BOTTOM)
       .setHeightReference(Cesium$c.HeightReference.CLAMP_TO_GROUND)
-      .setDisableDepthTestDistance(Number.POSITIVE_INFINITY);
+      .setDisableDepthTestDistance(LabelDepthConfig.distance);
 
     // 选择图片来源：自定义 URL 优先，否则使用 SDK 内置 base64 图标
     const imageSource = (typeof imgUrl === 'string' && imgUrl.trim() !== '')
@@ -4347,25 +4436,23 @@ class DrawTool extends BaseTool {
     }
   }
 
-  _updateTempLine(mousePos) {
-    // 构建预览线位置：已有位置 + 鼠标当前位置（跟随鼠标）
-    const previewPositions = [...this._tempPositions];
-    if (mousePos) {
-      previewPositions.push(mousePos);
-    }
-
-    // 计算 Cartesian3 数组
-    const flatCoords = [];
-    for (const c of previewPositions) {
-      flatCoords.push(c[0], c[1], c[2] || 0);
-    }
-    const cartesians = Cesium$c.Cartesian3.fromDegreesArrayHeights(flatCoords);
-
+  _updateTempLine() {
+    // 第一次创建时建立稳定的 CallbackProperty，回调内部读 this._tempPositions +
+    // this._currentMousePos（与 _updateTempPolygon 同模式），避免每次 move 都重建。
     if (!this._previewLine) {
       // 首次创建预览线（黑白相间的斑马纹路）
       this._previewLine = this.createTempEntity(this.generateId('temp_line'), {
         polyline: {
-          positions: cartesians,
+          positions: new Cesium$c.CallbackProperty(() => {
+            const previewPositions = [...this._tempPositions];
+            if (this._currentMousePos) previewPositions.push(this._currentMousePos);
+            if (previewPositions.length < 2) return [];
+            const flatCoords = [];
+            for (const c of previewPositions) {
+              flatCoords.push(c[0], c[1], c[2] || 0);
+            }
+            return Cesium$c.Cartesian3.fromDegreesArrayHeights(flatCoords);
+          }, false),
           material: new Cesium$c.PolylineDashMaterialProperty({
             color: Cesium$c.Color.WHITE,
             gapColor: Cesium$c.Color.BLACK,
@@ -4376,12 +4463,6 @@ class DrawTool extends BaseTool {
         }
       });
       this._tempEntities.push(this._previewLine);
-    } else {
-      // 直接更新位置属性，避免重建实体
-      // this._previewLine.polyline.positions = cartesians;
-      this._previewLine.polyline.positions = new Cesium$c.CallbackProperty(() => {
-        return cartesians;
-      }, false);
     }
   }
 
@@ -4429,116 +4510,87 @@ class DrawTool extends BaseTool {
     }
   }
 
-  _updateRectOrCirclePreview(currentLonLat) {
+  _updateRectOrCirclePreview() {
     if (!this._startPos) return;
 
     if (this._drawType === DrawType.RECTANGLE) {
-      this._updateRectPreview(currentLonLat);
+      this._updateRectPreview();
     } else if (this._drawType === DrawType.CIRCLE) {
-      this._updateCirclePreview(currentLonLat);
+      this._updateCirclePreview();
     }
   }
 
-  _updateRectPreview(currentLonLat) {
-    const corner1 = this._startPos;
-    const corner2 = currentLonLat;
-
-    // 计算矩形四个角
-    const positions = [
-      [corner1[0], corner1[1]],
-      [corner2[0], corner1[1]],
-      [corner2[0], corner2[1]],
-      [corner1[0], corner2[1]],
-      [corner1[0], corner1[1]]
-    ];
-
-    const flatCoords = [];
-    for (const c of positions) {
-      flatCoords.push(c[0], c[1], 0);
-    }
-    const cartesians = Cesium$c.Cartesian3.fromDegreesArrayHeights(flatCoords);
-
+  _updateRectPreview() {
+    // 第一次创建时建立稳定的 CallbackProperty，回调内部读 this._startPos / _currentMousePos，
+    // 避免每个 mousemove 都 new CallbackProperty + 重绑几何（参见 polygon preview 同模式）。
     if (!this._previewRect) {
+      const polylinePositions = new Cesium$c.CallbackProperty(() => this._computeRectCornersFlat(2), false);
+      const polygonHierarchy = new Cesium$c.CallbackProperty(() => {
+        const cartesians = this._computeRectCornersFlat(2);
+        return new Cesium$c.PolygonHierarchy(cartesians);
+      }, false);
       this._previewRect = this.createTempEntity(this.generateId('temp_rect'), {
         polyline: {
-          positions: new Cesium$c.CallbackProperty(() => cartesians, false),
+          positions: polylinePositions,
           material: Cesium$c.Color.YELLOW.withAlpha(0.7),
           width: 2
         },
         polygon: {
-          hierarchy: new Cesium$c.CallbackProperty(() => new Cesium$c.PolygonHierarchy(cartesians), false),
+          hierarchy: polygonHierarchy,
           material: Cesium$c.Color.YELLOW.withAlpha(0.2),
           outline: false
         }
       });
       this._previewRect._isPreview = true;
       this._tempEntities.push(this._previewRect);
-    } else {
-      // 直接更新位置属性
-      this._previewRect.polyline.positions = new Cesium$c.CallbackProperty(() => {
-        const c1 = this._startPos;
-        const c2 = this._currentMousePos;
-        if (!c1 || !c2) return cartesians;
-        const pos = [
-          [c1[0], c1[1]],
-          [c2[0], c1[1]],
-          [c2[0], c2[1]],
-          [c1[0], c2[1]],
-          [c1[0], c1[1]]
-        ];
-        const flat = [];
-        for (const p of pos) {
-          flat.push(p[0], p[1], 0);
-        }
-        return Cesium$c.Cartesian3.fromDegreesArrayHeights(flat);
-      }, false);
-      this._previewRect.polygon.hierarchy = new Cesium$c.CallbackProperty(() => {
-        const c1 = this._startPos;
-        const c2 = this._currentMousePos;
-        if (!c1 || !c2) return new Cesium$c.PolygonHierarchy(cartesians);
-        const pos = [
-          [c1[0], c1[1]],
-          [c2[0], c1[1]],
-          [c2[0], c2[1]],
-          [c1[0], c2[1]],
-          [c1[0], c1[1]]
-        ];
-        const flat = [];
-        for (const p of pos) {
-          flat.push(p[0], p[1], 0);
-        }
-        return new Cesium$c.PolygonHierarchy(Cesium$c.Cartesian3.fromDegreesArrayHeights(flat));
-      }, false);
     }
   }
 
-  _updateCirclePreview(currentLonLat) {
-    const center = this._startPos;
-    const radius = this._calcDistance(center, currentLonLat);
-    const segments = 64;
+  /**
+   * 计算矩形四个角点的 Cartesian3[]（含起末闭合点）：
+   *   [start, (currLon, startLat), curr, (startLon, currLat), start]
+   * 返回数组便于 polyline 与 polygon 共用；调用方负责包装 PolygonHierarchy。
+   */
+  _computeRectCornersFlat() {
+    const c1 = this._startPos;
+    const c2 = this._currentMousePos;
+    if (!c1 || !c2) {
+      return [Cesium$c.Cartesian3.fromDegrees(0, 0, 0)];
+    }
+    const flat = [
+      c1[0], c1[1], 0,
+      c2[0], c1[1], 0,
+      c2[0], c2[1], 0,
+      c1[0], c2[1], 0,
+      c1[0], c1[1], 0
+    ];
+    return Cesium$c.Cartesian3.fromDegreesArrayHeights(flat);
+  }
 
+  _updateCirclePreview() {
+    // 第一次创建时建立稳定的 CallbackProperty，回调内部读 this._startPos / _currentMousePos，
+    // 避免每个 mousemove 都 new CallbackProperty 并重建几何。
+    const segments = 64;
     if (!this._previewCircle) {
+      const hierarchy = new Cesium$c.CallbackProperty(() => {
+        const center = this._startPos;
+        const r = this._calcDistance(center, this._currentMousePos);
+        if (!center || !this._currentMousePos) {
+          return new Cesium$c.PolygonHierarchy([]);
+        }
+        const pos = this._generateCirclePositions(center, r, segments);
+        const flat = pos.flatMap(c => [c[0], c[1], 0]);
+        return new Cesium$c.PolygonHierarchy(Cesium$c.Cartesian3.fromDegreesArrayHeights(flat));
+      }, false);
       this._previewCircle = this.createTempEntity(this.generateId('temp_circle'), {
         polygon: {
-          hierarchy: new Cesium$c.CallbackProperty(() => {
-            const positions = this._generateCirclePositions(center, radius, segments);
-            const flat = positions.flatMap(c => [c[0], c[1], 0]);
-            return new Cesium$c.PolygonHierarchy(Cesium$c.Cartesian3.fromDegreesArrayHeights(flat));
-          }, false),
+          hierarchy,
           material: Cesium$c.Color.YELLOW.withAlpha(0.2),
           outline: false // 地形贴合时不支持 outline，设为 false 避免警告
         }
       });
       this._previewCircle._isPreview = true;
       this._tempEntities.push(this._previewCircle);
-    } else {
-      // 直接更新
-      this._previewCircle.polygon.hierarchy = new Cesium$c.CallbackProperty(() => {
-        const r = this._calcDistance(this._startPos, this._currentMousePos);
-        const pos = this._generateCirclePositions(this._startPos, r, 64);
-        const flat = pos.flatMap(c => [c[0], c[1], 0]);
-        return new Cesium$c.PolygonHierarchy(Cesium$c.Cartesian3.fromDegreesArrayHeights(flat));
-      }, false);
     }
   }
 
@@ -4706,37 +4758,39 @@ class DrawTool extends BaseTool {
    * @param {object} config 标绘配置
    * @param {Array} mousePos 当前鼠标位置 [lon, lat, height]
    */
-  _updatePlotPreview(config, mousePos) {
-    const isEllipse = config.plotType === PlotGraphicType.ELLIPSE;
-    const normalizeForEllipse = (pts) => isEllipse ? this._normalizeEllipseControlPoints(pts) : pts;
-
-    const previewPositions = [...this._tempPositions];
-    if (mousePos) {
-      previewPositions.push(mousePos);
-    }
-
-    if (previewPositions.length < config.minPoints) return;
-
+  _updatePlotPreview(config) {
+    // 标绘预览整体思路：
+    // 第一次调用时建立稳定的 CallbackProperty，回调内部读取 this._tempPositions +
+    // this._currentMousePos 重新生成几何。这样 mouve 之间的预览更新只是一帧一次的
+    // 几何重算，没有 CallbackProperty 重建开销。
     const factoryName = `create${this._capitalizePlotType(config.plotType)}`;
     if (!PlotGeometryUtil[factoryName]) {
       console.warn(`未知标绘类型: ${config.plotType}`);
       return;
     }
-
-    const geometryPositions = normalizeForEllipse(previewPositions);
-    const positions = PlotGeometryUtil[factoryName](geometryPositions);
+    const isEllipse = config.plotType === PlotGraphicType.ELLIPSE;
+    const normalizeForEllipse = (pts) => isEllipse ? this._normalizeEllipseControlPoints(pts) : pts;
     const isLine = config.category === 'line';
-    const flatCoords = [];
-    for (const c of positions) {
-      flatCoords.push(c[0], c[1], c[2] || 0);
-    }
-    const cartesians = Cesium$c.Cartesian3.fromDegreesArrayHeights(flatCoords);
+    const minPoints = config.minPoints;
 
     if (!this._previewPlot) {
+      // 标绘预览几何工厂：把"读 this._tempPositions + this._currentMousePos 并生成
+      // 标绘几何"的逻辑抽到一个内部方法，由稳定的 CallbackProperty 在每帧调用。
+      // 避免每次 mousemove 都重建 CallbackProperty + 重新计算整个几何。
+      const computePlotGeometry = () => {
+        const dynamicPositions = [...this._tempPositions];
+        if (this._currentMousePos) dynamicPositions.push(this._currentMousePos);
+        if (dynamicPositions.length < minPoints) return null;
+        const pos = PlotGeometryUtil[factoryName](normalizeForEllipse(dynamicPositions));
+        const flat = [];
+        for (const c of pos) flat.push(c[0], c[1], c[2] || 0);
+        return Cesium$c.Cartesian3.fromDegreesArrayHeights(flat);
+      };
+
       if (isLine) {
         this._previewPlot = this.createTempEntity(this.generateId('temp_plot'), {
           polyline: {
-            positions: new Cesium$c.CallbackProperty(() => cartesians, false),
+            positions: new Cesium$c.CallbackProperty(() => computePlotGeometry() || [], false),
             material: Cesium$c.Color.YELLOW,
             width: 2,
             clampToGround: true
@@ -4745,12 +4799,19 @@ class DrawTool extends BaseTool {
       } else {
         this._previewPlot = this.createTempEntity(this.generateId('temp_plot'), {
           polygon: {
-            hierarchy: new Cesium$c.CallbackProperty(() => new Cesium$c.PolygonHierarchy(cartesians), false),
+            hierarchy: new Cesium$c.CallbackProperty(() => {
+              const c = computePlotGeometry();
+              return new Cesium$c.PolygonHierarchy(c || []);
+            }, false),
             material: Cesium$c.Color.YELLOW.withAlpha(0.3),
             outline: false
           },
           polyline: {
-            positions: new Cesium$c.CallbackProperty(() => [...cartesians, cartesians[0]], false),
+            positions: new Cesium$c.CallbackProperty(() => {
+              const c = computePlotGeometry();
+              if (!c || c.length === 0) return [];
+              return [...c, c[0]];
+            }, false),
             material: Cesium$c.Color.YELLOW,
             width: 1
           }
@@ -4758,51 +4819,6 @@ class DrawTool extends BaseTool {
       }
       this._previewPlot._isPreview = true;
       this._tempEntities.push(this._previewPlot);
-    } else {
-      const self = this;
-      if (isLine) {
-        this._previewPlot.polyline.positions = new Cesium$c.CallbackProperty(() => {
-          const dynamicPositions = [...self._tempPositions];
-          if (self._currentMousePos) {
-            dynamicPositions.push(self._currentMousePos);
-          }
-          if (dynamicPositions.length < config.minPoints) return [];
-          const pos = PlotGeometryUtil[factoryName](normalizeForEllipse(dynamicPositions));
-          const flat = [];
-          for (const c of pos) {
-            flat.push(c[0], c[1], c[2] || 0);
-          }
-          return Cesium$c.Cartesian3.fromDegreesArrayHeights(flat);
-        }, false);
-      } else {
-        this._previewPlot.polygon.hierarchy = new Cesium$c.CallbackProperty(() => {
-          const dynamicPositions = [...self._tempPositions];
-          if (self._currentMousePos) {
-            dynamicPositions.push(self._currentMousePos);
-          }
-          if (dynamicPositions.length < config.minPoints) return new Cesium$c.PolygonHierarchy([]);
-          const pos = PlotGeometryUtil[factoryName](normalizeForEllipse(dynamicPositions));
-          const flat = [];
-          for (const c of pos) {
-            flat.push(c[0], c[1], c[2] || 0);
-          }
-          return new Cesium$c.PolygonHierarchy(Cesium$c.Cartesian3.fromDegreesArrayHeights(flat));
-        }, false);
-        this._previewPlot.polyline.positions = new Cesium$c.CallbackProperty(() => {
-          const dynamicPositions = [...self._tempPositions];
-          if (self._currentMousePos) {
-            dynamicPositions.push(self._currentMousePos);
-          }
-          if (dynamicPositions.length < config.minPoints) return [];
-          const pos = PlotGeometryUtil[factoryName](normalizeForEllipse(dynamicPositions));
-          const flat = [];
-          for (const c of pos) {
-            flat.push(c[0], c[1], c[2] || 0);
-          }
-          const cart = Cesium$c.Cartesian3.fromDegreesArrayHeights(flat);
-          return [...cart, cart[0]];
-        }, false);
-      }
     }
   }
 
@@ -5225,9 +5241,9 @@ class EditTool extends BaseTool {
     }
   }
 
-  _onMove(data) {
-    // _onMove receives movement object from BaseTool
-    const screenPos = data.position || data.endPosition;
+  _onMove(_lngLat, _entity, movement) {
+    // BaseTool.registerObserver 现在统一转发 (lngLat, entity, movement)
+    const screenPos = movement.position || movement.endPosition;
     if (!screenPos) return;
 
     // 非拖拽时做节流，避免 hover 检测过于频繁
@@ -5435,7 +5451,7 @@ class EditTool extends BaseTool {
           pixelSize: 12,
           outlineColor: Cesium$b.Color.BLACK,
           outlineWidth: 2,
-          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+          disableDepthTestDistance: LabelDepthConfig.distance,
           heightReference: Cesium$b.HeightReference.CLAMP_TO_GROUND
         }
       });
@@ -5483,7 +5499,7 @@ class EditTool extends BaseTool {
         pixelSize: 14,
         outlineColor: Cesium$b.Color.BLUE,
         outlineWidth: 2,
-        disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        disableDepthTestDistance: LabelDepthConfig.distance,
         heightReference: Cesium$b.HeightReference.CLAMP_TO_GROUND
       }
     });
@@ -5650,7 +5666,7 @@ class EditTool extends BaseTool {
             pixelSize: 12,
             outlineColor: Cesium$b.Color.BLACK,
             outlineWidth: 2,
-            disableDepthTestDistance: Number.POSITIVE_INFINITY,
+            disableDepthTestDistance: LabelDepthConfig.distance,
             heightReference: Cesium$b.HeightReference.CLAMP_TO_GROUND,
           }
         });
@@ -5676,7 +5692,7 @@ class EditTool extends BaseTool {
           pixelSize: 14,
           outlineColor: Cesium$b.Color.BLUE,
           outlineWidth: 2,
-          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+          disableDepthTestDistance: LabelDepthConfig.distance,
           heightReference: Cesium$b.HeightReference.CLAMP_TO_GROUND
         }
       });
@@ -5690,7 +5706,7 @@ class EditTool extends BaseTool {
           pixelSize: 12,
           outlineColor: Cesium$b.Color.YELLOW,
           outlineWidth: 2,
-          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+          disableDepthTestDistance: LabelDepthConfig.distance,
           heightReference: Cesium$b.HeightReference.CLAMP_TO_GROUND
         }
       });
@@ -5715,7 +5731,7 @@ class EditTool extends BaseTool {
             pixelSize: 12,
             outlineColor: Cesium$b.Color.BLACK,
             outlineWidth: 2,
-            disableDepthTestDistance: Number.POSITIVE_INFINITY,
+            disableDepthTestDistance: LabelDepthConfig.distance,
             // heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
           }
         });
@@ -5747,7 +5763,7 @@ class EditTool extends BaseTool {
                 pixelSize: 10,
                 outlineColor: Cesium$b.Color.RED,
                 outlineWidth: 2,
-                disableDepthTestDistance: Number.POSITIVE_INFINITY
+                disableDepthTestDistance: LabelDepthConfig.distance
               }
             }
           );
@@ -5815,7 +5831,7 @@ class EditTool extends BaseTool {
         pixelSize: 14,
         outlineColor: Cesium$b.Color.BLUE,
         outlineWidth: 2,
-        disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        disableDepthTestDistance: LabelDepthConfig.distance,
         heightReference: Cesium$b.HeightReference.CLAMP_TO_GROUND
       }
     });
@@ -6018,24 +6034,43 @@ class EditTool extends BaseTool {
         return this._clampPositionToGround(newPos);
       });
       this._selectedEntity.polyline.positions = newPositions;
-      
-      // 修复：更新所有顶点控制点位置，同时更新中心控制点位置
+
+      // 修复：更新所有顶点和中点控制点位置
       this._editHandles.forEach((handle) => {
-        // 修复：统一使用 includes('center') 来判断中心控制点
-        if (handle.id && handle.id.includes('center')) {
-          // 中心控制点已经更新过了
+        if (!handle.id || handle.id.includes('center')) return;
+        // 顶点 handle：__edit_handle_<index>
+        const vertexMatch = handle.id.match(/__edit_handle_(\d+)$/);
+        if (vertexMatch) {
+          const index = parseInt(vertexMatch[1], 10);
+          if (newPositions[index]) {
+            const posProp = handle.position;
+            if (posProp && typeof posProp.setValue === 'function') {
+              posProp.setValue(newPositions[index]);
+            } else {
+              handle.position = new Cesium$b.ConstantPositionProperty(newPositions[index]);
+            }
+          }
           return;
         }
-        // 找到对应的顶点索引
-        const match = handle.id.match(/__edit_handle_(\d+)$/);
-        if (match) {
-          const index = parseInt(match[1], 10);
-          if (newPositions[index]) {
-            handle.position = new Cesium$b.ConstantPositionProperty(newPositions[index]);
+        // 中点 handle：__edit_handle_mid_<li>_<ri>
+        const midMatch = handle.id.match(/__edit_handle_mid_(\d+)_(\d+)/);
+        if (midMatch) {
+          const li = parseInt(midMatch[1], 10);
+          const ri = parseInt(midMatch[2], 10);
+          const left = newPositions[li];
+          const right = newPositions[ri];
+          if (!left || !right) return;
+          const midCart = Cesium$b.Cartesian3.midpoint(left, right, new Cesium$b.Cartesian3());
+          const clamped = this._clampPositionToGround(midCart);
+          const posProp = handle.position;
+          if (posProp && typeof posProp.setValue === 'function') {
+            posProp.setValue(clamped);
+          } else {
+            handle.position = new Cesium$b.ConstantPositionProperty(clamped);
           }
         }
       });
-      
+
       // 更新原始位置缓存
       this._originalPositions = newPositions;
     } else if (Cesium$b.defined(this._selectedEntity.polygon)) {
@@ -6086,18 +6121,40 @@ class EditTool extends BaseTool {
           return this._clampPositionToGround(newPos);
         });
 
-        // 修复：更新顶点控制点位置，使用更可靠的ID匹配
+        // 修复：更新顶点和中点控制点位置。
+        // 注意：正则 `/__edit_handle_(\d+)$/` 只匹配顶点 handle；
+        // 中点 handle 的 ID 是 `__edit_handle_mid_<li>_<ri>`，需要单独处理。
         this._editHandles.forEach((handle) => {
-          // 修复：统一使用 includes('center') 来判断中心控制点
-          if (handle.id && handle.id.includes('center')) {
+          if (!handle.id || handle.id.includes('center')) return;
+          // 顶点 handle：__edit_handle_<index>
+          const vertexMatch = handle.id.match(/__edit_handle_(\d+)$/);
+          if (vertexMatch) {
+            const index = parseInt(vertexMatch[1], 10);
+            if (newPositions[index]) {
+              const posProp = handle.position;
+              if (posProp && typeof posProp.setValue === 'function') {
+                posProp.setValue(newPositions[index]);
+              } else {
+                handle.position = new Cesium$b.ConstantPositionProperty(newPositions[index]);
+              }
+            }
             return;
           }
-          // 提取数字索引
-          const match = handle.id.match(/__edit_handle_(\d+)$/);
-          if (match) {
-            const index = parseInt(match[1], 10);
-            if (newPositions[index]) {
-              handle.position = new Cesium$b.ConstantPositionProperty(newPositions[index]);
+          // 中点 handle：__edit_handle_mid_<li>_<ri>
+          const midMatch = handle.id.match(/__edit_handle_mid_(\d+)_(\d+)/);
+          if (midMatch) {
+            const li = parseInt(midMatch[1], 10);
+            const ri = parseInt(midMatch[2], 10);
+            const left = newPositions[li];
+            const right = newPositions[ri];
+            if (!left || !right) return;
+            const midCart = Cesium$b.Cartesian3.midpoint(left, right, new Cesium$b.Cartesian3());
+            const clamped = this._clampPositionToGround(midCart);
+            const posProp = handle.position;
+            if (posProp && typeof posProp.setValue === 'function') {
+              posProp.setValue(clamped);
+            } else {
+              handle.position = new Cesium$b.ConstantPositionProperty(clamped);
             }
           }
         });
@@ -6658,7 +6715,14 @@ class EditTool extends BaseTool {
       // 多边形顶点拖动：通过 CallbackProperty 让 Cesium 直接从 handle 位置读，
       // 这里只需要更新 handle.position 即可，几何会跟着弯折，
       // 远比每帧 newPositions + new PolygonHierarchy 顺滑。
-      this._dragHandle.position = new Cesium$b.ConstantPositionProperty(newCartesian);
+      // 复用现有 Property 实例并 setValue：避免替换 Property 引用导致
+      // Cesium 某些情况下不重新渲染。
+      const dragPosProp = this._dragHandle.position;
+      if (dragPosProp && typeof dragPosProp.setValue === 'function') {
+        dragPosProp.setValue(newCartesian);
+      } else {
+        this._dragHandle.position = new Cesium$b.ConstantPositionProperty(newCartesian);
+      }
 
       // 修复：多边形编辑后重新计算并更新中心控制点位置
       this._updateCenterHandlePosition();
@@ -6701,7 +6765,14 @@ class EditTool extends BaseTool {
       if (!left || !right) return;
       const midCart = Cesium$b.Cartesian3.midpoint(left, right, new Cesium$b.Cartesian3());
       const clamped = this._clampPositionToGround(midCart);
-      handle.position = new Cesium$b.ConstantPositionProperty(clamped);
+      // 复用现有 Property 实例并 setValue：避免替换 Property 引用导致
+      // Cesium 某些情况下不重新渲染。
+      const posProp = handle.position;
+      if (posProp && typeof posProp.setValue === 'function') {
+        posProp.setValue(clamped);
+      } else {
+        handle.position = new Cesium$b.ConstantPositionProperty(clamped);
+      }
     });
   }
 
@@ -6924,14 +6995,15 @@ class SelectTool extends BaseTool {
     }
   }
 
-  _onMove(data) {
+  _onMove(lngLat, _entity, movement) {
     // mouse:move passes movement object from BaseTool
-    const screenPos = data.position || data.endPosition;
+    const screenPos = movement.position || movement.endPosition;
     if (!screenPos) return;
 
     if (!this._isSelecting || !this._startPos) return;
 
-    const lonLat = this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
+    // 优先使用 EventModule 已计算的 lngLat（避免重复 scene.pickPosition）。
+    const lonLat = lngLat || this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
     if (!lonLat) return;
 
     this._updateSelectionRectPreview(lonLat);
@@ -7423,17 +7495,18 @@ class DeleteTool extends BaseTool {
     }
   }
 
-  _onMove(data) {
-    const screenPos = data.position || data.endPosition;
+  _onMove(_lngLat, pickedEntity, movement) {
+    const screenPos = movement.position || movement.endPosition;
     if (!screenPos) return;
 
-    const picked = this._viewer.scene.pick(screenPos);
-
+    // 优先使用 EventModule 已计算的 pickedEntity（避免重复 scene.pick）。
+    // EventModule 已经做过 pickedEntity.id（Pick 对象 → Entity 实例）取一次，
+    // 这里直接取 Entity.id（字符串）即可。
     let hoveredId = null;
 
-    if (Cesium$9.defined(picked) && Cesium$9.defined(picked.id)) {
-      const entityId = picked.id.id;
-      if (!entityId.startsWith('__temp_') && !entityId.startsWith('__edit_handle_')) {
+    if (Cesium$9.defined(pickedEntity) && Cesium$9.defined(pickedEntity.id)) {
+      const entityId = pickedEntity.id;
+      if (typeof entityId === 'string' && !entityId.startsWith('__temp_') && !entityId.startsWith('__edit_handle_')) {
         hoveredId = entityId;
       }
     }
@@ -7716,6 +7789,24 @@ const LABEL_BORDER_COLOR = '#FB120E';
 const LABEL_BACKGROUND_COLOR = '#ffffff';
 const LABEL_TEXT_COLOR = '#000000';
 
+// 模块级 measure canvas 单例：测量标签每次重绘文字宽度时复用，避免
+// 每次都 document.createElement + getContext（之前在 _createLabelImage 中是热路径）。
+// 延迟到首次调用时再创建：jsdom 等环境顶层 document.createElement('canvas').getContext 不可用。
+let _measureCanvas = null;
+let _measureCtx = null;
+function _measureTextWidth(text, font) {
+  if (!_measureCanvas) {
+    try {
+      _measureCanvas = document.createElement('canvas');
+      _measureCtx = _measureCanvas.getContext('2d');
+    } catch (e) {
+      return Math.max(1, text.length * 8);
+    }
+  }
+  _measureCtx.font = font;
+  return Math.max(1, Math.ceil(_measureCtx.measureText(text).width));
+}
+
 /**
  * 测量类型枚举
  */
@@ -7903,8 +7994,8 @@ class MeasureTool extends BaseTool {
     this._updateMeasurement();
   }
 
-  _onMove(data) {
-    const screenPos = data.position || data.endPosition;
+  _onMove(lngLat, entity, movement) {
+    const screenPos = movement.position || movement.endPosition;
     if (!screenPos) return;
 
     // 拖拽顶点中：节流更新该顶点位置与对应几何/标注
@@ -7913,7 +8004,8 @@ class MeasureTool extends BaseTool {
       if (now - this._lastDragMoveTime < this._dragThrottleMs) return;
       this._lastDragMoveTime = now;
 
-      const lonLat = this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
+      // 拖动路径优先用 EventModule 已计算的 lngLat；否则 fallback。
+      const lonLat = lngLat || this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
       if (lonLat) {
         this._updateVertexDuringDrag(this._dragVertexIndex, lonLat, this._dragResult);
 
@@ -7927,25 +8019,27 @@ class MeasureTool extends BaseTool {
       return;
     }
 
-    // 非拖拽：检测悬停，更新光标（与 EditTool 风格一致）
+    // 非拖拽：检测悬停，更新光标（与 EditTool 风格一致）。优先用 EventModule 给的 entity。
     let isOverFinishedVertex = false;
-    try {
-      const picked = this._viewer.scene.pick(screenPos);
-      // scene.pick 返回的是 Pick 对象（含 id / primitive 两层），需要取出 .id 才能与 pointEntities 中的 Entity 做比较
-      if (Cesium$7.defined(picked)) {
-        isOverFinishedVertex = !!this._findFinishedPointHit(picked.id);
+    if (Cesium$7.defined(entity)) {
+      try {
+        // EventModule 传过来的是 Cesium Entity 实例（不是 Pick 对象），直接用于命中判定
+        isOverFinishedVertex = !!this._findFinishedPointHit(entity);
+      } catch (e) {
+        // ignore
       }
-    } catch (e) {
-      // ignore
     }
     // 悬停在角点上：CSS `grab`（开放的手）暗示"可拖动"；无浏览器支持时回退 `default`
     this._setCanvasCursor(isOverFinishedVertex ? 'grab' : 'default');
 
-    const lonLat = this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
+    const lonLat = lngLat || this.screenToLonLat({ x: screenPos.x, y: screenPos.y });
     if (!lonLat) return;
     this._mousePos = lonLat;
+
+    // 非拖拽预览路径：用 rAF 合并 mousemove，与 render 帧同步，避免全球视角下
+    // 多次 mousemove 之间重复重建几何/canvas。
     if (this._isMeasuring) {
-      this._updateMeasurement();
+      this._scheduleMoveWork(() => this._updateMeasurement());
     }
   }
 
@@ -8725,7 +8819,7 @@ class MeasureTool extends BaseTool {
         verticalOrigin: Cesium$7.VerticalOrigin.BOTTOM,
         horizontalOrigin: Cesium$7.HorizontalOrigin.CENTER,
         pixelOffset: new Cesium$7.Cartesian2(0, -6),
-        disableDepthTestDistance: Number.POSITIVE_INFINITY
+        disableDepthTestDistance: LabelDepthConfig.distance
       }
     });
     entity._lastText = text;
@@ -8751,11 +8845,8 @@ class MeasureTool extends BaseTool {
     const triangleHeight = 8;
     const rectHeight = 20;
 
-    // 先用临时 ctx 测量文字宽度，确定目标 canvas 尺寸
-    const measureCanvas = document.createElement('canvas');
-    const measureCtx = measureCanvas.getContext('2d');
-    measureCtx.font = font;
-    const textWidth = Math.max(1, Math.ceil(measureCtx.measureText(text).width));
+    // 复用模块级 measure canvas 单例，避免每次 mousemove 都 document.createElement('canvas')
+    const textWidth = _measureTextWidth(text, font);
     const rectWidth = textWidth + paddingX * 2;
     const width = rectWidth + borderWidth * 2;
     const height = rectHeight + triangleHeight + borderWidth * 2;
@@ -8877,7 +8968,7 @@ class MeasureTool extends BaseTool {
         style: Cesium$7.LabelStyle.FILL_AND_OUTLINE,
         verticalOrigin: Cesium$7.VerticalOrigin.BOTTOM,
         horizontalOrigin: Cesium$7.HorizontalOrigin.CENTER,
-        disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        disableDepthTestDistance: LabelDepthConfig.distance,
         pixelOffset: new Cesium$7.Cartesian2(0, -10)
       }
     });
@@ -8892,7 +8983,7 @@ class MeasureTool extends BaseTool {
         pixelSize: 8,
         outlineColor: Cesium$7.Color.fromCssColorString(MEASURE_POINT_OUTLINE_COLOR),
         outlineWidth: 1,
-        disableDepthTestDistance: Number.POSITIVE_INFINITY
+        disableDepthTestDistance: LabelDepthConfig.distance
       }
     });
     this._pointEntities.push(point);
@@ -10054,9 +10145,15 @@ class Zoom extends BaseControl {
     const camera = this._viewer.camera;
     // 以双击位置拾取到的地表点为缩放中心；拾取不到退回相机正下方
     let cartographic = camera.positionCartographic;
+    // 锚点缩放需要"点击像素的视线方向"：保持这条视线不变，
+    // 锚点缩放后才仍投影在光标下方（相机中轴方向只在点击点恰为中心时成立）
+    let rayDirection = camera.direction;
     if (movement?.position && this._viewer.scene?.globe) {
       const ray = camera.getPickRay(movement.position);
       const cartesian = ray ? this._viewer.scene.globe.pick(ray, this._viewer.scene) : null;
+      if (ray) {
+        rayDirection = ray.direction;
+      }
       if (cartesian) {
         cartographic = Cesium$5.Cartographic.fromCartesian(cartesian);
       }
@@ -10064,7 +10161,89 @@ class Zoom extends BaseControl {
 
     const currentLevel = this._pendingLevel ?? this._getZoomLevel();
     const targetLevel = Math.max(0, Math.min(24, currentLevel + levelDelta));
-    this._flyToLevel(targetLevel, cartographic);
+    this._flyToLevelKeepScreenPoint(targetLevel, cartographic, rayDirection);
+  }
+
+  /**
+   * 飞到指定层级，且保持 cartographic 对应的地面点在原屏幕位置（锚点缩放）。
+   *
+   * 与 _flyToLevel（以点为中心）不同：这里把相机沿"点击像素的视线方向"反方向
+   * 退到目标高度——同一像素的视线方向只取决于相机姿态、与位置无关，因此相机
+   * 沿该方向移动后，锚点仍投影在双击位置（光标下方），而不是被搬到屏幕中心。
+   * 视线几乎水平（点击靠近地平线/天空）时退化为居中模式。
+   *
+   * @param {number} targetLevel 目标层级
+   * @param {Cesium.Cartographic} cartographic 锚点（双击拾取的地面点）
+   * @param {Cesium.Cartesian3} rayDirection 点击像素的视线方向（ECEF 单位向量）
+   */
+  _flyToLevelKeepScreenPoint(targetLevel, cartographic, rayDirection) {
+    const camera = this._viewer.camera;
+    const targetHeight = this._getHeightByZoomLevel(targetLevel);
+    const pitch = camera.pitch;
+
+    let destination = null;
+    // 相机俯角至少 ~60° 才做锚点缩放；更平时后退距离发散，观感也差，退化为中心模式
+    const minPitch = Cesium$5.Math.toRadians(-60);
+    if (pitch <= minPitch && rayDirection) {
+      // 锚点处的本地"上"方向（ECEF）
+      const cosLat = Math.cos(cartographic.latitude);
+      const up = new Cesium$5.Cartesian3(
+        cosLat * Math.cos(cartographic.longitude),
+        cosLat * Math.sin(cartographic.longitude),
+        Math.sin(cartographic.latitude)
+      );
+      // 视线向下的分量
+      const rayUp = Cesium$5.Cartesian3.dot(rayDirection, up);
+      // 相机沿视线到锚点的距离：垂直落差 / 视线向下分量
+      const s = (targetHeight - cartographic.height) / (-rayUp);
+      if (rayUp < -0.05 && Number.isFinite(s) && s > 0) {
+        const anchor = Cesium$5.Cartesian3.fromRadians(
+          cartographic.longitude,
+          cartographic.latitude,
+          cartographic.height
+        );
+        destination = Cesium$5.Cartesian3.add(
+          anchor,
+          Cesium$5.Cartesian3.multiplyByScalar(rayDirection, -s, new Cesium$5.Cartesian3()),
+          new Cesium$5.Cartesian3()
+        );
+      }
+    }
+
+    if (!destination) {
+      destination = Cesium$5.Cartesian3.fromRadians(
+        cartographic.longitude,
+        cartographic.latitude,
+        targetHeight
+      );
+    }
+    this._flyToDestination(targetLevel, destination);
+  }
+
+  /**
+   * 飞到指定层级的目的地（目的地构造交给调用方），并记录 _pendingLevel
+   * @param {number} targetLevel 目标层级
+   * @param {Cesium.Cartesian3} destination 相机最终位置
+   */
+  _flyToDestination(targetLevel, destination) {
+    const camera = this._viewer.camera;
+
+    this._pendingLevel = targetLevel;
+    camera.flyTo({
+      destination,
+      orientation: {
+        heading: camera.heading,
+        pitch: camera.pitch,
+        roll: camera.roll
+      },
+      duration: this._duration,
+      complete: () => {
+        if (this._pendingLevel === targetLevel) this._pendingLevel = null;
+      },
+      cancel: () => {
+        if (this._pendingLevel === targetLevel) this._pendingLevel = null;
+      }
+    });
   }
 
   _zoomIn() {
@@ -10086,34 +10265,19 @@ class Zoom extends BaseControl {
   }
 
   /**
-   * 飞到指定层级（以给定经纬度为中心），并记录 _pendingLevel
+   * 飞到指定层级（以给定经纬度为正下方中心），并记录 _pendingLevel
    * @param {number} targetLevel 目标层级
    * @param {Cesium.Cartographic} cartographic 目的地中心
    */
   _flyToLevel(targetLevel, cartographic) {
-    const camera = this._viewer.camera;
-    const targetHeight = this._getHeightByZoomLevel(targetLevel);
-
-    this._pendingLevel = targetLevel;
-    camera.flyTo({
-      destination: Cesium$5.Cartesian3.fromRadians(
+    this._flyToDestination(
+      targetLevel,
+      Cesium$5.Cartesian3.fromRadians(
         cartographic.longitude,
         cartographic.latitude,
-        targetHeight
-      ),
-      orientation: {
-        heading: camera.heading,
-        pitch: camera.pitch,
-        roll: camera.roll
-      },
-      duration: this._duration,
-      complete: () => {
-        if (this._pendingLevel === targetLevel) this._pendingLevel = null;
-      },
-      cancel: () => {
-        if (this._pendingLevel === targetLevel) this._pendingLevel = null;
-      }
-    });
+        this._getHeightByZoomLevel(targetLevel)
+      )
+    );
   }
 
   _getZoomLevel() {
@@ -11888,6 +12052,7 @@ const xs3d = {
     Zoom,
     Compass,
     DistanceLegend,
+    LabelDepthConfig,
     // 导出工具枚举
     DrawType,
     EditMode,