@mapgis/webclient-cesium-plugin

v17.10.10

Published

8 days ago

MapGIS Cesium plugin for 3D globe mapping with terrain, M3D models, analysis tools, and visualization extensions.

0High
0Medium
0Low

1、获取 MapGIS Client for JavaScript（Cesium）开发包

MapGIS Client for JavaScript（Cesium）是 WebClient 面向 Cesium 引擎的三维地图插件包，承接 @mapgis/webclient-common 的地图、图层、几何、符号和工具等通用接口，并完成三维场景下的引擎适配。

该包提供 Cesium 引擎下的核心能力扩展，覆盖三维场景、地形、M3D/模型、空间分析、可视化和交互编辑等 WebGIS 应用能力。

示例站点：http://webclient.smaryun.com

1.1、获取方式

1.1.1、npm 安装

推荐在现代工程中通过 npm 安装插件包和 Cesium 引擎包：

npm install @mapgis/webclient-common @mapgis/webclient-cesium-plugin @mapgis/cesium

@mapgis/webclient-cesium-plugin 负责 WebClient 三维能力扩展，@mapgis/cesium 提供 Cesium 引擎运行时和静态资源。

1.1.2、静态资源引入

如果项目暂时不接入构建链，可以直接使用发布包中的静态资源：

如果需要通过 CDN 格式开发包或离线示例站点集成，可前往：http://smaryun.com/dev/download_detail.html#/download828。

dist/esm/webclient-cesium-plugin.js
dist/umd/webclient-cesium-plugin.min.js
dist/webclient-cesium-plugin-resource
@mapgis/cesium 发布包中的 Cesium 引擎目录

常见做法是将 Cesium 引擎目录、webclient-cesium-plugin.min.js 和插件资源目录拷贝到项目静态资源目录，再通过 <script> 和 <link> 加载。

1.2、能力范围

view：三维场景视图、图层视图和视图交互
layer：地图、影像、地形、模型、场景、矢量和三维瓦片图层
analysis：通视、剖面、淹没、填挖方、日照和空间量算分析
visualization：专题图、热力图、风场和三维效果表达
editor：绘制、草图编辑和三维交互编辑
engineExtensions：Cesium 引擎扩展、资源适配和 MapGIS 能力桥接
resource：插件纹理、样式、Worker 和运行时资源

2、引入方式

2.1、ESM 引入

现代工程建议使用 ESM 方式引入插件 API，并在页面中加载 Cesium 引擎资源：

import { Map as ZondyMap } from '@mapgis/webclient-common'
import { SceneView, IGSSceneLayer } from '@mapgis/webclient-cesium-plugin'

Cesium 引擎包需要按项目构建策略复制到静态资源目录，并在入口 HTML 中加载：

<script src="/static/cesium/Cesium.js"></script>
<link rel="stylesheet" href="/static/cesium/Widgets/widgets.css" />
<link rel="stylesheet" href="/static/cesium/MapGIS/css/mapgis.css" />

2.2、全局引入

如果使用传统页面或旧工程，可直接挂载全局对象：

<script src="/static/cesium/Cesium.js"></script>
<link rel="stylesheet" href="/static/cesium/Widgets/widgets.css" />
<link rel="stylesheet" href="/static/cesium/MapGIS/css/mapgis.css" />
<script src="/static/libs/zondyclient/webclient-common.min.js"></script>
<script src="/static/libs/zondyclient/webclient-cesium-plugin.min.js"></script>
<script>
  const { Map: ZondyMap } = window.MapGISWebClientCommon
  const { SceneView } = window.MapGISWebClientCesiumPlugin
  const legacyNamespace = window.zondy
  const compatNamespace = window.Zondy
</script>

全局对象同时保留新命名空间和 window.zondy、window.Zondy 兼容入口，便于旧代码迁移。

3、快速开始

下面示例展示三维场景视图的最小初始化方式。实际项目中，请将容器尺寸设置为可见区域高度。

3.1、创建场景视图

import { Map as ZondyMap } from '@mapgis/webclient-common'
import { SceneView } from '@mapgis/webclient-cesium-plugin'

const zondyMap = new ZondyMap()
const sceneView = new SceneView({
  viewId: 'scene-container',
  map: zondyMap
})

3.2、加载场景图层

import { Map as ZondyMap } from '@mapgis/webclient-common'
import { IGSSceneLayer } from '@mapgis/webclient-cesium-plugin'

const zondyMap = new ZondyMap()
const sceneLayer = new IGSSceneLayer({
  url: 'http://server/igs/rest/g3d/SceneServer'
})

zondyMap.add(sceneLayer)

3.3、全局方式

