企业官网建设流程全解析

用 Cesium 三步搭建 WebGL 地下空间可视化

【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium

想在浏览器里把矿井巷道、地下管线放到地表以下显示？Cesium 是一款开源 JavaScript 三维地球库，配合地表透明化与负高度坐标，可以搭出可交互的 WebGL 地下空间可视化。本文先给一个能跑的最小示例，再回头拆解每一处配置背后的原理。

一、从一个真实需求说起

做矿山安全演示时，客户要求看到的是山体内部的巷道网络，而不是地表卫星影像。模型放地表之上解决不了“在地下”这件事。你要同时处理两件事：让地表变半透明，否则它挡住一切地下内容；让相机和模型能进入负高度空间。Cesium 的 Globe 对象对这两点都有原生 API，不需要 hack。

二、先跑起来：一个 60 行的最小示例

1. 把项目跑起来

git clone https://gitcode.com/GitHub_Trending/ce/cesium cd cesium && npm install npm start

启动后打开本地 Sandcastle，本文代码都在它的运行环境里可以直接粘贴。

2. 初始化场景并允许相机入地

创建 Viewer 后必须关闭碰撞检测，否则相机飞不进地表以下：

const viewer = new Cesium.Viewer("cesiumContainer"); const scene = viewer.scene; scene.screenSpaceCameraController.enableCollisionDetection = false;

3. 打开地表透明

启用 Globe 的 translucency，把地表调成半透明：

const globe = scene.globe; globe.showGroundAtmosphere = false; // 关掉地表大气，避免雾边干扰 globe.baseColor = Cesium.Color.TRANSPARENT; globe.translucency.enabled = true; globe.translucency.frontFaceAlpha = 0.25; // 0~1，越小越透明 globe.undergroundColor = undefined;

4. 往地下放一个模型

用负高度坐标表示“地下 500 米”，放一个 glTF 模型：

viewer.entities.add({ name: "地下模型", position: Cesium.Cartesian3.fromDegrees(-3.8, 53.1, -500), model: { uri: "models/underground.glb" } // 换成你自己的模型路径 });

飞到现场，地表变淡，模型浮在地下——最小闭环完成。

三、把刚才的现象拆开看 🔍

地表透明化两种做法

掩码法（全局）：整颗球透明，frontFaceAlpha控制程度。官方示例还会把海洋像素“抠掉”，让陆地若隐若现：

const baseLayer = scene.imageryLayers.get(0); baseLayer.colorToAlpha = new Cesium.Color(0.0, 0.016, 0.059); baseLayer.colorToAlphaThreshold = 0.2;

矩形法（局部）：只让一块矩形区域透明，其余地表保持完整，适合做对照展示：

globe.translucency.rectangle = Cesium.Rectangle.fromDegrees(-120, 0, -30, 45);

两种做法的切换逻辑在 globe-interior 官方示例 里，可直接对照阅读。

往地下放什么模型

从糙到精三个选项：

• 椭球/盒子图元：搭地球内核这类分层结构，Ellipsoid实体的radii直接给半径，position放在Cartesian3.ZERO；
• glTF/GLB 模型：真实设施放在负高度坐标，上面的示例就是这种；
• 地形数据融合：用量化网格或 3D Tiles 地形还原真实地下起伏。

地下环境怎么控制

三个关键项：undergroundColor换地下背景色，置undefined关闭；undergroundColorAlphaByDistance按 near/far 距离渐变透明度，越往深处越淡；相机深度在 postUpdate 里限幅。

globe.undergroundColor = Cesium.Color.LIGHTSLATEGRAY; globe.undergroundColorAlphaByDistance = new Cesium.NearFarScalar(1000, 0.0, 1000000, 1.0);

四、进阶调优：三个最常用的旋钮

性能：用 3D Tiles 流式加载大型地下模型

整条隧道网不要一次性塞进场景，按 LOD 分块后按需加载：

const tileset = await Cesium.Cesium3DTileset.fromUrl("tileset.json"); scene.primitives.add(tileset);

视觉：加一点雾做出远近层次

地下空间容易“平”，调低雾密度让远处结构自然收暗。默认 0.0006，别调太高否则模型被吞：

scene.fog.density = 0.0006;

数据接入：地质分层数据走 CZML

分层、时间演化的地质数据用 CZML 描述，用intervals表达各层的起止时间，即可让时间轴驱动地层显隐。

五、高频问题速查

相机为什么进不了地下？忘关碰撞检测。enableCollisionDetection = false是相机入地的前提，缺了它无论怎么拉都会被顶回来。

为什么模型在地下完全看不见？查两点：一是translucency.enabled是否真正为 true、矩形法是否覆盖了目标区域；二是undergroundColor默认黑色，相机够深时不透明度接近 1，会把模型整个盖住——把它置undefined或调低undergroundColorAlphaByDistance的 far 端透明度。

如何限制地下漫游深度？监听 postUpdate，相机高度低于阈值就钳回去：

scene.postUpdate.addEventListener(() => { const h = scene.globe.getHeight(scene.camera.positionCartographic); if (h < -1000) { scene.camera.positionCartographic.height = -1000; } });

六、上手路线图与延伸阅读

• 复现本文最小示例，确认相机能飞入负高度
• 打开 globe-interior 示例 切换两种透明化方式对比效果
• 用自有 GLB 模型替换示例模型，参考 underground-color 示例 调地下背景色
• 通读 Globe.js 源码 中 translucency 与 undergroundColor 段落，核对各参数默认值
• 场景达标后，微调fog.density与 3D Tiles 的 LOD 策略，压到目标帧率

核心就三步：开透明、放模型、控环境。参数都集中在 Globe 和 Scene 两个对象上，跑通一遍之后，调参空间比想象中开阔得多。

【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium