hn-map 1.1.14 → 1.1.16

package/src/util.ts

@@ -1,3 +1,8 @@
+/**
+ * 地图工具函数库
+ * 包含坐标转换、地图计算、数据处理等工具函数
+ */
+
 // import Vue from 'vue'
 //
 // // 渲染vue组件并获取dom结构
@@ -13,7 +18,18 @@
 //     return app.$el
 // }
 
-// 对象深度合并
+/**
+ * 对象深度合并函数
+ * @param target 目标对象，合并结果会存储在此对象中
+ * @param source 源对象，提供要合并的属性
+ * @returns {any} 合并后的目标对象
+ * @example
+ * ```javascript
+ * const target = { a: 1, b: { c: 2 } };
+ * const source = { b: { d: 3 }, e: 4 };
+ * deepMerge(target, source); // { a: 1, b: { c: 2, d: 3 }, e: 4 }
+ * ```
+ */
 export function deepMerge(target: any, source: any): any {
   for (let key of Object.keys(source)) {
     if (source[key] instanceof Object && !Array.isArray(source[key])) {
@@ -26,14 +42,32 @@ export function deepMerge(target: any, source: any): any {
   return target;
 }
 
-// 递归格式化高德坐标系
+/**
+ * 递归格式化坐标数组，将WGS-84坐标转换为GCJ-02（高德坐标）
+ * 支持多种坐标格式：点坐标、线坐标、面坐标和对象数组
+ * @param position 坐标数组或对象数组
+ * @returns {any} 转换后的坐标数组或对象数组
+ * @example
+ * ```javascript
+ * // 点坐标
+ * wgs84ToGcj02Format([116.404, 39.915]);
+ *
+ * // 线坐标
+ * wgs84ToGcj02Format([[116.404, 39.915], [116.405, 39.916]]);
+ *
+ * // 对象数组
+ * wgs84ToGcj02Format([{lng: 116.404, lat: 39.915}, {lng: 116.405, lat: 39.916}]);
+ * ```
+ */
 export function wgs84ToGcj02Format(position: any): any {
-  // 判断是否是数组
+  // 判断是否是二维数组（线或面坐标）
   if (position.every((item: any) => Array.isArray(item))) {
     return position.map((item: any) => {
       return wgs84ToGcj02Format(item);
     });
-  } else if (position.every((item: any) => typeof item === "object")) {
+  }
+  // 判断是否是对象数组
+  else if (position.every((item: any) => typeof item === "object")) {
     return position.map((item: any) => {
       let data = wgs84ToGcj02Format([item.lng, item.lat]);
       return {
@@ -42,16 +76,22 @@ export function wgs84ToGcj02Format(position: any): any {
         lat: data[1],
       };
     });
-  } else {
+  }
+  // 单点坐标
+  else {
     return wgs84ToGcj02(position[0], position[1]);
   }
 }
 
 /**
  * WGS-84 转 GCJ-02（高德坐标）
- * @param {number} wgsLat - WGS-84纬度
  * @param {number} wgsLng - WGS-84经度
- * @returns {[number, number]} GCJ-02经纬度数组
+ * @param {number} wgsLat - WGS-84纬度
+ * @returns {[number, number]} GCJ-02经纬度数组 [经度, 纬度]
+ * @example
+ * ```javascript
+ * wgs84ToGcj02(116.404, 39.915); // 返回转换后的高德坐标
+ * ```
  */
 export function wgs84ToGcj02(wgsLng: any, wgsLat: any): any {
   if (!isCorrectPosition(wgsLng, wgsLat)) {
@@ -61,6 +101,12 @@ export function wgs84ToGcj02(wgsLng: any, wgsLat: any): any {
   const a = 6378245.0; // 长半轴
   const ee = 0.00669342162296594323; // 扁率
 
+  /**
+   * 纬度转换函数
+   * @param x 经度偏移
+   * @param y 纬度偏移
+   * @returns {number} 纬度转换值
+   */
   function transformLat(x: any, y: any): any {
     let ret =
       -100.0 +
@@ -82,6 +128,12 @@ export function wgs84ToGcj02(wgsLng: any, wgsLat: any): any {
     return ret;
   }
 
+  /**
+   * 经度转换函数
+   * @param x 经度偏移
+   * @param y 纬度偏移
+   * @returns {number} 经度转换值
+   */
   function transformLng(x: any, y: any): any {
     let ret =
       300.0 +
@@ -117,16 +169,37 @@ export function wgs84ToGcj02(wgsLng: any, wgsLat: any): any {
 }
 
 /**
- * 判断是否为正确的坐标
- * @param {number} lat - 纬度
+ * 判断是否为正确的坐标范围
  * @param {number} lng - 经度
- * @returns {boolean}
+ * @param {number} lat - 纬度
+ * @returns {boolean} 坐标是否在有效范围内
+ * @example
+ * ```javascript
+ * isCorrectPosition(116.404, 39.915); // true
+ * isCorrectPosition(200, 100); // false
+ * ```
  */
 export function isCorrectPosition(lng: any, lat: any): boolean {
   return lng <= 180 && lng >= -180 && lat <= 90 && lat >= -90;
 }
 
-// 根据矩形左上角和右上角坐标计算矩形坐标对
+/**
+ * 根据矩形左上角和右下角坐标计算矩形的完整坐标数组
+ * @param leftTop 左上角坐标 [经度, 纬度]
+ * @param rightBottom 右下角坐标 [经度, 纬度]
+ * @returns {Array<Array<number>>} 矩形的完整坐标数组，包含5个点（首尾相同以闭合矩形）
+ * @example
+ * ```javascript
+ * createRectangleCoordinates([116.404, 39.915], [116.405, 39.914]);
+ * // 返回：[
+ * //   [116.404, 39.915], // 左上角
+ * //   [116.405, 39.915], // 右上角
+ * //   [116.405, 39.914], // 右下角
+ * //   [116.404, 39.914], // 左下角
+ * //   [116.404, 39.915]  // 回到左上角，闭合矩形
+ * // ]
+ * ```
+ */
 export function createRectangleCoordinates(leftTop: any, rightBottom: any) {
   const [leftTopLng, leftTopLat] = leftTop;
   const [rightBottomLng, rightBottomLat] = rightBottom;
@@ -137,7 +210,7 @@ export function createRectangleCoordinates(leftTop: any, rightBottom: any) {
   const rightBottomPoint = [Number(rightBottomLng), Number(rightBottomLat)];
   const leftBottomPoint = [Number(leftTopLng), Number(rightBottomLat)];
 
-  // 返回五个点的坐标对（首尾相同）
+  // 返回五个点的坐标对（首尾相同，形成闭合矩形）
   return [
     leftTopPoint,
     rightTopPoint,
@@ -147,6 +220,15 @@ export function createRectangleCoordinates(leftTop: any, rightBottom: any) {
   ];
 }
 
+/**
+ * 根据地图缩放级别获取对应的高度范围
+ * @param level 地图缩放级别（1-18）
+ * @returns {Object} 包含startHeight和endHeight的对象，表示该级别的高度范围
+ * @example
+ * ```javascript
+ * getMapRangeHeightByLevel(11); // 返回level=11对应的高度范围
+ * ```
+ */
 export function getMapRangeHeightByLevel(level: number) {
   // 输入校验：限制在 1~18
   level = Math.max(1, Math.min(18, Math.floor(level)));
@@ -166,21 +248,27 @@ export function getMapRangeHeightByLevel(level: number) {
 }
 
 /**
- * 根据 level 返回该层级的“中间高度”（几何平均值）
- *
+ * 根据缩放级别返回该层级的“中间高度”
  * @param {number} level - 缩放级别 [1, 18]
  * @returns {number} 中间高度（米）
+ * @example
+ * ```javascript
+ * getLevelMiddleHeight(11); // 返回level=11对应的中间高度
+ * ```
  */
 export function getLevelMiddleHeight(level: number): number {
-  const { startHeight, endHeight } = getMapRangeHeightByLevel(level);
-  // 如果 startHeight 为 0（如 level=18），几何平均会为 0，不合理
-  // 所以 level=18 特殊处理：返回 (0 + end)/2 或直接返回 end * 0.7 左右
-  if (startHeight === 0) {
-    return endHeight * 0.7; // 经验值，贴近“中间感知”
-  }
-
-  // 几何平均：√(start × end)
-  return Math.sqrt(startHeight * endHeight);
+  // const { startHeight, endHeight } = getMapRangeHeightByLevel(level);
+  // // 如果 startHeight 为 0（如 level=18），几何平均会为 0，不合理
+  // // 所以 level=18 特殊处理：返回 (0 + end)/2 或直接返回 end * 0.7 左右
+  // if (startHeight === 0) {
+  //   return endHeight * 0.7; // 经验值，贴近“中间感知”
+  // }
+  //
+  // // 几何平均：√(start × end)
+  // return Math.sqrt(startHeight * endHeight);
+  const EARTH_RADIUS = 6378137; // 赤道半径
+  const height = (2 * Math.PI * EARTH_RADIUS) / (256 * Math.pow(2, level));
+  return height;
 }
 
 /**
@@ -191,6 +279,10 @@ export function getLevelMiddleHeight(level: number): number {
  *
  * @param {number} level - 缩放级别 [1, 18]
  * @returns {[number, number]} [开始高度, 结束高度]（单位：米）
+ * @example
+ * ```javascript
+ * getLevelHeightRange(11); // 返回level=11对应的高度范围
+ * ```
  */
 export function getLevelHeightRange(level: number): [number, number] {
   const { startHeight, endHeight } = getMapRangeHeightByLevel(level);
@@ -198,9 +290,13 @@ export function getLevelHeightRange(level: number): [number, number] {
 }
 
 /**
- * 根据高度反推 level（1~18）
+ * 根据高度反推地图缩放级别（1~18）
  * @param {number} height - 当前视野高度（米）
- * @returns {number} level
+ * @returns {number} 对应的地图缩放级别
+ * @example
+ * ```javascript
+ * getHeightToLevel(100000); // 根据高度返回对应的缩放级别
+ * ```
  */
 export function getHeightToLevel(height: number): number {
   if (height > 32000000) return 1;
@@ -213,7 +309,18 @@ export function getHeightToLevel(height: number): number {
   // 限制在 1~18
   return Math.max(1, Math.min(18, level));
 }
-// 將坐标数组中的元素字符串类型统一处理为number类型
+
+/**
+ * 将坐标数组中的字符串类型元素统一转换为数字类型
+ * 支持一维、二维、三维坐标数组
+ * @param position 字符串坐标数组
+ * @returns {number[] | number[][] | number[][][]} 转换后的数字坐标数组
+ * @example
+ * ```javascript
+ * convertPosition(["116.404", "39.915"]); // [116.404, 39.915]
+ * convertPosition([["116.404", "39.915"], ["116.405", "39.916"]]); // 二维数组转换
+ * ```
+ */
 export function convertPosition(
   position: string[] | string[][] | string[][][]
 ): number[] | number[][] | number[][][] {
@@ -233,34 +340,41 @@ export function convertPosition(
   }) as number[] | number[][] | number[][][];
 }
 
-// mars3d 地图重写瓦片加载失败的回调，使控制台过滤掉瓦片加载失败的报错
+/**
+ * mars3d 地图重写瓦片加载失败的回调函数
+ * 用于过滤掉控制台中瓦片加载失败的报错，提高开发体验
+ * @example
+ * ```javascript
+ * // 在地图初始化后调用
+ * mars3dTileErrorHandler();
+ * ```
+ */
 export function mars3dTileErrorHandler() {
   // 确保 Cesium 已加载
-  if (typeof Cesium !== 'undefined' && Cesium.TileProviderError) {
+  if (typeof Cesium !== "undefined" && Cesium.TileProviderError) {
     const originalReportError = Cesium.TileProviderError.reportError;
 
     Cesium.TileProviderError.reportError = function (
-        existingError:any,
-        provider:any,
-        errorEvent:any,
-        message:any,
-        x:any,
-        y:any,
-        level:any,
-        error:any
+      existingError: any,
+      provider: any,
+      errorEvent: any,
+      message: any,
+      x: any,
+      y: any,
+      level: any,
+      error: any
     ) {
-      // 可选：判断是否为“瓦片不存在”类错误（如 404、fetch 失败等）
+      // 判断是否为“瓦片不存在”类错误（如 404、fetch 失败等）
       const shouldIgnore =
-          message?.includes('Failed to obtain image') ||
-          message?.includes('无法获得图块') ||
-          message?.includes('404') ||
-          (error && error.status === 404) ||
-          message?.includes('NetworkError') ||
-          message?.includes('not found');
+        message?.includes("Failed to obtain image") ||
+        message?.includes("无法获得图块") ||
+        message?.includes("404") ||
+        (error && error.status === 404) ||
+        message?.includes("NetworkError") ||
+        message?.includes("not found");
 
       if (shouldIgnore) {
         // 静默处理：不打印日志，但仍可触发 errorEvent（供自定义监听）
-        // 注意：仍需调用 raiseEvent（如果有人监听），但跳过 console.log
         if (Cesium.defined(errorEvent) && errorEvent.numberOfListeners > 0) {
           let tileError = existingError;
           if (Cesium.defined(existingError)) {
@@ -271,23 +385,35 @@ export function mars3dTileErrorHandler() {
             tileError.level = level;
             tileError.retry = false;
             tileError.error = error;
-            tileError.timesRetried = Cesium.defaultValue(tileError.timesRetried, 0) + 1;
+            tileError.timesRetried =
+              Cesium.defaultValue(tileError.timesRetried, 0) + 1;
           } else {
             tileError = new Cesium.TileProviderError(
-                provider,
-                message,
-                x,
-                y,
-                level,
-                0,
-                error
+              provider,
+              message,
+              x,
+              y,
+              level,
+              0,
+              error
             );
           }
           errorEvent.raiseEvent(tileError);
           return tileError;
         } else {
-          // 没人监听，且我们不想打印 → 直接返回一个空错误对象（或 null）
-          return existingError || new Cesium.TileProviderError(provider, message, x, y, level, 0, error);
+          // 没人监听，直接返回错误对象
+          return (
+            existingError ||
+            new Cesium.TileProviderError(
+              provider,
+              message,
+              x,
+              y,
+              level,
+              0,
+              error
+            )
+          );
         }
       }
 
@@ -296,3 +422,81 @@ export function mars3dTileErrorHandler() {
     };
   }
 }
+
+/**
+ * Cesium专用工具函数
+ */
+
+/**
+ * 将WGS84坐标转换为Cesium笛卡尔坐标
+ */
+export function wgs84ToCartesian(
+  lng: number,
+  lat: number,
+  alt: number = 0
+): any {
+  return Cesium.Cartesian3.fromDegrees(lng, lat, alt);
+}
+
+/**
+ * 将Cesium笛卡尔坐标转换为WGS84坐标
+ */
+export function cartesianToWgs84(cartesian: any): {
+  lng: number;
+  lat: number;
+  alt: number;
+} {
+  const cartographic = Cesium.Cartographic.fromCartesian(cartesian);
+  return {
+    lng: Cesium.Math.toDegrees(cartographic.longitude),
+    lat: Cesium.Math.toDegrees(cartographic.latitude),
+    alt: cartographic.height,
+  };
+}
+
+/**
+ * 计算两点间的距离（米）
+ */
+export function calculateDistance(pos1: any, pos2: any): number {
+  const cartesian1 = wgs84ToCartesian(pos1.lng, pos1.lat, pos1.alt || 0);
+  const cartesian2 = wgs84ToCartesian(pos2.lng, pos2.lat, pos2.alt || 0);
+  return Cesium.Cartesian3.distance(cartesian1, cartesian2);
+}
+
+/**
+ * 创建颜色材质
+ */
+export function createColorMaterial(color: string, opacity: number = 1.0): any {
+  return new Cesium.ColorMaterialProperty(
+    Cesium.Color.fromCssColorString(color).withAlpha(opacity)
+  );
+}
+
+/**
+ * 创建图片材质
+ */
+export function createImageMaterial(imageUrl: string): any {
+  return new Cesium.ImageMaterialProperty({
+    image: imageUrl,
+    transparent: true,
+  });
+}
+
+/**
+ * 计算包围球
+ */
+export function calculateBoundingSphere(
+  positions: Array<[number, number, number?]>
+): any {
+  const cartesians = positions.map((pos) =>
+    wgs84ToCartesian(pos[0], pos[1], pos[2] || 0)
+  );
+  return Cesium.BoundingSphere.fromPoints(cartesians);
+}
+
+/**
+ * 创建实体集合
+ */
+export function createEntityCollection(id: string): any {
+  return new Cesium.CustomDataSource(id);
+}