cesium-xs-sdk 1.0.18 → 1.0.19

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();
@@ -10054,9 +10072,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 +10088,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 +10192,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() {