矿区岩层开挖

使用 ExcavateEffect 与 DrawManager 组合，实现带岩层侧壁材质的交互式地表开挖。

能力定位

ExcavateEffect 管理 Globe 裁剪面、坑底 Polygon 和贴合地形的 Wall，适合基坑、矿区和地下空间等局部开挖展示。岩层纹理属于业务侧可配置资源，示例通过离屏 Canvas 生成，不要求额外图片或第三方依赖。

该效果只支持凸多边形。凹多边形需要先在业务侧拆分为多个凸多边形，再分别管理其裁剪策略。

基础用法

import { CesiumViewer, ExcavateEffect } from '@nexa/gis-cesium'
import { Cartesian3 } from 'cesium'

const nexaGis = new CesiumViewer('container')
const viewer = nexaGis.viewer
const positions = Cartesian3.fromDegreesArray([
  108.9464, 34.2473,
  108.9536, 34.2478,
  108.9540, 34.2535,
  108.9468, 34.2532,
])

const effect = new ExcavateEffect({
  positions,
  excavateDepth: 120,
  sampleSpacing: 10,
  bottomImage: '/images/excavate/excavate_side_min.jpg',
  sideImage: '/images/my-stratum-texture.png',
})

effect.on(viewer)

// 页面退出时只回收该效果创建的资源
effect.destroy(viewer)

配置项

参数	类型	默认值	说明
positions	Cartesian3[]	必填	凸多边形顶点，至少 3 个
excavateDepth	number	200	相对最低顶点向下的开挖深度，单位米
sampleSpacing	number	10	侧墙上边缘贴合地形的采样间距，必须为有限正数
bottomImage	string	灰色材质	坑底图片 URL 或 Data URL
sideImage	string	棕色材质	侧壁图片 URL 或 Data URL

sampleSpacing 越小，侧墙越贴合局部地形，但插值点和高度查询也越多。普通局部开挖建议保持默认的 10 米；高精度小范围场景可按数据分辨率适当减小。

配合 DrawManager

import { DrawManager, ExcavateEffect } from '@nexa/gis-cesium'

const draw = new DrawManager(viewer, { defaultMode: 'polygon' })
let activeEffect: ExcavateEffect | undefined

draw.onDrawComplete((result) => {
  // DrawManager 会创建绘制结果线，本例不需要保留它
  viewer.entities.remove(result.entity)

  // Globe 只有一个 clippingPlanes 槽位，重画前先释放旧效果
  activeEffect?.destroy(viewer)
  activeEffect = new ExcavateEffect({
    positions: result.positions,
    excavateDepth: 150,
    sampleSpacing: 10,
  })
  activeEffect.on(viewer)
})

draw.startDraw('polygon')

// 页面退出时同时释放效果、交互 handler 和 Tooltip DOM
activeEffect?.destroy(viewer)
draw.offDrawComplete()
draw.destroy()

生命周期与限制

• on(viewer)、off(viewer) 和 destroy(viewer) 可重复调用；Effect 不会销毁调用方传入的 Viewer。
• Effect 只移除自己创建的底面和侧墙，不会清空 viewer.entities。
• 同一个 Globe 的 clippingPlanes 是单一场景资源，推荐同一时刻只启用一个开挖 Effect。
• 侧墙高度来自当前已加载的地形瓦片；瓦片未加载时会保留输入顶点高度，因此真实地形场景仍应进行浏览器视觉验收。
• 实现只使用 CesiumJS 稳定公共 API，不依赖 Cesium 私有字段。