# CesiumSDK

**Repository Path**: morningSunLikely/cesium-sdk

## Basic Information

- **Project Name**: CesiumSDK
- **Description**: 集成一些常用的cesium小功能
tips:持续更新中...
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-07-22
- **Last Updated**: 2025-11-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CMap使用说明
注: 本工具包依赖于cesium,但并不包含cesium,需要使用者自己在index.html文件中以标签方式全局引入cesium依赖
+ cesium版本应不小于1.102 
+ 所有注明不推荐字样的使用方法,都是目前阶段不希望用户使用的操作方法,因为在编写对应构造函数时,并未完善实例销毁时操作,因此在此阶段也就不能提供给用户在新建对应构造函数实例之后有效销毁实例的方法
+ 使用该工具包完全不妨碍用户使用原生Cesium的viewer实例,用户通过使用`map.viewer`即可拿到原生的viewer实例
+ map实例对常用的一些viewer上的对象书写了getter函数,如
  ++ `map.entities === viewer.entities`
  ++ `map.dataSources === viewer.dataSources`
  ++ `map.camera === viewer.camera`
  ++ `map.scene === viewer.scene`
  ++ `map.canvas === viewer.canvas`
  ++ `map.clock === viewer.clock`
  ++ 若有更多需要进行getter函数的需求,可以反馈
## 1 创建地图Map类
> 创建map是使用该sdk包的起点,所有功能都基于map实例
> 支持根据已有viewer创建,也支持如原生cesium那般创建
### (1)如原生cesium那般创建(都推荐,看你自己需要)
```js
import * as CMap from '@/sdk'
import '@/sdk/assets/widgets.css'

const map = new CMap.Map('mapContainer',options)
/**
 * 第一个参数是挂载div容器的id
 * 第二个参数同cesium新建Viewer时的参数配置项,详情请查阅cesium文档
 */
```
### (2)根据已有viewer创建(都推荐,看你自己需要)
```js
import * as CMap from '@/sdk'
import '@/sdk/assets/widgets.css'

const viewer = new Cesium.Viewer('mapContainer',options)
const map = new CMap.Map('mapContainer',null,viewer)
/**
 * 第一个参数是挂载到的div容器的id
 * 第二个参数,已有viewer实例的情况,该参数请传入undefined/null
 * 第三个参数为viewer实例
 */
```
## 2 使用工具Tools类
> Tools构造函数已默认注册在map实例中,但仍支持单独实例化Tools构造函数
### (1)使用已注册的Tools构造函数实例(墙裂推荐)
#### 绘制 -- 持续开发更新中
所有的绘制工具都支持传入回调函数,以在绘制结束时机触发传入的回调函数
设计回调的目的在于,提供用户在绘制结束时的部分操作,如还原组件状态等
同时支持回调函数拿到绘制过程中产生的最终实体,以数据Array的形式存储
```js
// 绘制点 -- 需要使用绘制的点实体
map.tools.drawPoint((res)=>{})
// 绘制点 -- 不需要使用绘制的点实体
map.tools.drawPoint()
// 绘制线
map.tools.drawLine((res)=>{})
// 绘制面
map.tools.drawArea((res)=>{})
// 绘制圆
map.tools.drawCircle((res)=>{})
```
#### 测量 -- 功能开发中
> 直线距离
> 水平距离
> 垂直距离
> 角度
> 空间角度
> 扇形球面
#### 空间分析 -- 功能开发中
> 通视分析
> 可视域分析
> 坡度坡向分析
> 高差分析
#### 其他工具 -- 功能开发中
> 视点工具(主视点,恢复视点,设置视点,当前位置,当前相机位置等)
### (2)创建新的Tools构造函数实例(不推荐)
```js
import * as CMap from '@/sdk'
import '@/sdk/assets/widgets.css'

const tools = new CMap.Tools(map)
// 创建实例后,使用方法同上
// 绘制点
tools.drawPoint((res)=>{})
```
## 3 编辑绘制的实体DrawEditor类
(1)DrawEditor构造函数的实例已默认在map实例中创建,但支持用户自己创建新的DrawEditor构造函数实例,独立进行维护
(2)支持用户传入回调函数,回调函数将会在用户确认完成编辑之后触发,同时该回调函数支持拿到编辑的实体以Array格式存储
### (1)使用默认注册的DrawEditor实例(墙裂推荐)
```typeScript
// 通过在地球上拾取实体进入编辑
map.drawEditor.activate((res:Array<Cesium.Entity>):any=>{})
// 直接传入实体进入编辑
map.drawEditor.edit(entity:Cesium.Entity,(res:Array<Cesium.Entity>):any=>{})
/**
 * 特别注意,该类设计的初衷是对Tools构造函数绘制的实体进行编辑,故其有使用范围,只有实体包含以下属性适用
 * Editable = true
 * GeoType = 'point'/'polyline'/'polygon'/'ellipse'
 */
```
### (2)创建新的DrawEditor构造函数实例(不推荐)
```js
import * as CMap from '@/sdk'
import '@/sdk/assets/widgets.css'

const drawEditor = new CMap.DrawEditor(map)
// 使用方式同上
// 如通过拾取实体进入编辑
drawEditor.activate(res=>{})
// 如通过直接传入实体进入编辑
drawEditor.edit(entity,res=>{})
```
## 4 使用鼠标操作提示Reminder类
Reminder构造函数已默认在map实例中注册,同时也支持用户创建新的Reminder构造函数实例单独进行维护
### (1)使用默认注册的Reminder类(墙裂推荐)
```js
// 显示
map.reminder.show('一段提示文本信息')
// 隐藏
map.reminder.hide()
// 在已经显示提示文本的情况,如需要更新提示的文本,只需要再次调用show方法传入新文本即可
```
### (2)新建Reminder构造函数实例(不推荐)
```js
import * as CMap from '@/sdk'
import '@/sdk/assets/widgets.css'

const reminder = new CMap.Reminder(map)
// 显示
reminder.show('一段提示文本')
// 隐藏
reminder.hide()
```
## 5 使用封装的消息提示Message类
+ 该类目前仅支持通过map实例调用,没有放开对新建实例进行单独维护的支持
```js
/**
 * 以下方法均满足
 * 第一个参数是提示文本
 * 第二个参数是消息提示存在的时间
 */
// info消息提示
map.message.info('一段提示文字',5000)
// success成功提示
map.message.success('操作成功',1500)
// error错误提示
map.message.error('操作失败',2000)
// warning警告提示
map.message.warning('警告警告',2500)
```
该类是仿照antd和element框架的message编写的,目前只实现了基础功能
对于鼠标悬浮,提示不销毁 以及 支持用户点击关闭按钮关闭提示的功能暂未实现
## 6 使用封装的场景特效类Effects
目前支持的场景特效包括:
+ 全球海洋
+ 场景泛光(正在完善中)
### (1) 开启全球海洋特效Water
```js
// 显示
map.effects.water.show()
// 隐藏
map.effects.water.hide()
```
### (2) 开启场景泛光(正在完善中)
## 7 使用实体特效材质
+ 该类型材质主要是对自定义shader进行的封装
+ 所有材质均已在创建map实例时注册到Cesium依赖中去
+ 目前材质只适用于Entity类型的实体
### (1) 流动线--LineFlowMaterialProperty
```js
import Arrow from '@/sdk/assets/textures/Arrow.png'
map.entities.add({
    polyline: {
      positions: Cesium.Cartesian3.fromDegreesArray([114, 30, 126, 45]),
      material: new Cesium.LineFlowMaterialProperty({
        image: Arrow, // 该参数指定流动的图片,不传,则默认是Arrow
        speed: 5, // 该参数指定流动的速度,不传,则默认是1
        repeat: new Cesium.Cartesian2(10, 1), // 该参数指定流动材质的大小,不传,则默认是{x:1,y:1}
        color:Cesium.Color.AQUA, // 该参数指定流动线的颜色,不传则默认是red
      }),
      width: 5,
    },
  })
```
### (2) 动态扩散圆--CircleWaveMaterialProperty
```js
map.entities.add({
  position: Cesium.Cartesian3.fromDegrees(114, 40),
  ellipse: {
    semiMinorAxis: 500000,
    semiMajorAxis: 500000,
    material: new Cesium.CircleWaveMaterialProperty({
      color: Cesium.Color.AQUA, // 该参数指定动态扩散圆的颜色,不传,则默认是aqua
      duration: 5e3, // 该参数指定动态扩散圆的扩散速度,不传,则默认是1e3,e前面的数字越大扩散速度越快
      count: 1, // 该参数指定动态扩散圆的同心圆个数,不传,默认是2个同心圆在扩散
    })
  }
})
```
### (3) 动态墙--DynamicWallMaterialProperty
```js
map.viewer.entities.add({
  name: "立体墙效果",
  wall: {
    positions: Cesium.Cartesian3.fromDegreesArrayHeights([
      118.286419, 31.864436, 20000.0,
      119.386419, 31.864436, 20000.0,
      119.386419, 32.864436, 20000.0,
      118.286419, 32.864436, 20000.0,
      118.286419, 31.864436, 20000.0,
    ]),
    // 设置高度
    maximumHeights: new Array(5).fill(100000),
    minimumHeights: new Array(5).fill(1000),
    material: new Cesium.DynamicWallMaterialProperty({
      color: new Cesium.Color(1.0, 0.0, 0.0, 0.5), // 指定立体墙的颜色,不允许不传
      duration: 3000 // 指定立体墙一次动画的时长,不允许不传
    }),
  }
});
```
### (4) 更多实体材质持续开发更新中
### (5) 期望将来可以实现材质包,能通过Material调用,同时支持Primitive和Entity
## 8 拓展材质
> 拓展材质并未在map中进行默认注册,需要用户自己从sdk中导入
```js
// 如使用CircleBlurMaterialProperty
import { CircleBlurMaterialProperty } from '@/sdk'

map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(114,40),
  ellipse:{
    semiMajorAxis:500000,
    semiMinorAxis:500000,
    material:new Cesium.CircleBlurMaterialProperty({
      color:Cesium.Color.SKYBLUE,
      speed:5,
    })
  }
})
```
### (1) 圆实体(ellipse)相关拓展材质
- [CircleBlurMaterialProperty](#CircleBlurMaterialProperty)
- [CircleDiffuseMaterialProperty](#CircleDiffuseMaterialProperty)
- [CircleFadeMaterialProperty](#CircleFadeMaterialProperty)
- [CirclePulseMaterialProperty](#CirclePulseMaterialProperty)
- [CircleScanMaterialProperty](CircleScanMaterialProperty)
- [CircleSpiralMaterialProperty](CircleSpiralMaterialProperty)
- [CircleVaryMaterialProperty](#CircleVaryMaterialProperty)
- [CircleRotateMaterialProperty](#CircleRotateMaterialProperty)
#### CircleBlurMaterialProperty
```js
/**
 * @param {Cesium.Color} color 指定颜色
 * @param {Number} speed 与速度有关,shader中是sin(speed/1000)的函数,因此值越小,闪烁速度越快
 */
import { CircleBlurMaterialProperty } from '@/sdk'
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(114,40),
  ellipse:{
    semiMajorAxis:500000,
    semiMinorAxis:500000,
    material:new Cesium.CircleBlurMaterialProperty({
      color:Cesium.Color.SKYBLUE,
      speed:5,
    })
  }
})
```
#### CircleDiffuseMaterialProperty
```js
/**
 * 一个非常神奇的效果,具体有多神奇可以改变speed参数试试
 * @param {Cesium.Color} color 指定颜色
 * @param {Number} speed 与速度有关,单位是毫秒,
 */
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(124,57),
  ellipse:{
    semiMajorAxis:500000,
    semiMinorAxis:500000,
    material:new Cesium.CircleDiffuseMaterialProperty({
      color:Cesium.Color.RED,
      speed:500,
    })
  }
})
```
#### CircleFadeMaterialProperty
```js
/**
 * @param {Cesium.Color} color 指定圆的颜色
 * @param {Number} speed 0-1000,指定圆从圆心向外消失的速度,值越接近1000,速度越快,>=1000将失去动画
 */
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(102,57),
  ellipse:{
    semiMajorAxis:500000,
    semiMinorAxis:500000,
    material:new Cesium.CircleFadeMaterialProperty({
      color:Cesium.Color.RED,
      speed:50,
    })
  }
})
```
#### CirclePulseMaterialProperty
```js
/**
 * 脉冲圆效果
 * @param {Cesium.Color} color 指定圆的颜色
 * @param {Number} speed 0-1000指定圆从圆心向外消失的速度,值越接近1000,速度越快,>=1000,将失去动画
 */
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(102,57),
  ellipse:{
    semiMajorAxis:500000,
    semiMinorAxis:500000,
    material:new Cesium.CircleFadeMaterialProperty({
      color:Cesium.Color.RED,
      speed:50,
    })
  }
})
```
#### CircleScanMaterialProperty
```js
/**
 * 范围扫描圆效果
 * @param {Cesium.Color} color 指定圆的颜色
 * @param {Number} speed 指定圆从圆心向外扩散的速度,值越大,速度越快,大到一定程度,将失去动画,推荐为5
 */
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(103,31),
  ellipse:{
    semiMajorAxis:100000,
    semiMinorAxis:100000,
    material:new Cesium.CircleScanMaterialProperty({
      color:Cesium.Color.AQUA,
      speed:5,
    })
  }
})
```
#### CircleSpiralMaterialProperty
```js
/**
 * 范围扫描圆效果
 * @param {Cesium.Color} color 指定圆的颜色
 * @param {Number} speed 指定圆从圆心向外扩散的速度,值越大,速度越快,大到一定程度,将失去动画
 */
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(104,32),
  ellipse:{
    semiMajorAxis:100000,
    semiMinorAxis:100000,
    material:new Cesium.CircleSpiralMaterialProperty({
      color:Cesium.Color.AQUA,
      speed:50,
    })
  }
})
```
#### CircleVaryMaterialProperty
```js
/**
 * 多彩膨胀圆效果
 * @param {Cesium.Color} color 指定圆的颜色,不能决定多彩颜色,只是提供了vec函数的计算基数
 * @param {Number} speed 指定圆从圆心向外扩散的速度,值越大,速度越快,大到一定程度,将失去动画
 */
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(105,33),
  ellipse:{
    semiMajorAxis:100000,
    semiMinorAxis:100000,
    material:new Cesium.CircleVaryMaterialProperty({
      color:Cesium.Color.AQUA,
      speed:50,
    })
  }
})
```
#### CircleRingMaterialProperty
```js
/**
 * 静态同心环
 * @param {Cesium.Color} color 指定同心环的颜色
 */
map.entities.add({
  position:Cesium.Cartesian3.fromDegrees(106,34),
  ellipse:{
    semiMajorAxis:100000,
    semiMinorAxis:100000,
    material:new Cesium.CircleRingMaterialProperty({
      color:Cesium.Color.AQUA,
    })
  }
})
```
#### CircleRotateMaterialProperty
> 暂不开放使用
```js
/**
 * 还未测试,暂时未进行注册
 * @param {Cesium.Color} color 指定颜色
 * @param {String} image 指定贴图
 */
```
### (2) 圆柱实体(cylinder)相关拓展材质
- [CylinderFadeMaterialProperty](#cylinderfadematerialproperty)
#### CylinderFadeMaterialProperty
```js
/**
 * @param {Cesium.Color} color 指定圆柱实体的颜色
 */
map.entities.add({
  position: Cesium.Cartesian3.fromDegrees(107, 35),
  cylinder: {
    length: 500000,
    topRadius: 0,
    bottomRadius: 100000,
    material: new Cesium.CylinderFadeMaterialProperty({
      color: Cesium.Color.AQUA,
    })
  }
})
```
### (3) 球实体(ellipsoid)相关拓展材质
- [EllipsoidElectricMaterialProperty](#ellipsoidelectricmaterialproperty)
- [EllipsoidTrailMaterialProperty](#ellipsoidtrailmaterialproperty)
#### EllipsoidElectricMaterialProperty
```js
/**
 * 电弧球体材质
 * @param {Cesium.Color} color 指定电弧球体的颜色
 * @param {Number} speed 指定电弧动画的速度
 */
map.entities.add({
  position: Cesium.Cartesian3.fromDegrees(108, 36),
  ellipsoid: {
    radii: new Cesium.Cartesian3(100000, 100000, 100000),
    minimumCone: 0,
    maximumCone: 90 * Math.PI / 180,
    material: new Cesium.EllipsoidElectricMaterialProperty({
      color: Cesium.Color.LIGHTGREEN,
      speed:5.0,
    })
  }
})
```
#### EllipsoidTrailMaterialProperty
```js
/**
 * 瀑布球
 * @param {Cesium.Color} color 指定瀑布球的颜色
 * @param {Number} speed 指定瀑布落下的速度快慢,值越大,速度越快,值过大,将失去动画
 */
map.entities.add({
  position: Cesium.Cartesian3.fromDegrees(109, 37),
  ellipsoid: {
    radii: new Cesium.Cartesian3(100000, 100000, 100000),
    minimumCone: 0,
    maximumCone: 90 * Math.PI / 180,
    material: new Cesium.EllipsoidTrailMaterialProperty({
      color: Cesium.Color.AQUA.withAlpha(0.5),
      speed:50.0,
    })
  }
})
```