NEXA - 文档

Appearance

UndergroundEffect 地下模式（地表透明穿地漫游） ​

通过三组公开 Scene 标志切换"地下模式"：地表透明 + 穿地漫游，可透视/穿入地表观察地下构筑物。对齐源案例 Analysis/UnderGround。

能力定位 ​

UndergroundEffect 适合：

  • 地下场景巡检：透明地表下透视地下管线、管廊、构筑物（源案例演示黄色柱体 + 红色管线）；
  • 穿地漫游：关闭相机碰撞检测后，镜头可穿入地表进入地下视角；
  • 地下物体正确遮挡：开启地形深度测试，地下物体被地表轮廓正确裁切。

通过三组公开 Scene 标志组合呈现（对齐源案例 initViewer）：

标志地下模式取值作用
screenSpaceCameraController.enableCollisionDetectionfalse禁用相机碰撞，可穿入地表
globe.depthTestAgainstTerraintrue地形深度测试，地下物体被地表正确遮挡
globe.translucency.enabled + frontFaceAlphatrue + 0.8地表透明，透视地下构筑物

与其他相机/效果类的区分：

效果作用面行为
UndergroundEffect（本效果）Scene 标志 + globe 半透明全局切换地下漫游观感，不触碰几何资源
CameraBoundary相机位置约束限制相机不越界，与穿地无直接关系
TilesMultClip3D Tiles 裁剪地面挖洞剖切，地下可视化另一路径

构造函数 ​

ts
constructor(options: UndergroundEffectOptions = {})
ts
interface UndergroundEffectOptions {
  alpha?: number        // 地表透明度的 frontFaceAlpha，默认 0.8
  underground?: boolean // 是否禁用相机碰撞进入穿地模式，默认 true
  translucent?: boolean // 是否启用地表透明，默认 true
  depthTest?: boolean   // 是否开启地形深度测试，默认 true
}
参数类型默认值描述
alphanumber0.8globe.translucency.frontFaceAlpha，1 完全不透明、0 完全透明
undergroundbooleantrue为 true 时 enableCollisionDetection=false（可穿地）；false 时保留碰撞检测
translucentbooleantrueglobe.translucency.enabled，透明地表总开关
depthTestbooleantrueglobe.depthTestAgainstTerrain，地下物体遮挡开关

无必填项，new UndergroundEffect() 亦合法。

生命周期 ​

实现 Lifecycle<Viewer> 契约，on/off/destroy 均幂等：

ts
on(viewer: Viewer): void      // 保存四项原状态并应用地下模式
off(viewer: Viewer): void     // 逐一还原 on 前保存的原状态
destroy(viewer: Viewer): void // 等价于 off

on 在应用前完整保存四项 scene 标志原值，off/destroy 逐一还原，不触碰调用方其他资源；on→off→on 可复用，destroy 后需重新 on 才生效。 源案例 destroy 仅 removeAll 实体并销毁 viewer，未还原 scene 标志；本效果保存/还原协议避免污染调用方场景。

基础示例 ​

ts
import { UndergroundEffect } from '@nexa/gis-cesium'

const effect = new UndergroundEffect({ alpha: 0.8 }) // 对齐源案例：透明地表 0.8
effect.on(viewer)                                    // 开启地下模式：可穿地 + 地表透明

进阶示例 ​

运行时用 setAlpha / setCollisionDetection 调整（对齐源案例同名方法），未 on 时仅更新内部值、on 后立即生效：

ts
const effect = new UndergroundEffect()
effect.on(viewer)

effect.setAlpha(0.5)              // 地表更透明
effect.setCollisionDetection(false) // 关闭碰撞 → 可穿入地表
effect.setCollisionDetection(true)  // 恢复碰撞 → 相机止于地表

实现说明 ​

  • 三组场景标志：enableCollisionDetection（穿地）、depthTestAgainstTerrain（遮挡）、globe.translucency.enabled + frontFaceAlpha（透明地表），全部为 Cesium 公开 API，无 GLSL / 私有字段依赖；
  • 保存/还原协议：on 将四项标志原值存入 _saved，off/destroy 逐一还原并清空；重复 on 早退（幂等），不会二次覆盖保存态；
  • 运行时调整：setAlpha / setCollisionDetection 在 on 状态下即时写入 scene 标志；未 on 时仅更新内部参数，由下一次 on 统一应用；
  • 资源所有权：本效果只读写 4 个布尔/数值标志，不创建实体、不持有时钟/相机引用，off 后无泄漏。

清理责任 ​

ts
effect.destroy(viewer) // 或 effect.off(viewer)，等价且幂等

重复调用 destroy/off 安全（未 on 时为空操作）；销毁后 scene 标志还原为 on 前状态。

Cesium 版本限制 ​

  • 依赖 Cesium 公开 API：ScreenSpaceCameraController.enableCollisionDetection、Globe.depthTestAgainstTerrain、Globe.translucency（GlobeTranslucency.enabled / frontFaceAlpha）；
  • 地表透明/穿地观感需真实浏览器/WebGL 验证；已验证目标版本：Cesium 1.133.1。