<div id="scene-container"></div>
<script>
  const zondyMap = new zondy.Map()
  const sceneView = new zondy.cesium.SceneView({
    viewId: 'scene-container',
    map: zondyMap
  })
</script>

4、@mapgis/webclient-cesium-plugin 版本说明

v17.10.9

修复

修改分包配置，把commonjsHelpers单独打包成一个chunk，避免打入s3m中

v17.10.7

修复

修改注释问题

v17.10.6

修复

三维点符号，切换符号样式后，旧的符号样式未删除

v17.10.4

修复

修复线符号 solid/none 样式切换失效以及同 id 图形缓存问题

v17.10.2

修复

上下标+分式注记显示不全
修复cesium-plugin中Style类未导出的问题
导入 Marker 类型标绘对象后，Marker 的颜色属性未正确应用导入数据中的配置，仍保持默认值

v17.10.0

新增

支持地形裁剪抬升
新增极端天气模拟-雷暴天气
新增水面、水下特效；
新增3D图形默认自定义材质
新增 elevationInfo 到 Cesium ImageryLayer.classificationType 的转换逻辑，并在各类影像/瓦片/矢量瓦片图层创建及属性更新时生效，支持 onTheScene 模式下图层叠加到三维模型之上。

优化

优化体积云性能
优化栅格体元显示效率及效果
地形开挖支持动态设置是否显示开挖侧面和底面

修复

修复已知问题

v17.8.10

修复

修复传编码的空间过滤参数后，空间过滤不生效的问题
修复IGS地图服务一张图 POST 请求不生效的问题

v17.8.9

修复

修复已知问题

v17.8.8

修复

修复已知问题

v17.8.7

修复

修复已知问题

v17.8.6

修复

修复已知问题

v17.8.5

修复

修复地图服务图层到一定级别不显示的问题

v17.8.4

修复

在一定视角下加载自定义裁图图层卡顿

v17.8.3

修复

修复已知问题

v17.8.2

修复

修复已知问题

v17.8.1

修复

修复已知问题

v17.8.0

新增

Cesium 地形剖切支持凹多边形
新增路径漫游工具 RouteAnimationTool 支持实例化多个路径漫游工具
地质体剖切功能支持 3D Tiles 格式数据（3D Tiles 1.0和 3D Tiles 1.1）
环境特效增强，支持天气特效、水下特效、集群鸟类与动物、镜头特效

修复

优化使用非 FID 属性时更新 Cesium3DTileStyle 场景渲染效率

v17.6.25

修复

修复 imageryLayer.imageryProvide 对象在不同版本 Cesium 上不兼容的问题

v17.6.24

修复

修复已知问题

v17.6.23

修复

修复已知问题

v17.6.22

修复

修复天际线分析中颜色设置失败的问题

v17.6.21

修复

优化重复设置 Graphic 的显隐属性值为 true 时场景卡顿的问题

v17.6.20

修复

解决地图缩放时，加载自定义裁图图层时中间状态出现闪烁的问题
解决使用 startDrawing 添加广告牌时重复添加图元的问题

v17.6.19

修复

解决聚合专题图报错的问题

v17.6.18

修复

修复场景图层 hitTest 拾取报错的问题

v17.6.16

修复

修复已知问题

v17.6.15

修复

插件库适配 Cesium.defaultValue 方法，以兼容官方 Cesium 的接口更新改动
修复 Cesium Viewer 中设置默认底图报错的问题

v17.6.12

修复

优化瓦片类型Provider上isStretchImage参数默认拉伸

v17.6.8

修复

修复包含空格字符的图层访问令牌（token）认证失败问题

v17.6.6

修复

优化IGS地图服务一张图出图模式下闪烁和卡顿的问题

v17.6.3

修复

修复可视域分析视锥体未定义时的报错问题
修复混合接口方式加载动态服务时，出图过滤条件报错的问题

v17.6.2

修复

修复高频率更新流体模拟粒子数量时出现偶发报错的问题

v17.6.0

新增

支持三维仿真可视化：流体模拟仿真和水体效果可视化
面积、长度、角度、三角、方位角测量工具支持显示多个测量结果
新增IGS地图服务、ArcGIS地图服务、WMS服务一张图出图的服务接入Provider

修复

优化M3D2.0、2.1服务数据的加载性能和效果
优化剖面分析工具和地形分析工具功能效果

v17.4.7

修复

修复Graphic中半透明图元顺序异常的问题
修复剖面分析工具接口异常的问题
修复Popup弹窗接口异常的问题

v17.4.6

修复

修复场景设置罗盘失败的问题
修复剖切分析中绘制模型裁剪面功能中，配置剖切辅助面属性不生效的问题
修复碰撞检测中多次开启漫游时，碰撞检测失效的问题

v17.4.5

修复

修复CuttingTool无法剖切3D Tiles的问题

v17.4.4

修复

优化 GraphicsLayer 图层中深度检测设置的默认值

v17.4.3

新增

新增MapGIS网格要素容器类MapGISFeatureGridCollection

修复

优化面积测量工具图形外边线绘制效果

v17.4.2

修复

优化Tooltip工具根据相对位置定位的问题
增强对Cesium1.122版本的兼容
修复Mapv热力图显示错误的问题

v17.4.1

新增

混合开发接口增强，支持MapGIS场景服务和S3M场景服务混合开发

修复

修复API文档中部分接口文档缺失的问题

v17.4.0

新增

三维动态注记丰富避让策略设置
支持S3M数据接入
支持M3D2.1格式的栅格体元数据接入、配色方案设置、时态切换、透明度设置
兼容Cesium1.122版本

修复

优化绘制辅助剖切面(体)显隐状态控制
要素图层对接对gdbp数据的处理

v17.2.8

修复

三维（Cesium）引擎修复已知问题

v17.2.7

修复

三维（Cesium）引擎修复已知问题

v17.2.6

修复

三维（Cesium）引擎修复已知问题

v17.2.5

修复

三维（Cesium）引擎修复已知问题

v17.2.4

修复

三维（Cesium）引擎修复已知问题

v17.2.3

新增

三维（Cesium）引擎中兼容高版本Cesium加载IGS服务支持设置header

修复

三维（Cesium）引擎修复填挖方计算接口问题

v17.2.2

修复

三维（Cesium）引擎修复已知问题

v17.2.1

修复

三维（Cesium）引擎优化命名空间结构
三维（Cesium）引擎修复已知问题

v17.2.0

新增

三维（Cesium）引擎支持加载自定义裁图原点、自定义裁图方向的瓦片服务
三维（Cesium）引擎实现多DEM服务聚合显示

修复

三维（Cesium）引擎优化坡向分析中的箭头效果

v17.0.0

新增

支持WebClient库与第三方Cesium库混合开发
三维Cesium插件上支持聚合专题图

修复

提升Web端动态注记站立显示时性能Cesium引擎
优化阴影分析速度
M3D2.0缓存加载流畅度优化

v16.8.0

新增

地质体模型夸张显示（模型局部沿地心方向拉伸）
模型缓存增加线框显示和轮廓显示样式
支持在地质体模型中模拟隧道开挖
模型压平增加根据要素ID压平的功能。
支持通过二次开发扩展的方式实现三维钻孔渲染、多视图漫游功能
Billbord支持播放动图（git图或图片序列）
支持在对数缓冲下进行可视域分析

修复

漫游功能优化

v16.6.0

新增

新增三维场景碰撞检测功能
新增键盘漫游功能
新增自定义坐标系（如高斯）数据和服务(含矢量瓦片)的接入功能
新增全局的请求拦截器
新增水面倒影特效
新增地表（半）透明时，影像图层透明度独立控制功能
卷帘增加对以下图层类型的支持：Cesium3DTilesModelCahceLayer、IGSFeatureLayer、WFSLayer、GeoJSONLayer、KML、KMZ、CZML
模型编辑接口增加对 M3D、3DTiles 服务类型数据的支持
洪水淹没分析支持水面倒影
动态注记增加对含上下标、分式的三维标注的支持
视频投放功能支持投放到指定的场景元素上

v16.4.0

新增

新增支持支持视频调绘功能，支持基于视频流的调绘、量算
M3D 模型缓存图层新增支持自定义着色器，支持白模泛光特效的实现
新增支持动态河流覆盖物类型
新增模型沿地形漫游
新增基于服务端的地图要素查询，支持空间查询、属性查询；客户端查询新增支持根据 OID 显隐图元（M3D 2.0），设置图元透明度（M3D）
新增支持地图图片图层显示

修复

卷帘对比分析功能优化，支持纵向、横向常用的卷帘方式，支持矩形、小望远镜、多边形等自定义范围方式；
地形剖切分析功能优化，支持纹理封边；
视频投放功能优化，支持俯仰角、翻滚角、方位角、水平/竖直广角等参数设置
文字覆盖物显示效果优化，支持贴地图和站立两种类型
动态注记显示效果优化，支持在前端实时绘制矢量瓦片点要素动态注记，动态注记支持广告牌、贴地效果；支持避让；支持淡入淡出效果
优化客户端可视化效果，包括专题图表达、基于 EChart 的可视化、基于 MapV 的可视化显示效果

v16.2.0

新增

新增支持前端符号的二三维一体化管理
新增行业标绘功能：支持基础、军事两类符号的交互式编辑，支持属性、生长、显隐、闪烁、路径、比例等动画类型，支持态势编辑、管理、推演等功能
新增基于 GeoJson、要素图层创建单值、分段等前端三维专题图功能
新增任意面剖切
新增流动线、光晕等纹理效果
新增动态剖切封边功能
新增动态注记功能
新增模型绘存图层本地绘存功能
新增 M3D 模型位置和姿态编辑接口和工具
新增 M3D 模型按属性爆炸功能
新增地质体网格模型支持按空间范围进行筛选显示功能
新增 M3D 模型图层卷帘功能
新增角度测量工具
新增地形的网格化显示
动态剖切支持凹多边形折线
支持模型凹凸纹理贴图和显示
标注图层支持更丰富的注记样式：新增阴影、角度、空心、文字间距、文字轮廓、文字背景等 13 种样式
路径漫游支持不同路段设置不同的速度
Cesium 量算工具，量算结果单位支持自定义

修复

M3DServer、SceneServer 服务图层适配 M3D1.0 缓存数据
M3D 效率优化

v16.0.0

新增

新增瓦片错级机制
长度测量，增加避让处理、单位转换等功能，支持样式配置
注记图层增加控制可见性、显示文本长度等参数
动画漫游新增获取模型的方法、设定点不同速度漫游场景等功能
提升 MapGIS 矢量图层能力，提升 filter 查询、多区绘制、系统库设置等能力，支持设置线矢量图层的高度

修复

解决动画漫游设定速度和时间数组中方向向量计算问题
优化地形图层、注记图层等图层定位、及显示显示
优化测量，包括三角测量、贴地测量等功能
优化阴影分析、动画漫游等分析功能
优化多个接口，新增多个属性

v15.6.0

新增

注记图层增加最大显示文本长度参数
注记图层增加根据相机远近设置可见性的控制参数
增加 OGC WFS 加载接口
新增动态圆波纹后处理特效
新增雷达扫描后处理特效
模型图层加载新增支持跳转动画

修复

解决地形剖切结果 echart 对象无法修改大小
修改地形压平后为避免影响默认相机加载地形瓦片

v15.4.0

新增

新增 MapGIS 注记服务图层
添加服务数据接口新增是否开启缓存参数
新增支持 webMercator 坐标系 MapGIS 地图文档服务
新增地形剖切功能
新增支持 beijing54 椭球类型
新增支持基于 indexDB 实现 M3D 2.0 数据的前端属性存储和查询功能
新增支持 M3D 数据属性信息前端挂接
新增支持 M3D 数据 OID 拾取
新增多个三维示例

修复

优化 DrawElement 增加销毁对象方法
优化使用缓存后，数据稍大交互后无法正确加载数据
解决坡度坡向分析时，渲染结果不消失问题
优化数据加载性能
解决 DrawElement 对象造成鼠标移动卡顿问题
解决样式存在冲突的问题，统一加前缀
popup 的 visible 参数不支持 v-model
解决加载 mapgis 三维地图文档服务时需要支持图层过滤

v15.2.0

新增

实现模型压平功能,支持任意凸多边形的压平
提供解压 M3D 压缩数据流的功能，客户端支持将压缩的流进行高效解压，并渲染

修复

优化粒子特效：优化雨雪雾粒子效果，提升真实度；新增火焰、喷泉粒子特效、以及烟雾粒子特效
海量倾斜摄影数据缓存结构优化策略升级，提高网络传输效率以及前端渲染效率
加载渲染亿级 Las 格式点云数据，帧率在 15 帧以上，交互流畅；
加载渲染亿级地质网格剖分结果数据，帧率在 15 帧以上，交互流畅；
加载渲染千万级三角网单个地质体数据，帧率在 15 帧以上，交互流畅；
加载渲染 500 平方公里以上倾斜模型，帧率在 15 帧以上，交互流畅；
示例说明文档美化

v15.0.0

新增

全面整合了 Cesium 等脚本库，代码模块化，采用最新的 JavaScript ES6 标准；
提供 Cesium 开发库、示例、API，支持二三维数据可视化（含 M3D、OGC、MapGIS 地图服务、第三方地图服务等）、图形绘制、量算、模型漫游、三维查询与分析、场景特效，以及三维场景下的大数据可视化与分析等功能；
新增集成 Echarts、MapV 可视化库，支持在 Web 三维模式下实现大数据可视化、大数据分析功能；
新增集成 Turf.js 客户端空间分析库，提供 Web 三维客户端空间计算能力。

修复

Cesium 示例全面优化，提供配套示例说明文档与 API；