huweili-cesium 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# huweili-cesium
+
+基于 Cesium 的地图工具库，从 `tzr` 项目 `src/components/cesiumMap/js` 提取，包含 **21 个** 核心 JS 模块（含 `toolbar` 子目录 4 个文件）。
+
+## 安装
+
+```bash
+npm install huweili-cesium
+```
+
+### 对等依赖（需在项目中已安装）
+
+- `cesium`
+- `vue` ^3.3
+- `pinia` ^2 或 ^3
+- `mitt` ^3
+- `qrcode` ^1.5
+
+## 使用前准备
+
+1. 在 HTML 中加载与宿主项目一致的 `constants.js`（定义 `window.DroneStatus`、`window.MapInstanceIds` 等），或自行赋值这些全局变量。
+2. 在 Vue 应用中 `app.use(pinia)`，地图组件初始化后调用各 `*Config()` 工厂函数。
+
+## 引入示例
+
+```js
+// 统一入口
+import { basicConfig, setPoint, movePointConfig } from 'huweili-cesium'
+
+// 或按文件引入
+import { basicConfig } from 'huweili-cesium/basis'
+import { hemisphereConfig } from 'huweili-cesium/hemisphere'
+import { createCustomToolbarButtons } from 'huweili-cesium/customToolbarButtons'
+```
+
+## 可选业务钩子
+
+若需光电引导、轨迹列表等业务能力，在应用启动时注入：
+
+```js
+import { setDroneMapProvider, setOptGuideHandler } from 'huweili-cesium/config/hooks'
+
+setDroneMapProvider(() => myDroneMap)
+setOptGuideHandler((payload) => api.toOptGuide(payload))
+```
+
+## 发布到 npm（维护者）
+
+```bash
+cd huweili-cesium
+npm login
+npm publish
+```
+
+首次发布前可在本地打包预览：
+
+```bash
+npm pack
+# 会生成 huweili-cesium-1.0.0.tgz，解压检查是否包含全部 js
+```
+
+## 从 tzr 源目录同步更新
+
+```bash
+cd huweili-cesium
+npm run sync
+# 同步后需重新修复 @/ 别名为包内相对路径（见 scripts）
+```
+
+## 包含的文件清单
+
+| 文件 | 说明 |
+|------|------|
+| basis.js | 地图基础操作 |
+| setPoint.js / movePoint.js | 点位与移动 |
+| setPath.js / movePath.js | 路径与轨迹 |
+| groundLink.js | 地面连接线 |
+| hemisphere.js | 半球区域 |
+| geometry.js | 几何图形 |
+| drawFence.js / drawFenceNew.js | 电子围栏 |
+| cardPool.js / labelDiv.js | 信息牌 |
+| clickHandler.js | 点击交互 |
+| tileProviders.js | 底图瓦片 |
+| customToolbarButtons.js | 工具栏 |
+| toolbar/* | 指南针、底图切换、缩放、全屏 |
+| droneRipple.js / qrCodeGenerator.js | 涟漪、二维码 |
+
+另含 `stores/mapStore.js`、`utils/*`、`config/*` 等运行依赖。

package/api/gaode.js

@@ -0,0 +1,16 @@
+/**
+ * 逆地理编码（可选）
+ * 宿主项目可覆盖：import { setGeocodeProvider } from 'huweili-cesium/api/gaode'
+ */
+let geocodeProvider = null
+
+export function setGeocodeProvider(fn) {
+  geocodeProvider = fn
+}
+
+export function getAddressByLocation(lng, lat) {
+  if (geocodeProvider) {
+    return geocodeProvider(lng, lat)
+  }
+  return Promise.resolve('')
+}

package/basis.js

@@ -0,0 +1,335 @@
+/**
+ * 地图基本操作模块
+ * 
+ * 提供在Cesium地图上基本操作的功能，如设置地图中心点、添加鼠标事件控制器等
+ * 支持在地图上添加鼠标事件控制器，如点击、拖动、缩放等
+ * 
+ * @author huweili
+ * @email czxyhuweili@163.com
+ * @version 1.0.0
+ */
+import * as Cesium from 'cesium'
+import { useMapStore } from '../stores/mapStore.js'
+
+export function basicConfig() {
+
+  // 获取地图store实例
+  const mapStore = useMapStore()
+
+  /**
+   * 检查坐标是否在中国境内
+   * @param {*} longitude - 经度
+   * @param {*} latitude - 纬度
+   * @returns - 是否在中国境内
+   */
+  const isInChina = (longitude, latitude) => {
+    // 中国大致经纬度范围
+    // 经度: 73°33′E 至 135°05′E
+    // 纬度: 3°51′N 至 53°33′N
+    return longitude >= 73.55 && longitude <= 135.08 && latitude >= 3.85 && latitude <= 53.55
+  }
+
+  /**
+   * 设置Cesium地图时间为当前北京时间
+   * @param mapId - 地图实例ID，可选，不传则使用当前实例
+   */
+  const setBeiJingTime = (mapId) => {
+    const map = mapStore.getMap(mapId)
+    if (!map) return
+    // 强制设置时间为当前北京时间
+    const now = new Date()
+    const chinaTime = new Date(now.getTime() + 8 * 60 * 60 * 1000)
+    map.clock.currentTime = Cesium.JulianDate.fromDate(chinaTime)
+    // 如果你不想动画效果，可以暂停时钟
+    map.clock.shouldAnimate = true
+  }
+
+  /**
+   * 鼠标事件控制器
+   * 
+   * 处理地图上的鼠标事件，包括点击、拖动、缩放等、
+   * @param map - 地图实例
+   */
+  const mouseController = (map) => {
+    // 添加右键点击事件监听
+    map.screenSpaceEventHandler.setInputAction((click) => {
+      // 获取点击位置的笛卡尔坐标
+      const cartesian = map.camera.pickEllipsoid(click.position, map.scene.globe.ellipsoid);
+
+      if (cartesian) {
+        // 转换为经纬度
+        const cartographic = Cesium.Cartographic.fromCartesian(cartesian);
+        const lng = Cesium.Math.toDegrees(cartographic.longitude);
+        const lat = Cesium.Math.toDegrees(cartographic.latitude);
+        const height = cartographic.height;
+
+        console.log('点击位置:', {
+          lng: Number(lng),
+          lat: Number(lat),
+          height: Number(height)
+        });
+
+        // 弹出alert显示坐标信息
+        // alert(`点击位置坐标：\n经度：${Number(lng).toFixed(6)}\n纬度：${Number(lat).toFixed(6)}\n高度：${Number(height).toFixed(2)}米`);
+      }
+    }, Cesium.ScreenSpaceEventType.RIGHT_CLICK);
+
+    // 添加左键点击事件，用于隐藏弹窗
+    map.screenSpaceEventHandler.setInputAction(() => {
+      console.log('左键点击事件触发')
+    }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+  }
+
+  /**
+   * 设置地图中心点
+   * 
+   * @param options - 包含地图中心点经纬度和高度的对象
+   * @param options.lng - 地图中心点经度
+   * @param options.lat - 地图中心点纬度
+   * @param options.alt - 可选，镜头高度/相机距离，默认 10000
+   * @param options.targetAlt - 可选，看向目标点的高度，例如飞机高度，默认 0
+   * @param options.map - 地图实例，可选，默认从store中获取
+   * @param options.mapId - 地图实例ID，可选，不传则使用当前实例
+   */
+  const setCesiumCenter = (options) => {
+    const { lng, lat, alt: altitude, targetAlt, map: mapInstance, mapId } = options
+
+    const map = mapInstance || mapStore.getMap(mapId)
+    if (!map) {
+      console.error('地图实例不存在')
+      return null
+    }
+
+    const centerInfo = mapStore.getMapInfo('center', mapId) || {}
+    // 优先级：传入的 altitude > 配置文件中的 centerInfo.alt > 默认值 10000
+    const finalAltitude = altitude !== undefined ? altitude : (centerInfo.alt || 10000)
+    // targetAlt 是看向目标点的高度，例如飞机高度；不要和视角高度 alt 混用
+    const finalTargetAlt = targetAlt !== undefined ? targetAlt : (centerInfo.targetAlt || 0)
+    
+    // 检查当前是正交投影（2D）还是透视投影（3D）
+    const isOrthographic = map.camera.frustum instanceof Cesium.OrthographicFrustum
+    
+    if (isOrthographic) {
+      // 2D 俯视视角
+      set2DView(map, lng, lat, finalAltitude)
+    } else {
+      // 3D 斜视视角
+      set3DView(map, lng, lat, centerInfo, finalAltitude, finalTargetAlt)
+    }
+  }
+
+
+
+  /******************************************************2、3维视角切换**************************************************************************** */
+  
+  /**
+   * 获取当前RTK经纬度
+   * @param {string=} mapId 地图实例ID
+   * @returns {{lng: number, lat: number}|null}
+   */
+  const getCurrentRtkPosition = (mapId) => {
+    const rtkData = mapStore.getRtkData(mapId)
+    const lng = Number(rtkData?.longitude)
+    const lat = Number(rtkData?.latitude)
+
+    if (!Number.isFinite(lng) || !Number.isFinite(lat)) {
+      return null
+    }
+
+    return { lng, lat }
+  }
+
+  /**
+   * 恢复 3D 透视投影
+   * @param {object} map Cesium 地图实例
+   */
+  const restorePerspectiveFrustum = (map) => {
+    if (!map) return
+
+    const currentFrustum = map.camera.frustum
+    const perspectiveFrustum = new Cesium.PerspectiveFrustum()
+    perspectiveFrustum.fov = Cesium.Math.toRadians(60)
+    perspectiveFrustum.aspectRatio = map.canvas.clientWidth / map.canvas.clientHeight
+    perspectiveFrustum.near = currentFrustum.near || 1.0
+    perspectiveFrustum.far = currentFrustum.far || 10000000.0
+    map.camera.frustum = perspectiveFrustum
+  }
+
+  /**
+   * 设置 2D 俯视用的正交投影
+   * @param {object} map Cesium 地图实例
+   */
+  const applyOrthographicFrustum = (map) => {
+    if (!map) return
+
+    const canvas = map.canvas
+    const frustum = new Cesium.OrthographicFrustum()
+    const width = canvas.clientWidth
+    const height = canvas.clientHeight
+    
+    // 检查当前是否是透视投影，只有透视投影才有 fovy
+    let widthValue
+    if (map.scene.camera.frustum instanceof Cesium.PerspectiveFrustum) {
+      widthValue = width * map.scene.camera.frustum.fovy * map.scene.camera.positionCartographic.height / 1000
+    } else {
+      // 如果已经是正交投影，保留当前宽度或使用默认值
+      widthValue = map.scene.camera.frustum.width || 20000
+    }
+    
+    frustum.width = widthValue
+    frustum.aspectRatio = width / height
+    frustum.near = 0.1
+    frustum.far = 10000000.0
+    map.scene.camera.frustum = frustum
+  }
+
+  /**
+   * 设置并锁定2D俯视视角（禁止通过中键拖动进入3D姿态）
+   * @param {object} map Cesium 地图实例
+   * @param {number} lng 经度
+   * @param {number} lat 纬度
+   * @param {number=} height 相机高度
+   */
+  const set2DView = (map, lng, lat, height = 10000) => {
+    if (!map) return
+    applyOrthographicFrustum(map)
+    const cameraController = map.scene?.screenSpaceCameraController
+    if (cameraController) {
+      cameraController.enableTilt = false
+      cameraController.enableLook = false
+    }
+    map.camera.setView({
+      destination: Cesium.Cartesian3.fromDegrees(lng, lat, height),
+      orientation: {
+        heading: Cesium.Math.toRadians(0),
+        pitch: Cesium.Math.toRadians(-90),
+        roll: Cesium.Math.toRadians(0)
+      }
+    })
+  }
+
+  /**
+   * 设置3D斜视视角（恢复透视投影，让相机看向指定目标点）
+   * 
+   * 简单理解：就像你站在高楼上看地面上的目标
+   * - 你站的位置高度 = altitude
+   * - 你看向的目标点 = (lng, lat, targetAlt)
+   * - 你的视线角度 = heading(朝向) + pitch(俯仰)
+   * 
+   * @param {object} map Cesium 地图实例（必须传）
+   * @param {number} lng 目标点的经度（比如无人机所在位置）
+   * @param {number} lat 目标点的纬度
+   * @param {Object=} centerInfo 视角配置（可选）
+   * @param {number} [centerInfo.heading=0] 水平朝向角度（0=正北，90=正东）
+   * @param {number} [centerInfo.pitch=-35] 俯仰角度（负数=向下看，-90=正俯视）
+   * @param {number=} altitude 相机高度（单位：米，默认10000米）
+   * @param {number=} targetAlt 目标点的高度（比如无人机的飞行高度，默认0）
+   */
+  const set3DView = (map, lng, lat, centerInfo = {}, altitude = 10000, targetAlt = 0) => {
+    // 1. 检查地图实例是否存在，不存在就直接返回
+    if (!map) return
+
+    // 2. 恢复3D透视投影（让地图可以有立体感）
+    restorePerspectiveFrustum(map)
+
+    // 3. 获取相机控制器，允许用户之后可以倾斜和旋转视角
+    const cameraController = map.scene?.screenSpaceCameraController
+    if (cameraController) {
+      cameraController.enableTilt = true   // 允许倾斜（上下看）
+      cameraController.enableLook = true   // 允许旋转（左右看）
+    }
+
+    // 4. 处理俯仰角度（视线上下倾斜的角度）
+    //    pitch范围：0度=水平向前看，-90度=正俯视，-35度=稍微向下看
+    //    这里防止配置的角度太极端（<= -80度几乎就是俯视了，强制改成-35度）
+    const configuredPitch = centerInfo.pitch ?? -35  // 用配置的值，没有就用默认-35度
+    const targetPitch = configuredPitch <= -80 ? -35 : configuredPitch  // 防止角度太极端
+    const pitchRadians = Cesium.Math.toRadians(targetPitch)  // 角度转弧度（Cesium用弧度计算）
+
+    // 5. 处理目标点高度（比如无人机的飞行高度）
+    const targetAltNumber = Number(targetAlt)  // 转成数字
+    const finalTargetAlt = Number.isFinite(targetAltNumber) ? targetAltNumber : 0  // 确保是有效数字
+    // 把经纬度+高度转成Cesium能识别的三维坐标（笛卡尔坐标）
+    const targetPosition = Cesium.Cartesian3.fromDegrees(lng, lat, finalTargetAlt)
+
+    // 6. 处理相机高度（我们想让相机飞多高）
+    const altitudeNumber = Number(altitude)
+    const finalAltitude = Number.isFinite(altitudeNumber) ? altitudeNumber : 10000
+
+    // 7. 计算相机到目标点的直线距离（重点！）
+    //    HeadingPitchRange的range是"直线距离"，不是高度
+    //    想象一下：你站在100米高的地方，视线向下30度看地面
+    //    你到目标点的直线距离 = 高度 / sin(俯仰角)
+    //    用Math.max(..., 0.1)防止sin值太小导致距离过大
+    const range = finalAltitude / Math.max(Math.sin(Math.abs(pitchRadians)), 0.1)
+
+    // 8. 设置相机看向目标点
+    //    HeadingPitchRange：一种描述相机位置的方式
+    //    - heading: 水平朝向（比如0=正北看）
+    //    - pitch: 俯仰角度（向下为负）
+    //    - range: 相机到目标点的直线距离
+    map.camera.lookAt(
+      targetPosition,  // 看向的目标点
+      new Cesium.HeadingPitchRange(
+        Cesium.Math.toRadians(centerInfo.heading ?? 0),  // 朝向转弧度
+        pitchRadians,  // 俯仰角（弧度）
+        range          // 直线距离
+      )
+    )
+
+    // 9. 重置相机变换（确保lookAt生效后恢复正常状态）
+    map.camera.lookAtTransform(Cesium.Matrix4.IDENTITY)
+  }
+
+  /**
+   * 在两种俯仰视角之间切换
+   * 注意：这里只切换相机视角，不切换 Cesium 的 2D/3D 模式
+   * @param {string=} mapId 地图实例ID
+   */
+  const toggleViewToRtk = (mapId) => {
+    const map = mapStore.getMap(mapId)
+    const rtkPosition = getCurrentRtkPosition(mapId)
+
+    if (!map || !rtkPosition) {
+      return { success: false, currentMode: null }
+    }
+
+    const centerInfo = mapStore.getMapInfo('center', mapId) || {}
+    let { lng, lat } = rtkPosition
+    
+    if (lng === 0 && lat === 0) {
+      lng = centerInfo.lng ?? lng
+      lat = centerInfo.lat ?? lat
+    }
+    
+    const camera = map.camera
+    const isOrthographic = camera.frustum instanceof Cesium.OrthographicFrustum
+    const nextAlt = centerInfo.alt ?? 10000 
+
+    let currentMode
+    // 切换视角
+    if (isOrthographic) {
+      // 当前是正交投影（俯视），切换到透视投影（斜视）
+      set3DView(map, lng, lat, centerInfo, 10000)
+      currentMode = '3D'
+    } else {
+      // 当前是透视投影，切换到正交投影（俯视）
+      set2DView(map, lng, lat, nextAlt)
+      currentMode = '2D'
+    }
+
+    return { success: true, currentMode }
+  }
+
+  return {
+    isInChina,
+    mouseController,
+    setCesiumCenter,
+    setBeiJingTime,
+    toggleViewToRtk,
+    set2DView,
+    set3DView,
+    applyOrthographicFrustum,
+    restorePerspectiveFrustum
+  }
+}