huweili-cesium 1.2.87 → 1.2.89

package/index.vue

@@ -16,6 +16,15 @@ import { useMapStore, MapLoadStatus } from './js/stores/mapStore.js'
 import { useEventBus } from './js/utils/useEventBus.js'
 import { processMapConfigColors } from './js/tileProviders.js'
 import { applyImageryLayers, resolveOnlineBasemap } from './js/utils/mapImagery.js'
+import {
+  ensureTerrainConfig,
+  resolveTerrainConfig,
+  createTerrainProvider,
+  applyTerrain,
+  isTerrainEnabled,
+  syncTerrainConfig,
+} from './js/utils/terrainProvider.js'
+import { resampleAllMapFences } from './js/utils/terrainHeight.js'
 import { createCustomToolbarButtons } from './js/customToolbarButtons.js'
 const { merge } = objectUtils()
 const { mouseController, setInitialCameraView, syncCameraInteractionMode } = basicConfig()
@@ -89,6 +98,25 @@ const handleSceneModeChange = ({ mapId, sceneMode }) => {
   syncCameraInteractionMode(map, mapId, sceneMode)
 }
 
+/**
+ * 处理地形开关变化（地图外 UI 通过事件总线触发）
+ *
+ * 用法示例（宿主页面）：
+ * emit('map-terrain-changed', { mapId: 'home-main-map', show: true })
+ * emit('map-terrain-changed', { mapId: 'home-main-map', url: '/terrain' })
+ *
+ * @param {Object} param
+ * @param {string} param.mapId - 地图实例 ID
+ * @param {boolean} [param.show] - 是否启用地形
+ * @param {string} [param.url] - 地形服务地址（离线数据替换此 url 即可）
+ */
+const handleTerrainChange = async ({ mapId, show, url }) => {
+  if (mapId !== props.mapId || !map || map.isDestroyed?.()) return
+  await syncTerrainConfig(map, MapConfig, { show, url })
+  await resampleAllMapFences(mapStore, props.mapId)
+  map.render()
+}
+
 const cesiumContainer = ref(null)
 let map = null
 let customButtons = []
@@ -151,6 +179,7 @@ const initCesium = async () => {
 
   if (mapOptions) {
     mapOptions = processMapConfigColors(mapOptions)
+    ensureTerrainConfig(mapOptions)
   }
 
   try {
@@ -169,12 +198,16 @@ const initCesium = async () => {
       infoBox: mapOptions.control.infoBox, // 实体信息弹窗
       fullscreenButton: mapOptions.control.fullscreenButton, // 全屏按钮
       vrButton: mapOptions.control.vrButton, // VR 模式按钮
-      terrainProvider: mapOptions.terrain.show // 地形服务；不开启时为 undefined
-        ? await Cesium.CesiumTerrainProvider.fromUrl(mapOptions.terrain.url, {
-            requestWaterMask: mapOptions.terrain.coastlineData, // 水体效果所需海岸线数据
-            requestVertexNormals: mapOptions.terrain.lightingData, // 地形光照法线数据
-          })
-        : undefined,
+      terrainProvider: await (async () => {
+        const terrainConfig = resolveTerrainConfig(mapOptions)
+        if (!terrainConfig.show) return undefined
+        try {
+          return await createTerrainProvider(terrainConfig)
+        } catch (error) {
+          console.error('初始地形加载失败，将使用默认椭球地形:', error)
+          return undefined
+        }
+      })(),
       terrainShadows: Cesium.ShadowMode.RECEIVE_ONLY, // 地形只接收阴影，不投射，节省性能
       creditContainer: document.createElement('div'), // 用空容器替换默认版权水印区域
     }
@@ -228,6 +261,15 @@ const initCesium = async () => {
       console.warn('未找到可用底图，Cesium 将使用默认底图或空底图显示')
     }
 
+    const terrainConfig = resolveTerrainConfig(mapOptions)
+    if (terrainConfig.show) {
+      if (isTerrainEnabled(map)) {
+        console.log(`地形已启用，URL：${terrainConfig.url}`)
+      } else {
+        console.warn(`地形开关已开启但未加载成功，请检查 mapConfig.terrain.url：${terrainConfig.url}`)
+      }
+    }
+
     if (map.screenSpaceEventHandler && mapOptions.control.disableDoubleClick) {
       // 移除双击左键事件，防止地图缩放
       map.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
@@ -277,6 +319,25 @@ const initCesium = async () => {
         removeToolbarButtons, // 移除工具栏按钮
       },
       syncCameraInteractionMode: (mode) => syncCameraInteractionMode(map, props.mapId, mode), // 同步相机交互模式
+      terrain: {
+        getEnabled: () => isTerrainEnabled(map),
+        getConfig: () => resolveTerrainConfig(mapOptions),
+        setEnabled: async (show) => {
+          await syncTerrainConfig(map, MapConfig, { show })
+          map?.render()
+          return isTerrainEnabled(map)
+        },
+        setUrl: async (url) => {
+          await syncTerrainConfig(map, MapConfig, { url, show: true })
+          map?.render()
+          return isTerrainEnabled(map)
+        },
+        apply: async (config = {}) => {
+          await syncTerrainConfig(map, MapConfig, config)
+          map?.render()
+          return isTerrainEnabled(map)
+        },
+      },
     })
 
     map.resize() // 调整地图尺寸
@@ -414,6 +475,7 @@ onMounted(() => {
   mapStore.setCurrentMapId(props.mapId) // 初始化当前地图ID
   setupActivityListeners() // 初始化用户活动监听器，用于判断是否需要继续渲染地图，避免空闲超时导致的渲染暂停
   onEvent('map-scene-mode-changed', handleSceneModeChange) // 监听场景模式变化事件，用于同步相机交互模式
+  onEvent('map-terrain-changed', handleTerrainChange) // 监听地形开关变化（地图外 UI 控制）
   initCesium() // 初始化 Cesium 地图实例
 })
 
@@ -439,6 +501,7 @@ onUnmounted(() => {
   isMapActive = false
   stopRenderLoop() // 停止持续渲染循环，释放资源
   offEvent('map-scene-mode-changed', handleSceneModeChange) // 移除场景模式变化事件监听器
+  offEvent('map-terrain-changed', handleTerrainChange) // 移除地形开关变化事件监听器
   if (map) {
     teardownOrthographicWheelZoom(map) // 移除正交投影滚轮缩放事件监听器
   }

package/js/drawFenceNew.js

@@ -11,6 +11,15 @@
 import * as Cesium from 'cesium'
 import { useMapStore } from './stores/mapStore.js'
 import { BaseConfig } from './config/index.js'
+import {
+  applyTerrainWallToEntity,
+  cartesianFootprintFromLngLat,
+  cartesianToLngLat,
+  generateCircleLngLatPositions,
+  getCenterLngLat,
+  resampleAllMapFences,
+  sampleTerrainHeights,
+} from './utils/terrainHeight.js'
 
 export function drawFenceNew() {
   const mapStore = useMapStore()
@@ -126,14 +135,7 @@ export function drawFenceNew() {
       return cartesianToGroundCartesian(cartesian)
     }
 
-    const cartesianToLngLatHeight = (cartesian) => {
-      const cartographic = Cesium.Cartographic.fromCartesian(cartesian)
-      return {
-        lng: Cesium.Math.toDegrees(cartographic.longitude),
-        lat: Cesium.Math.toDegrees(cartographic.latitude),
-        height: 0
-      }
-    }
+    const cartesianToLngLatHeight = (cartesian) => cartesianToLngLat(cartesian)
 
     const getPolylinePositions = () => {
       if (positions.length === 0) return []
@@ -155,23 +157,10 @@ export function drawFenceNew() {
       return wallPositions
     }
 
-    const getPolygonCenter = (polygonPositions = []) => {
-      const validPositions = polygonPositions.filter(Boolean)
-      if (!validPositions.length) return null
-
-      const lngLatList = validPositions.map(item => cartesianToLngLatHeight(item))
-      const total = lngLatList.reduce((sum, item) => {
-        sum.lng += item.lng
-        sum.lat += item.lat
-        sum.height += item.height || 0
-        return sum
-      }, { lng: 0, lat: 0, height: 0 })
-
-      return Cesium.Cartesian3.fromDegrees(
-        total.lng / lngLatList.length,
-        total.lat / lngLatList.length,
-        total.height / lngLatList.length
-      )
+    const getPolygonCenterCartesian = (lngLatList, terrainHeights) => {
+      if (!lngLatList?.length) return null
+      const center = getCenterLngLat(lngLatList, terrainHeights)
+      return Cesium.Cartesian3.fromDegrees(center.lng, center.lat, center.height)
     }
 
     const createFenceNameLabel = (position, text = '') => {
@@ -245,8 +234,8 @@ export function drawFenceNew() {
             positions: new Cesium.CallbackProperty(() => getPolylinePositions(), false),
             width: outlineWidth,
             material: color,
-            clampToGround: false,
-            arcType: Cesium.ArcType.NONE
+            clampToGround: true,
+            arcType: Cesium.ArcType.GEODESIC
           }
         })
       }
@@ -324,7 +313,7 @@ export function drawFenceNew() {
       map.cesiumWidget.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
     }
 
-    const finalize = () => {
+    const finalize = async () => {
       if (isFinished) return null
 
       if (positions.length < 3) {
@@ -335,9 +324,11 @@ export function drawFenceNew() {
       isFinished = true
       destroyHandler()
 
-      const finalPositions = positions.map(item => Cesium.Cartesian3.clone(item))
+      const finalPositions = positions.map((item) => Cesium.Cartesian3.clone(item))
+      const lngLatList = finalPositions.map((item) => cartesianToLngLatHeight(item))
+      const terrainHeights = await sampleTerrainHeights(map, lngLatList)
       const finalWallPositions = [...finalPositions, finalPositions[0]]
-      const lngLatPositions = finalPositions.map(item => cartesianToLngLatHeight(item))
+      const lngLatPositions = lngLatList.map(({ lng, lat }) => ({ lng, lat }))
 
       const fenceName = options.name || `多边形电子围栏-${options.id}`
       const fenceEntity = wallEntity || map.entities.add({
@@ -355,30 +346,30 @@ export function drawFenceNew() {
           positions: finalWallPositions,
           width: outlineWidth,
           material: color,
-          clampToGround: false,
-          arcType: Cesium.ArcType.NONE
+          clampToGround: true,
+          arcType: Cesium.ArcType.GEODESIC
         }
       })
 
       fenceEntity.name = fenceName
       fenceEntity.wall.positions = finalWallPositions
-      fenceEntity.wall.maximumHeights = finalWallPositions.map(() => height)
-      fenceEntity.wall.minimumHeights = finalWallPositions.map(() => 0)
       fenceEntity.wall.material = color.withAlpha(0.18)
       fenceEntity.wall.outline = true
       fenceEntity.wall.outlineColor = color
 
+      await applyTerrainWallToEntity(map, fenceEntity, lngLatList, height)
+
       if (polylineEntity) {
         map.entities.remove(polylineEntity)
         polylineEntity = null
       }
 
       fenceEntity.polyline = {
-        positions: finalWallPositions,
+        positions: fenceEntity.wall.positions,
         width: outlineWidth,
         material: color,
-        clampToGround: false,
-        arcType: Cesium.ArcType.NONE
+        clampToGround: true,
+        arcType: Cesium.ArcType.GEODESIC
       }
 
       if (activePointEntity) {
@@ -394,7 +385,7 @@ export function drawFenceNew() {
       wallEntity = null
       cleanupPointEntities()
 
-      const centerCartesian = getPolygonCenter(finalPositions)
+      const centerCartesian = getPolygonCenterCartesian(lngLatList, terrainHeights)
       const withLabel = options.withLabel !== false
       let labelEntity = null
       if (withLabel) {
@@ -406,6 +397,7 @@ export function drawFenceNew() {
 
       fenceEntity._originalOptions = {
         ...options,
+        type: 'polygon',
         positions: lngLatPositions,
         height,
         color: options.color || '#00ffff',
@@ -446,6 +438,7 @@ export function drawFenceNew() {
         options.onFinish(result)
       }
 
+      map.scene.requestRender()
       return result
     }
 
@@ -501,11 +494,11 @@ export function drawFenceNew() {
     }, Cesium.ScreenSpaceEventType.MOUSE_MOVE)
 
     handler.setInputAction(() => {
-      finalize()
+      finalize().catch((error) => console.error('多边形围栏完成绘制失败:', error))
     }, Cesium.ScreenSpaceEventType.RIGHT_CLICK)
 
     handler.setInputAction(() => {
-      finalize()
+      finalize().catch((error) => console.error('多边形围栏完成绘制失败:', error))
     }, Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
 
     map.cesiumWidget.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
@@ -578,24 +571,9 @@ export function drawFenceNew() {
     const opacity = options.opacity ?? 0.35
     const outlineWidth = options.outlineWidth ?? 3
 
-    const lngLatToCartesian = (lngLat) => {
-      return Cesium.Cartesian3.fromDegrees(lngLat.lng, lngLat.lat, lngLat.height || 0)
-    }
-
-    const finalPositions = options.positions.map(pos => lngLatToCartesian(pos))
+    const lngLatList = options.positions.map((pos) => ({ lng: pos.lng, lat: pos.lat }))
+    const finalPositions = lngLatList.map(cartesianFootprintFromLngLat)
     const finalWallPositions = [...finalPositions, finalPositions[0]]
-    const center = options.positions.reduce((sum, item) => {
-      sum.lng += item.lng
-      sum.lat += item.lat
-      sum.height += item.height || 0
-      return sum
-    }, { lng: 0, lat: 0, height: 0 })
-    const centerData = {
-      lng: center.lng / options.positions.length,
-      lat: center.lat / options.positions.length,
-      height: center.height / options.positions.length
-    }
-    const centerCartesian = Cesium.Cartesian3.fromDegrees(centerData.lng, centerData.lat, centerData.height || 0)
     const fenceName = options.name || `多边形电子围栏-${options.id}`
 
     const fenceEntity = map.entities.add({
@@ -613,13 +591,20 @@ export function drawFenceNew() {
         positions: finalWallPositions,
         width: outlineWidth,
         material: color,
-        clampToGround: false,
-        arcType: Cesium.ArcType.NONE
+        clampToGround: true,
+        arcType: Cesium.ArcType.GEODESIC
       }
     })
 
     const withLabel = options.withLabel !== false
     let labelEntity = null
+    const centerData = {
+      lng: lngLatList.reduce((sum, p) => sum + p.lng, 0) / lngLatList.length,
+      lat: lngLatList.reduce((sum, p) => sum + p.lat, 0) / lngLatList.length,
+      height: 0,
+    }
+    const centerCartesian = Cesium.Cartesian3.fromDegrees(centerData.lng, centerData.lat, 0)
+
     if (withLabel) {
       labelEntity = map.entities.add({
         id: `${options.id}_fence_name_label`,
@@ -644,7 +629,8 @@ export function drawFenceNew() {
     fenceEntity._labelEntity = labelEntity
     fenceEntity._originalOptions = {
       ...options,
-      positions: options.positions,
+      type: 'polygon',
+      positions: lngLatList,
       height,
       color: options.color || '#00ffff',
       opacity,
@@ -653,6 +639,32 @@ export function drawFenceNew() {
 
     mapStore.setGraphicMap(options.id, fenceEntity, options.mapId)
 
+    const applyHeights = async () => {
+      const terrainHeights = await sampleTerrainHeights(map, lngLatList)
+      await applyTerrainWallToEntity(map, fenceEntity, lngLatList, height)
+      const center = getCenterLngLat(lngLatList, terrainHeights)
+      centerData.lng = center.lng
+      centerData.lat = center.lat
+      centerData.height = center.height
+      if (labelEntity) {
+        labelEntity.position = Cesium.Cartesian3.fromDegrees(center.lng, center.lat, center.height)
+      }
+      if (options.zoomTo) {
+        map.flyTo(fenceEntity)
+      }
+      map.scene.requestRender()
+      if (typeof options.onReady === 'function') {
+        options.onReady({
+          id: options.id,
+          entity: fenceEntity,
+          labelEntity,
+          center: centerData,
+        })
+      }
+    }
+
+    applyHeights().catch((error) => console.error('多边形围栏回显贴地失败:', error))
+
     if (options.show === false) {
       fenceEntity.show = false
       if (labelEntity) {
@@ -660,15 +672,11 @@ export function drawFenceNew() {
       }
     }
 
-    if (options.zoomTo) {
-      map.flyTo(fenceEntity)
-    }
-
     return {
       id: options.id,
       entity: fenceEntity,
       labelEntity,
-      positions: options.positions,
+      positions: lngLatList,
       cartesianPositions: finalPositions,
       center: centerData,
       centerCartesian,
@@ -814,33 +822,37 @@ export function drawFenceNew() {
     const height = options.height ?? 2
     const opacity = options.opacity ?? 0.35
     const outlineWidth = options.outlineWidth ?? 3
-
-    const centerCartesian = Cesium.Cartesian3.fromDegrees(
-      options.center.lng,
-      options.center.lat,
-      options.center.height || 0
-    )
-
+    const centerData = { lng: options.center.lng, lat: options.center.lat, height: 0 }
+    const circleLngLats = generateCircleLngLatPositions(centerData.lng, centerData.lat, options.radius)
+    const footprint = circleLngLats.map(cartesianFootprintFromLngLat)
+    const wallPositions = [...footprint, footprint[0]]
     const fenceName = options.name || `圆形电子围栏-${options.id}`
+
     const fenceEntity = map.entities.add({
       id: options.id,
       name: fenceName,
-      position: centerCartesian,
-      ellipse: {
-        semiMajorAxis: options.radius,
-        semiMinorAxis: options.radius,
-        height: 0,
-        extrudedHeight: height,
-        material: color.withAlpha(0),
+      wall: {
+        positions: wallPositions,
+        maximumHeights: wallPositions.map(() => height),
+        minimumHeights: wallPositions.map(() => 0),
+        material: color.withAlpha(opacity),
         outline: true,
         outlineColor: color,
-        outlineWidth,
-        numberOfVerticalLines: 64
+        outlineWidth
+      },
+      polyline: {
+        positions: wallPositions,
+        width: outlineWidth,
+        material: color,
+        clampToGround: true,
+        arcType: Cesium.ArcType.GEODESIC
       }
     })
 
     const withLabel = options.withLabel !== false
     let labelEntity = null
+    const centerCartesian = Cesium.Cartesian3.fromDegrees(centerData.lng, centerData.lat, 0)
+
     if (withLabel) {
       labelEntity = map.entities.add({
         id: `${options.id}_fence_name_label`,
@@ -865,7 +877,8 @@ export function drawFenceNew() {
     fenceEntity._labelEntity = labelEntity
     fenceEntity._originalOptions = {
       ...options,
-      center: options.center,
+      type: 'circle',
+      center: centerData,
       radius: options.radius,
       height,
       color: options.color || '#00ffff',
@@ -875,6 +888,29 @@ export function drawFenceNew() {
 
     mapStore.setGraphicMap(options.id, fenceEntity, options.mapId)
 
+    const applyHeights = async () => {
+      await applyTerrainWallToEntity(map, fenceEntity, circleLngLats, height)
+      const centerHeights = await sampleTerrainHeights(map, [centerData])
+      centerData.height = centerHeights[0] || 0
+      if (labelEntity) {
+        labelEntity.position = Cesium.Cartesian3.fromDegrees(centerData.lng, centerData.lat, centerData.height)
+      }
+      if (options.zoomTo) {
+        map.flyTo(fenceEntity)
+      }
+      map.scene.requestRender()
+      if (typeof options.onReady === 'function') {
+        options.onReady({
+          id: options.id,
+          entity: fenceEntity,
+          labelEntity,
+          center: centerData,
+        })
+      }
+    }
+
+    applyHeights().catch((error) => console.error('圆形围栏回显贴地失败:', error))
+
     if (options.show === false) {
       fenceEntity.show = false
       if (labelEntity) {
@@ -882,16 +918,12 @@ export function drawFenceNew() {
       }
     }
 
-    if (options.zoomTo) {
-      map.flyTo(fenceEntity)
-    }
-
     return {
       id: options.id,
       entity: fenceEntity,
       labelEntity,
-      center: options.center,
-      centerCartesian,
+      center: centerData,
+      centerCartesian: Cesium.Cartesian3.fromDegrees(centerData.lng, centerData.lat, centerData.height),
       radius: options.radius,
       height,
       name: fenceName
@@ -1030,15 +1062,7 @@ export function drawFenceNew() {
      * @param {Cartesian3} cartesian - 世界3D坐标
      * @returns {Object} - 经纬度高度对象 {lng: 经度, lat: 纬度, height: 高度}
      */
-    const cartesianToLngLatHeight = (cartesian) => {
-      // 先将Cartesian3转换为Cartographic（弧度制经纬度）
-      const cartographic = Cesium.Cartographic.fromCartesian(cartesian)
-      return {
-        lng: Cesium.Math.toDegrees(cartographic.longitude),  // 弧度 → 角度（经度）
-        lat: Cesium.Math.toDegrees(cartographic.latitude),   // 弧度 → 角度（纬度）
-        height: 0                                            // 圆形围栏绘制点统一贴地
-      }
-    }
+    const cartesianToLngLatHeight = (cartesian) => cartesianToLngLat(cartesian)
 
     /**
      * 计算当前围栏的半径（圆心到边界点的地表距离）
@@ -1201,60 +1225,54 @@ export function drawFenceNew() {
      * 【重要函数：完成绘制，生成最终围栏
      * 当用户第二次点击或右键点击时调用
      */
-    const finalize = () => {
-      // 如果已经完成过了，直接返回，防止重复执行
+    const finalize = async () => {
       if (isFinished) return null
 
-      // 检查是否满足绘制条件：必须有圆心，且半径大于0
       const radius = getRadius()
       if (!centerPosition || radius <= 0) {
         console.warn('至少需要 2 个点才能形成圆形电子围栏')
         return null
       }
 
-      // ==================== 步骤1：标记绘制完成，开始收尾工作
       isFinished = true
-      destroyHandler()  // 销毁事件监听器
+      destroyHandler()
+
+      const finalCenter = Cesium.Cartesian3.clone(centerPosition)
+      const finalEdge = Cesium.Cartesian3.clone(edgePosition)
+      const fenceName = options.name || `圆形电子围栏-${options.id}`
+      const centerData = cartesianToLngLatHeight(finalCenter)
+      const circleLngLats = generateCircleLngLatPositions(centerData.lng, centerData.lat, radius)
+      const footprint = circleLngLats.map(cartesianFootprintFromLngLat)
+      const wallPositions = [...footprint, footprint[0]]
 
-      // ==================== 步骤2：保存最终数据（clone一份防止被修改）
-      const finalCenter = Cesium.Cartesian3.clone(centerPosition)  // 最终圆心
-      const finalEdge = Cesium.Cartesian3.clone(edgePosition)  // 最终边界点
-      const fenceName = options.name || `圆形电子围栏-${options.id}`  // 围栏名称
+      if (ellipseEntity) {
+        map.entities.remove(ellipseEntity)
+        ellipseEntity = null
+      }
 
-      // ==================== 步骤3：创建或修改围栏实体
-      // 如果之前已有预览的ellipseEntity，就复用它；否则创建新的
-      const fenceEntity = ellipseEntity || map.entities.add({
+      const fenceEntity = map.entities.add({
         id: options.id,
         name: fenceName,
-        position: finalCenter,
-        ellipse: {
-          semiMajorAxis: radius,
-          semiMinorAxis: radius,
-          height: 0,
-          extrudedHeight: height,
-          material: color.withAlpha(0),
+        wall: {
+          positions: wallPositions,
+          maximumHeights: wallPositions.map(() => height),
+          minimumHeights: wallPositions.map(() => 0),
+          material: color.withAlpha(0.18),
           outline: true,
           outlineColor: color,
-          outlineWidth,
-          numberOfVerticalLines: 64
+          outlineWidth
+        },
+        polyline: {
+          positions: wallPositions,
+          width: outlineWidth,
+          material: color,
+          clampToGround: true,
+          arcType: Cesium.ArcType.GEODESIC
         }
       })
 
-      // 确保围栏实体的所有属性都是最终值（避免使用静态值，不再是CallbackProperty）
-      fenceEntity.name = fenceName
-      fenceEntity.position = finalCenter
-      fenceEntity.ellipse.semiMajorAxis = radius
-      fenceEntity.ellipse.semiMinorAxis = radius
-      fenceEntity.ellipse.height = 0
-      fenceEntity.ellipse.extrudedHeight = height
-      fenceEntity.ellipse.material = color.withAlpha(0)
-      fenceEntity.ellipse.outline = true
-      fenceEntity.ellipse.outlineColor = color
-      fenceEntity.ellipse.outlineWidth = outlineWidth
-      fenceEntity.ellipse.numberOfVerticalLines = 64
-
-      // ==================== 步骤4：清理临时实体
-      // 移除预览用的点、提示文字等临时实体（不再需要了）
+      await applyTerrainWallToEntity(map, fenceEntity, circleLngLats, height)
+
       ;[centerPointEntity, activePointEntity, tipEntity].forEach((entity) => {
         if (entity) {
           map.entities.remove(entity)
@@ -1263,12 +1281,15 @@ export function drawFenceNew() {
       centerPointEntity = null
       activePointEntity = null
       tipEntity = null
-      ellipseEntity = null
 
-      // ==================== 步骤5：保存原始配置（方便后续修改或回显
+      const centerHeights = await sampleTerrainHeights(map, [centerData])
+      const centerHeight = centerHeights[0] || 0
+      const centerCartesian = Cesium.Cartesian3.fromDegrees(centerData.lng, centerData.lat, centerHeight)
+
       fenceEntity._originalOptions = {
         ...options,
-        center: cartesianToLngLatHeight(finalCenter),
+        type: 'circle',
+        center: { lng: centerData.lng, lat: centerData.lat },
         edge: cartesianToLngLatHeight(finalEdge),
         radius,
         height,
@@ -1277,21 +1298,13 @@ export function drawFenceNew() {
         outlineWidth
       }
 
-      // ==================== 步骤6：将围栏存入地图存储（便于管理
       mapStore.setGraphicMap(options.id, fenceEntity, options.mapId)
 
-      // ==================== 步骤7：如果配置了zoomTo，就飞过去查看
-      if (options.zoomTo) {
-        map.flyTo(fenceEntity)
-      }
-
-      // ==================== 步骤8：创建围栏名称标签
-      const centerData = cartesianToLngLatHeight(finalCenter)
       nameLabelEntity = map.entities.add({
         id: `${options.id}_draw_circle_name_label`,
-        position: finalCenter,
+        position: centerCartesian,
         label: {
-          text: '',  // 暂时为空，可通过updateCircleFenceName来设置
+          text: '',
           font: BaseConfig.fenceLabelFont,
           fillColor: Cesium.Color.WHITE,
           style: Cesium.LabelStyle.FILL,
@@ -1305,27 +1318,27 @@ export function drawFenceNew() {
           distanceDisplayCondition: new Cesium.DistanceDisplayCondition(0, Number.POSITIVE_INFINITY)
         }
       })
-      // 将标签实体挂载到围栏实体上，方便后续管理
       fenceEntity._labelEntity = nameLabelEntity
-      
-      // ==================== 步骤9：构造返回结果对象
+
+      if (options.zoomTo) {
+        map.flyTo(fenceEntity)
+      }
+
       const result = {
         id: options.id,
         entity: fenceEntity,
-        center: centerData,
+        center: { lng: centerData.lng, lat: centerData.lat },
         edge: cartesianToLngLatHeight(finalEdge),
-        centerCartesian: finalCenter,
+        centerCartesian,
         edgeCartesian: finalEdge,
         radius,
         height,
-        // 数据库存储用的数据
         dbData: {
           id: options.id,
           type: 'circle',
           center: {
             lng: centerData.lng,
             lat: centerData.lat,
-            height: centerData.height || 0
           },
           radius: radius,
           height: height,
@@ -1337,11 +1350,11 @@ export function drawFenceNew() {
         }
       }
 
-      // ==================== 步骤10：触发完成回调
       if (typeof options.onFinish === 'function') {
         options.onFinish(result)
       }
 
+      map.scene.requestRender()
       return result
     }
 
@@ -1398,7 +1411,7 @@ export function drawFenceNew() {
       // 情况2：已有圆心 → 这是第二次点击，完成绘制
       edgePosition = Cesium.Cartesian3.clone(cartesian)
       emitChange()
-      finalize()  // 完成绘制
+      finalize().catch((error) => console.error('圆形围栏完成绘制失败:', error))
     }, Cesium.ScreenSpaceEventType.LEFT_CLICK)
 
     // ==================== 事件2：鼠标移动 ====================
@@ -1417,7 +1430,7 @@ export function drawFenceNew() {
 
     // ==================== 事件3：鼠标右键点击 ====================
     handler.setInputAction(() => {
-      finalize()  // 右键点击也可以完成绘制
+      finalize().catch((error) => console.error('圆形围栏完成绘制失败:', error))
     }, Cesium.ScreenSpaceEventType.RIGHT_CLICK)
 
     // ==================== 返回绘制控制器 ====================
@@ -1460,7 +1473,12 @@ export function drawFenceNew() {
     const labelEntity = entity._labelEntity || map.entities.getById(`${id}_fence_name_label`)
     if (labelEntity?.label) {
       labelEntity.label.text = finalName
-      labelEntity.position = entity.position
+      const center = entity._originalOptions?.center
+      if (center && !labelEntity.position) {
+        const cartographic = Cesium.Cartographic.fromDegrees(center.lng, center.lat)
+        const terrainHeight = map.scene.sampleHeight(cartographic) || 0
+        labelEntity.position = Cesium.Cartesian3.fromDegrees(center.lng, center.lat, terrainHeight)
+      }
     }
     entity._labelEntity = labelEntity || null
     return true
@@ -1543,6 +1561,7 @@ export function drawFenceNew() {
     drawCircleFence,
     updateCircleFenceName,
     destroyCircleFence,
-    destroyAllFence
+    destroyAllFence,
+    resampleAllFenceHeights: (mapId) => resampleAllMapFences(mapStore, mapId),
   }
 }

package/js/index.js

@@ -58,3 +58,22 @@ export {
 export { getAddressByLocation, setGeocodeProvider } from './api/gaode.js'
 
 export { objectUtils } from './utils/cesium/object.js'
+
+export {
+  DEFAULT_TERRAIN_CONFIG,
+  resolveTerrainConfig,
+  ensureTerrainConfig,
+  createTerrainProvider,
+  applyTerrain,
+  isTerrainEnabled,
+  syncTerrainConfig,
+} from './utils/terrainProvider.js'
+
+export {
+  sampleTerrainHeights,
+  applyTerrainWallToEntity,
+  generateCircleLngLatPositions,
+  resampleAllMapFences,
+  resampleFenceEntityHeights,
+  isTerrainActive,
+} from './utils/terrainHeight.js'

package/js/utils/terrainHeight.js

@@ -0,0 +1,229 @@
+/**
+ * 地形高度采样与围栏墙高度计算
+ */
+import * as Cesium from 'cesium'
+
+const DEFAULT_SAMPLE_LEVEL = 12
+export const DEFAULT_CIRCLE_SEGMENTS = 64
+
+export function isTerrainActive(map) {
+  if (!map?.terrainProvider) return false
+  return !(map.terrainProvider instanceof Cesium.EllipsoidTerrainProvider)
+}
+
+export function lngLatToCartographic(lngLat) {
+  return Cesium.Cartographic.fromDegrees(lngLat.lng, lngLat.lat, 0)
+}
+
+export function cartesianFootprintFromLngLat(lngLat) {
+  return Cesium.Cartesian3.fromDegrees(lngLat.lng, lngLat.lat, 0)
+}
+
+export function cartesianToLngLat(cartesian) {
+  const cartographic = Cesium.Cartographic.fromCartesian(cartesian)
+  return {
+    lng: Cesium.Math.toDegrees(cartographic.longitude),
+    lat: Cesium.Math.toDegrees(cartographic.latitude),
+  }
+}
+
+export function buildWallHeights(terrainHeights, fenceHeight) {
+  const minimumHeights = terrainHeights.map((h) => h || 0)
+  const maximumHeights = minimumHeights.map((h) => h + fenceHeight)
+  return { minimumHeights, maximumHeights }
+}
+
+export function closeRing(values) {
+  if (!values?.length) return []
+  return [...values, values[0]]
+}
+
+/**
+ * 批量采样地形椭球海拔（米）
+ * @param {Cesium.Viewer} map
+ * @param {Array<{lng:number, lat:number}>} lngLatList
+ * @param {{ level?: number }} [options]
+ * @returns {Promise<number[]>}
+ */
+export async function sampleTerrainHeights(map, lngLatList, options = {}) {
+  const level = options.level ?? DEFAULT_SAMPLE_LEVEL
+  if (!lngLatList?.length) return []
+
+  if (!isTerrainActive(map)) {
+    return lngLatList.map(() => 0)
+  }
+
+  const cartographics = lngLatList.map(lngLatToCartographic)
+
+  try {
+    const sampled = await Cesium.sampleTerrainMostDetailed(map.terrainProvider, level, cartographics)
+    return sampled.map((cartographic) => resolveCartographicHeight(map, cartographic))
+  } catch (error) {
+    console.warn('地形高度采样失败，尝试同步采样:', error)
+    return cartographics.map((cartographic) => resolveCartographicHeight(map, cartographic))
+  }
+}
+
+function resolveCartographicHeight(map, cartographic) {
+  if (Cesium.defined(cartographic.height) && Number.isFinite(cartographic.height)) {
+    return cartographic.height
+  }
+  const syncHeight = map.scene.sampleHeight(cartographic)
+  if (Cesium.defined(syncHeight) && Number.isFinite(syncHeight)) {
+    return syncHeight
+  }
+  return 0
+}
+
+/**
+ * 根据圆心、半径生成圆周经纬度点
+ */
+export function generateCircleLngLatPositions(
+  centerLng,
+  centerLat,
+  radiusMeters,
+  segments = DEFAULT_CIRCLE_SEGMENTS,
+) {
+  const positions = []
+  const center = Cesium.Cartographic.fromDegrees(centerLng, centerLat)
+  const ellipsoid = Cesium.Ellipsoid.WGS84
+  const centerCartesian = ellipsoid.cartographicToCartesian(center)
+  const transform = Cesium.Transforms.eastNorthUpToFixedFrame(centerCartesian)
+
+  for (let i = 0; i < segments; i += 1) {
+    const bearing = (2 * Math.PI * i) / segments
+    const east = radiusMeters * Math.sin(bearing)
+    const north = radiusMeters * Math.cos(bearing)
+    const localPoint = new Cesium.Cartesian3(east, north, 0)
+    const worldPoint = Cesium.Matrix4.multiplyByPoint(transform, localPoint, new Cesium.Cartesian3())
+    const cartographic = ellipsoid.cartesianToCartographic(worldPoint)
+    positions.push({
+      lng: Cesium.Math.toDegrees(cartographic.longitude),
+      lat: Cesium.Math.toDegrees(cartographic.latitude),
+    })
+  }
+
+  return positions
+}
+
+export function getAverageTerrainHeight(terrainHeights) {
+  if (!terrainHeights?.length) return 0
+  return terrainHeights.reduce((sum, h) => sum + (h || 0), 0) / terrainHeights.length
+}
+
+export function getCenterLngLat(lngLatList, terrainHeights) {
+  const total = lngLatList.reduce(
+    (sum, item) => {
+      sum.lng += item.lng
+      sum.lat += item.lat
+      return sum
+    },
+    { lng: 0, lat: 0 },
+  )
+
+  return {
+    lng: total.lng / lngLatList.length,
+    lat: total.lat / lngLatList.length,
+    height: getAverageTerrainHeight(terrainHeights),
+  }
+}
+
+/**
+ * 将采样高度应用到 wall 实体（footprint 用 height=0，起伏由 min/max 控制）
+ */
+export async function applyTerrainWallToEntity(map, entity, lngLatList, fenceHeight, options = {}) {
+  const closed = options.closed !== false
+  const terrainHeights = await sampleTerrainHeights(map, lngLatList, options)
+  const ringHeights = closed ? closeRing(terrainHeights) : terrainHeights
+  const footprint = lngLatList.map(cartesianFootprintFromLngLat)
+  const wallPositions = closed ? closeRing(footprint) : footprint
+  const { minimumHeights, maximumHeights } = buildWallHeights(ringHeights, fenceHeight)
+
+  if (!entity.wall) {
+    entity.wall = {}
+  }
+
+  entity.wall.positions = wallPositions
+  entity.wall.minimumHeights = minimumHeights
+  entity.wall.maximumHeights = maximumHeights
+
+  if (entity.polyline) {
+    entity.polyline.positions = wallPositions
+    entity.polyline.clampToGround = true
+  }
+
+  if (entity.ellipse) {
+    entity.ellipse = undefined
+    entity.position = undefined
+  }
+
+  map.scene?.requestRender?.()
+
+  return {
+    terrainHeights,
+    minimumHeights,
+    maximumHeights,
+    wallPositions,
+  }
+}
+
+/**
+ * 地形变更后，根据 _originalOptions 重新采样单个围栏
+ */
+export async function resampleFenceEntityHeights(map, entity) {
+  const opts = entity?._originalOptions
+  if (!opts || !entity) return false
+
+  const fenceHeight = opts.height ?? 2
+
+  if (opts.center && typeof opts.radius === 'number') {
+    const circleLngLats = generateCircleLngLatPositions(opts.center.lng, opts.center.lat, opts.radius)
+    await applyTerrainWallToEntity(map, entity, circleLngLats, fenceHeight)
+
+    const centerHeights = await sampleTerrainHeights(map, [{ lng: opts.center.lng, lat: opts.center.lat }])
+    const centerHeight = centerHeights[0] || 0
+    if (entity._labelEntity) {
+      entity._labelEntity.position = Cesium.Cartesian3.fromDegrees(
+        opts.center.lng,
+        opts.center.lat,
+        centerHeight,
+      )
+    }
+    return true
+  }
+
+  if (opts.positions?.length >= 3) {
+    const lngLatList = opts.positions.map((p) => ({ lng: p.lng, lat: p.lat }))
+    await applyTerrainWallToEntity(map, entity, lngLatList, fenceHeight)
+    const terrainHeights = await sampleTerrainHeights(map, lngLatList)
+    const center = getCenterLngLat(lngLatList, terrainHeights)
+    if (entity._labelEntity) {
+      entity._labelEntity.position = Cesium.Cartesian3.fromDegrees(center.lng, center.lat, center.height)
+    }
+    return true
+  }
+
+  return false
+}
+
+/**
+ * 重新采样地图上所有围栏实体的高度
+ */
+export async function resampleAllMapFences(mapStore, mapId) {
+  const map = mapStore.getMap(mapId)
+  if (!map) return 0
+
+  const targetMapId = mapId != null ? mapId : mapStore.getCurrentMapId()
+  const context = mapStore.mapContexts.get(targetMapId)
+  if (!context?.graphicMap) return 0
+
+  let count = 0
+  for (const entity of context.graphicMap.values()) {
+    if (entity?.wall && entity._originalOptions) {
+      const updated = await resampleFenceEntityHeights(map, entity)
+      if (updated) count += 1
+    }
+  }
+
+  return count
+}

package/js/utils/terrainProvider.js

@@ -0,0 +1,125 @@
+/**
+ * 地形服务加载与切换（支持 mapConfig.terrain 配置及地图外开关）
+ */
+import * as Cesium from 'cesium'
+
+/** mapConfig.terrain 缺省时的默认值（show 仅在为 undefined 时生效） */
+export const DEFAULT_TERRAIN_CONFIG = {
+  show: true,
+  url: 'https://data.mars3d.cn/terrain',
+  coastlineData: false,
+  lightingData: false,
+}
+
+/**
+ * 解析地形配置（合并 mapConfig.terrain 与默认值）
+ * @param {Object} mapOptions
+ * @returns {{ show: boolean, url: string, coastlineData: boolean, lightingData: boolean }}
+ */
+export function resolveTerrainConfig(mapOptions) {
+  const terrain = mapOptions?.terrain || {}
+  return {
+    show: terrain.show ?? DEFAULT_TERRAIN_CONFIG.show,
+    url: terrain.url ?? DEFAULT_TERRAIN_CONFIG.url,
+    coastlineData: terrain.coastlineData ?? DEFAULT_TERRAIN_CONFIG.coastlineData,
+    lightingData: terrain.lightingData ?? DEFAULT_TERRAIN_CONFIG.lightingData,
+  }
+}
+
+/**
+ * 补全 mapOptions.terrain，避免宿主未配置时无法加载
+ * @param {Object} mapOptions
+ */
+export function ensureTerrainConfig(mapOptions) {
+  if (!mapOptions) return mapOptions
+  if (!mapOptions.terrain) {
+    mapOptions.terrain = { ...DEFAULT_TERRAIN_CONFIG }
+    return mapOptions
+  }
+  const resolved = resolveTerrainConfig(mapOptions)
+  mapOptions.terrain = { ...mapOptions.terrain, ...resolved }
+  return mapOptions
+}
+
+/**
+ * 创建 Cesium 地形 Provider
+ * @param {Object} terrainConfig
+ * @returns {Promise<Cesium.CesiumTerrainProvider|undefined>}
+ */
+export async function createTerrainProvider(terrainConfig) {
+  const config = resolveTerrainConfig({ terrain: terrainConfig })
+  if (!config.show || !config.url) return undefined
+
+  return Cesium.CesiumTerrainProvider.fromUrl(config.url, {
+    requestWaterMask: !!config.coastlineData,
+    requestVertexNormals: !!config.lightingData,
+  })
+}
+
+/**
+ * 将地形应用到 Viewer（关闭时使用椭球地形）
+ * @param {Cesium.Viewer} viewer
+ * @param {Object} terrainConfig
+ * @returns {Promise<boolean>} 是否成功加载真实地形
+ */
+export async function applyTerrain(viewer, terrainConfig) {
+  if (!viewer || viewer.isDestroyed?.()) return false
+
+  const config = resolveTerrainConfig({ terrain: terrainConfig })
+
+  if (!config.show) {
+    viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider()
+    viewer.scene?.requestRender?.()
+    return false
+  }
+
+  if (!config.url) {
+    console.warn('地形已开启但未配置 url，请在 mapConfig.js 的 terrain.url 中设置地形服务地址')
+    viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider()
+    viewer.scene?.requestRender?.()
+    return false
+  }
+
+  try {
+    const provider = await createTerrainProvider(config)
+    viewer.terrainProvider = provider
+    viewer.scene?.requestRender?.()
+    console.log(`地形已加载：${config.url}`)
+    return true
+  } catch (error) {
+    console.error('地形加载失败，将使用默认椭球地形:', error)
+    viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider()
+    viewer.scene?.requestRender?.()
+    return false
+  }
+}
+
+/**
+ * 当前 Viewer 是否在使用真实地形（非椭球）
+ * @param {Cesium.Viewer} viewer
+ */
+export function isTerrainEnabled(viewer) {
+  if (!viewer?.terrainProvider) return false
+  return !(viewer.terrainProvider instanceof Cesium.EllipsoidTerrainProvider)
+}
+
+/**
+ * 同步 mapConfig.terrain 并应用到 Viewer
+ * @param {Cesium.Viewer} viewer
+ * @param {Object} mapConfig - 通常为 window.MapConfig / MapConfig
+ * @param {{ show?: boolean, url?: string }} patch
+ */
+export async function syncTerrainConfig(viewer, mapConfig, patch = {}) {
+  if (!mapConfig) {
+    return applyTerrain(viewer, patch)
+  }
+
+  if (!mapConfig.terrain) {
+    mapConfig.terrain = { ...DEFAULT_TERRAIN_CONFIG }
+  }
+
+  if (patch.show !== undefined) mapConfig.terrain.show = patch.show
+  if (patch.url !== undefined) mapConfig.terrain.url = patch.url
+
+  return applyTerrain(viewer, mapConfig.terrain)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huweili-cesium",
-  "version": "1.2.87",
+  "version": "1.2.89",
   "description": "基于 Cesium 的地图工具库（无人机态势、轨迹、围栏、工具栏等）",
   "type": "module",
   "main": "./index.js",
@@ -81,6 +81,10 @@
     "./utils/basemapSwitcher.js": "./js/utils/basemapSwitcher.js",
     "./utils/mapImagery": "./js/utils/mapImagery.js",
     "./utils/mapImagery.js": "./js/utils/mapImagery.js",
+    "./utils/terrainProvider": "./js/utils/terrainProvider.js",
+    "./utils/terrainProvider.js": "./js/utils/terrainProvider.js",
+    "./utils/terrainHeight": "./js/utils/terrainHeight.js",
+    "./utils/terrainHeight.js": "./js/utils/terrainHeight.js",
     "./utils/eventBus": "./js/utils/eventBus.js",
     "./utils/eventBus.js": "./js/utils/eventBus.js",
     "./utils/useEventBus": "./js/utils/useEventBus.js",