Cesium三维WebGIS入门详解
浏览器端三维 GIS 要同时回答两件事：地球与地理坐标如何呈现，以及大体量模型与矢量如何流畅渲染。底层几乎都落在WebGL；上层框架里，面向「三维地球 / WebGIS」生态最完整、二次封装最多的是Cesium。下文从 WebGL 与周边引擎选型切入，再落到 Cesium 的引用方式、核心类与数据加载思路——以《WebGIS 开发从入门到实践》三维篇笔记为纲并扩写。
目录
- 三维 WebGIS 在解决什么问题
- WebGL：浏览器三维的底座
- Web 三维框架怎么选
- 为什么 WebGIS 常选 Cesium
- Cesium 如何引入工程
- 核心类与对象关系
- 交互、实体与数据源
- 落地清单与常见坑
- 延伸阅读
1. 三维 WebGIS 在解决什么问题
二维 Web 地图（瓦片 + 矢量叠加）擅长「平面位置与属性」；三维 WebGIS 额外要处理更多能力，也要付更多代价：
| 能力 | 含义 | 代价 / 门槛 |
|---|---|---|
| 地形 / 椭球 | 高程、曲率、全球尺度漫游 | 地形服务带宽与高精度 DEM 成本；弱设备掉帧 |
| 倾斜摄影 / BIM / 模型 | OSGB、3D Tiles、glTF 等上屏 | 预处理管线重（切片、坐标系、LOD）；存储与 CDN 压力大 |
| 时序与相机 | 飞行、日照、轨迹回放 | 状态机与交互复杂度上升；易与 UI 抢控制权 |
| 与二维数据互通 | GeoJSON、KML、WMS/WMTS 等 | 二维/三维双引擎时坐标与相机同步成本 |
| （共性） | 浏览器真三维 | WebGL 兼容性、首包体积、GPU 占用；低端 WebView 常直接劝退 |
决策时不要只看「三维能不能做」，要问：数据是否已有 3D Tiles/glTF 管线、用户设备是否扛得住、是否值得维护一套地球内核。很多业务继续用二维地图 + 局部 Three.js 弹窗就够。
工程上常见路径：业务二维地图（Mapbox / 高德 / Leaflet 等）+ 需要真三维时切 Cesium（或基于 Cesium 的商业封装）；纯可视化大屏也可能用 Three.js / deck.gl / L7，不一定上「地球内核」。
2. WebGL：浏览器三维的底座
WebGL（Web Graphics Library）是基于OpenGL ES的 JavaScript API，把三维绘制接到 HTML5Canvas，并走 GPU 加速。浏览器无插件即可渲染三维场景与模型，但页面必须跑在支持 WebGL的环境（多数现代桌面浏览器可用；部分嵌入式 WebView 需实测）。
对开发者而言：
- 直接写 WebGL：灵活，但缓冲、着色器、矩阵、资源管理成本高。
- 引擎 / 框架：封装场景图、相机、材质、加载器；WebGIS 框架再叠一层地理投影、地形、瓦片、时间轴。
Cesium、Three.js、deck.gl、L7 等最终都建立在 WebGL（或其演进路径）之上。
3. Web 三维框架怎么选
笔记中列举的引擎可按「问题域」粗分，而不是比谁「更三维」。
| 框架 | 定位 | 更适合 | 相对短板 |
|---|---|---|---|
| Three.js | 通用浏览器三维引擎 | 产品可视化、展厅、自定义场景 | 不自带全球 GIS 栈 |
| Babylon.js | 偏应用 / 游戏向的 WebGL 框架 | 交互复杂的 3D 应用 | 同样不是地球 GIS 专用 |
| PlayCanvas | 带编辑器的游戏引擎 | 强交互、音效物理一体的场景 | 学习与部署偏游戏管线 |
| ECharts GL | ECharts 的三维图表扩展 | 已有 ECharts 的三维统计图 | 不是完整 GIS 地球 |
| deck.gl | Uber 开源的 WebGL 地理大数据可视化 | 海量点线面图层、与地图底图组合 | 地球级倾斜摄影 / BIM 非主场 |
| harp.gl | TypeScript 实验性三维地图渲染 | 跟进 HERE 地图渲染实验 | 生态与文档相对小众 |
| L7 | AntV 大规模地理空间可视分析 | 符号化表达、与高德 / Mapbox GL 结合 | 重「可视分析」而非完整 Cesium 式地球内核 |
| Cesium | 三维地球与地图的 JS 库 | 全球地形、3D Tiles、时序、WebGIS 二次开发底座 | 包体与概念面较广，需按模块裁剪 |
选型口诀：要「地球 + 地理数据 + 倾斜/BIM」→ Cesium 系；要「炫酷地理大数据图层」→ deck.gl / L7；要「任意 3D 物体与材质」→ Three.js / Babylon。
4. 为什么 WebGIS 常选 Cesium
Cesium 是跨平台、跨浏览器的三维地球 / 地图JavaScript 库，基于 WebGL 硬件加速，Apache 2.0，可商用。产业里大量三维 WebGIS 产品在其开源内核上再封装（如超图 SuperMap iClient3D for Cesium、火星科技 mars3d 等）。
| 能力点 | 说明 |
|---|---|
| 模型 | OBJ、glTF；OSGB / BIM / MAX / SKP 等常转为 3D Tiles后加载 |
| 矢量 / 标注数据 | GeoJSON、Shapefile、KML 等（经加载器进入场景） |
| 生态 | 文档、示例、社区案例相对丰富 |
| 扩展 | 商业与开源二次封装多，便于接国内底图与业务组件 |
它解决的是「在浏览器里把地球和地理三维资产跑起来」，而不是替代所有 Three.js 场景。
5. Cesium 如何引入工程
常见两种方式：
5.1 静态包 + script
从官方发行包下载后，用<script>引入构建产物，适合简单演示页或非打包老项目。
5.2 npm + 现代前端工程
npminstallcesium-S若使用Vite，通常还需：
npmi vite-plugin-cesium-D并在vite.config.js中启用 Cesium 相关插件配置（静态资源、Worker、WASM 等路径由插件处理）。
Webpack没有 Vite 插件那层「开箱拷资源」时，经典坑是：编译成功，运行期Assets / Workers 404。实务上通常要用copy-webpack-plugin（或等价手段）把 Cesium 的Assets、Workers、ThirdParty等拷到输出目录，并正确设置CESIUM_BASE_URL/ 公共路径；只改resolve.alias往往不够。细节随 Cesium 与 Webpack 大版本变化，以官方 Webpack 示例为准，但「必须显式处理静态资源」这条很少变。
注意：Cesium 资源体积不小（Workers、Assets、第三方库）；生产环境应按需加载影像/地形 Provider，避免首屏拉全量样例数据。
6. 核心类与对象关系
笔记列出的核心概念：Viewer、Scene、ScreenSpaceEventHandler、CesiumWidget、Entity、Camera、DatasourceCollection。可先建立如下关系：
6.1 Viewer
Viewer是最常用的入口组件：创建并管理三维场景所需的基本能力——加载模型与影像、叠图层、设置相机、处理输入等。创建时绑定页面中的容器（通常是一个 div，内部使用 Canvas 呈现）。之后通过 API 添加实体、图层并驱动相机。
多数业务项目从new Cesium.Viewer(container, options)起步；可用 options 关掉不需要的底图控件、动画条等以减负。
6.2 Scene
Scene是三维图形对象的容器（对应 Canvas 上的场景），由 Viewer 或 CesiumWidget内部创建。通过 Scene 可触及例如：
| 成员 / 概念 | 作用 |
|---|---|
| Globe | 地球球体 |
| imageryLayers | 影像底图层 |
| terrainProvider | 地形 |
| camera | 相机 |
| skyBox / sun / moon | 天空盒与天体 |
| primitives | 偏底层的图元集合 |
| postProcessStages | 后处理效果 |
理解 Scene，有助于区分「改地球表现」和「改相机/后处理」。
6.3 CesiumWidget 与 Viewer
CesiumWidget是「带 Cesium 场景的轻量部件」，与 Scene 为包含关系。它与Viewer在用法上常被看作两种入口：二者都能拉起三维地球；Viewer更「全家桶」（控件、默认帮助、数据源管理等更全），CesiumWidget更精简，适合深度定制 UI 的壳。
6.4 Camera
Camera控制视图：旋转、缩放、平移、flyTo飞入等。Cesium 内置鼠标与触摸交互；也可用 API 编程控制。业务里常见需求是「定位到某经纬高 + 朝向」和「沿路径漫游」。
flyTo相关坑放到 §8；实现 POI 连点时务必考虑取消上一次飞行。
6.5 Entity：先会用，再知道何时不用
Entity是偏业务的高级对象：把可视化与属性收进统一结构，关注「展示什么数据」。适合点线面标注、随时间变化的样式、与属性面板绑定的业务图层。
什么时候不该（只）用 Entity
| 场景 | 更合适的方向 |
|---|---|
| 海量静态点（十万级+）频繁刷新 | Primitive / PointPrimitive / 聚合，或抽稀 |
| 城市级倾斜摄影、大型 BIM | 3D Tiles，不要拆成巨量 Entity |
| 需要极致合批、自定义 shader | 下沉到 Primitive / 自定义外观 |
| 一次性加载巨大 glTF 且无明显 LOD | 先做切片或减面，而不是堆 Entity |
入门与多数业务叠加层仍优先 Entity；性能问题出现时，再按上表降级，而不是一上来就写底层 API。
7. 交互、实体与数据源
7.1 ScreenSpaceEventHandler
用于屏幕空间输入：单击、右击、双击、移动、滚轮等。典型流程是监听事件 →scene.pick/ 拾取笛卡尔或地理坐标 → 高亮实体或弹出属性。
| 意图 | 事件类型（现行 API） |
|---|---|
| 单击 | ScreenSpaceEventType.LEFT_CLICK |
| 移动 | ScreenSpaceEventType.MOUSE_MOVE |
| 滚轮 | ScreenSpaceEventType.WHEEL |
旧资料或读书笔记里常见的MOUSE_CLICK属于过时/不准确写法，以当前文档中的LEFT_CLICK等为准。实现拾取时还要注意：地形深度检测、被模型遮挡、以及移动端触摸与鼠标差异。
7.2 Entity 与数据如何进场景
Entity 的定位见 §6.5。矢量进场景时，多数数据源最终仍落到 Entity（或对应图元）上参与渲染与拾取。
7.3 DatasourceCollection
DatasourceCollection管理可挂接的数据源（如 CZML、GeoJSON、KML 等）。不同格式是输入形态差异；进入 Cesium 后，多数仍落到Entity集合上。
8. 落地清单与常见坑
| # | 建议 |
|---|---|
| 1 | 先确认浏览器 / WebView 的 WebGL 可用性 |
| 2 | 影像与地形 Provider 按环境配置（密钥、跨域、CRS） |
| 3 | 大体量倾斜摄影走3D Tiles，避免浏览器端硬啃原始 OSGB |
| 4 | 区分 Entity（好用）与 Primitive / Tiles（性能）；见 §6.5 |
| 5 | 打包器必须正确处理 Cesium 静态资源与 Worker（Vite 插件或 Webpack CopyPlugin） |
| 6 | 国内项目评估是否直接用 Cesium，或用基于 Cesium 的国产封装（底图、控件、合规） |
| 7 | 与二维地图并存时，统一坐标与相机状态同步策略 |
| 8 | POI / 定位：flyTo连点前取消未完成的飞行，避免相机「抽搐」 |
常见坑
| 现象 | 常见原因 |
|---|---|
| 底图空白 | token / 密钥失效、跨域、Provider 配错 |
| 编译过、运行 404 | 未拷贝Assets/Workers（Webpack 尤甚） |
| 白屏 | WebView 无 WebGL；或 JS 初始化抛错未看控制台 |
| 相机乱飞 | 连续flyTo未cancelFlight/ 未串行化 |
| 卡顿 | Entity 过多或未切片的大体量模型 |
| 坐标错位 | 把 Three.js 局部坐标习惯硬套到笛卡尔 / 地理坐标 |
关于flyTo：默认带飞行时长与视角过渡；用户快速连点多个 POI 时，若不上一次结束又开下一次，相机会叠加动画显得抽搐。业务上应在新定位前取消当前飞行（如camera.cancelFlight()，以当前 API 为准），或自行队列化「只保留最后一次点击」。
9. 延伸阅读
| 资源 | 说明 |
|---|---|
| Cesium 官方文档与 Sandcastle 示例 | API 与交互样例 |
| 3D Tiles 规范 | 海量三维资产流式加载 |
| deck.gl / L7 文档 | 地理大数据可视化另一条路线 |
| glTF | 运行时三维模型交换格式 |
收束：三维 WebGIS 的底座是 WebGL；框架按问题域分流——要地球走 Cesium，要大数据图层走 deck.gl/L7，要自由造型走 Three.js。Cesium 的学习曲线往往不是陡峭，而是漫长：API 本身相对好懂，大部分时间耗在数据预处理、瓦片与 Provider、打包资源路径和真机性能上。先把 Viewer / Scene / Camera / Entity / 事件跑通，再心平气和地跟 3D Tiles 与工程配置较劲。
整理自《WebGIS 开发从入门到实践》（吕利利、牛健平）三维篇相关笔记，并补充选型与工程注意。具体 API 以 Cesium 当前版本为准。
