cesium笔记

Cesium viewer.entities.add() 常用属性详解

在 Cesium 中，viewer.entities.add()是最常用的实体添加方法之一。

它用于向场景中添加：

• 点
• 文字
• 图片
• 线
• 面
• 模型
• 圆柱
• 盒子
• 路径动画

等各种图形对象。

一、基础使用

viewer.entities.add({ name: '点位', position: Cesium.Cartesian3.fromDegrees(120, 30), point: { pixelSize: 10, color: Cesium.Color.RED, }, });

二、viewer.entities.add 基本结构

viewer.entities.add({ id, name, show, position, point, billboard, label, polyline, polygon, ellipse, rectangle, box, cylinder, corridor, wall, plane, model, path, orientation, description, availability, });

三、基础属性

1.id

实体唯一标识。

id: 'car001'

可以通过：

viewer.entities.getById('car001')

获取实体。

2.name

实体名称。

name: '车辆'

3.show

控制是否显示。

show: true

4.position（最重要）

控制实体位置。

通常使用：

Cesium.Cartesian3.fromDegrees()

进行经纬度转换。

position: Cesium.Cartesian3.fromDegrees( 120, 30, 100 )

参数：

四、点 Point

用于绘制简单点。

point: { pixelSize: 20, color: Cesium.Color.RED, outlineColor: Cesium.Color.WHITE, outlineWidth: 2, }

常用属性

五、图片 Billboard

用于显示图片图标。

billboard: { image: '/car.png', width: 40, height: 40, }

常用属性

六、文字 Label

用于显示文本。

label: { text: '杭州', font: '20px sans-serif', fillColor: Cesium.Color.WHITE, }

常用属性

七、线 Polyline

用于绘制线段。

polyline: { positions: Cesium.Cartesian3.fromDegreesArray([ 120,30, 121,31 ]), width: 5, material: Cesium.Color.RED }

常用属性

八、面 Polygon

用于绘制多边形。

polygon: { hierarchy: Cesium.Cartesian3.fromDegreesArray([ 120,30, 121,30, 121,31 ]), material: Cesium.Color.RED.withAlpha(0.5), }

九、圆 Ellipse

用于绘制圆形区域。

ellipse: { semiMinorAxis: 500, semiMajorAxis: 500, material: Cesium.Color.BLUE }

常用属性

十、盒子 Box

用于绘制立方体。

box: { dimensions: new Cesium.Cartesian3( 100, 100, 100 ), material: Cesium.Color.GREEN }

dimensions

盒子尺寸：

长 宽 高

十一、圆柱 Cylinder

用于绘制圆柱体。

cylinder: { length: 200, topRadius: 50, bottomRadius: 50, material: Cesium.Color.BLUE }

十二、模型 Model

用于加载 gltf/glb 模型。

model: { uri: '/car.glb', scale: 1, }

常用属性

十三、路径动画 Path

用于轨迹动画。

path: { width: 3, material: Cesium.Color.YELLOW }

十四、orientation 姿态

用于控制模型朝向。

orientation: Cesium.Transforms.headingPitchRollQuaternion( position, new Cesium.HeadingPitchRoll( heading, pitch, roll ) )

十五、description

点击实体后显示描述信息。

description: '这是一个点位'

支持 HTML：

description: ` <div> <h1>车辆信息</h1> <p>速度：100km/h</p> </div> `

十六、availability 时间控制

控制实体在某个时间范围内显示。

availability: new Cesium.TimeIntervalCollection([ new Cesium.TimeInterval({ start, stop }) ])

十七、综合案例

viewer.entities.add({ id: 'car1', position: Cesium.Cartesian3.fromDegrees( 120, 30, 100 ), billboard: { image: '/car.png', width: 40, height: 40, }, label: { text: '车辆1', pixelOffset: new Cesium.Cartesian2(0, -40), }, polyline: { positions: Cesium.Cartesian3.fromDegreesArray([ 120,30, 121,31 ]), width: 2, material: Cesium.Color.YELLOW, } });

十八、总结

viewer.entities.add()本质上就是：

一个实体对象 + 多个图形组件

例如：

实体 ├── 点 point ├── 图片 billboard ├── 文字 label ├── 线 polyline ├── 面 polygon └── 模型 model

这些图形组件都可以同时存在于一个实体上。

因此 Entity 是 Cesium 中最核心、最常用的数据组织方式之一。

Cesium 中 withAlpha 与 material 详解

在 Cesium 中，经常会看到：

Cesium.Color.BLUE.withAlpha(0.4)

以及：

material: Cesium.Color.RED

很多刚接触 Cesium 的同学会疑惑：

• withAlpha是什么意思？
• material到底是什么？
• 为什么 point 用 color，而线面用 material？

这篇文章详细讲解。

一、Cesium.Color.BLUE.withAlpha(0.4) 是什么意思？

Cesium.Color.BLUE

表示：

蓝色

而：

.withAlpha(0.4)

表示：

设置透明度

所以：

Cesium.Color.BLUE.withAlpha(0.4)

整体意思：

半透明蓝色

二、Alpha 是什么？

Alpha 表示：

透明度

取值范围：

0 ~ 1

常见透明度

三、示例

1.完全不透明

Cesium.Color.RED

等价于：

Cesium.Color.RED.withAlpha(1)

2.半透明

Cesium.Color.RED.withAlpha(0.5)

3.完全透明

Cesium.Color.RED.withAlpha(0)

四、material 是什么？

很多人会误以为：

material = 颜色

其实并不是。

material 本质是：

材质

你可以理解成：

物体表面怎么渲染

例如：

• 纯颜色
• 图片贴图
• 网格
• 流光
• 发光
• 水波纹
• 动画效果

这些都属于：

material

五、point 为什么不用 material？

因为：

point 本身只是简单像素点

它不像：

• 线
• 面
• 模型

需要复杂表面渲染。

所以 point 直接：

color

即可。

六、Point 点

point: { pixelSize: 20, color: Cesium.Color.RED }

point 常用属性

七、Polyline 线

线使用：

material

示例

polyline: { positions: [], width: 5, material: Cesium.Color.RED }

八、Polygon 面

polygon: { hierarchy: [], material: Cesium.Color.BLUE.withAlpha(0.5) }

九、Ellipse 圆形区域

ellipse: { semiMajorAxis: 1000, semiMinorAxis: 1000, material: Cesium.Color.RED.withAlpha(0.4) }

十、Box 盒子

box: { dimensions: new Cesium.Cartesian3( 100, 100, 100 ), material: Cesium.Color.GREEN }

十一、material 最简单写法

1.纯颜色

material: Cesium.Color.RED

2.半透明颜色

material: Cesium.Color.RED.withAlpha(0.5)

十二、material 还能写什么？

除了颜色。

还能：

1.ImageMaterialProperty（图片材质）

material: new Cesium.ImageMaterialProperty({ image: '/xxx.png' })

2.ColorMaterialProperty（颜色材质）

material: new Cesium.ColorMaterialProperty( Cesium.Color.RED )

3.StripeMaterialProperty（条纹）

material: new Cesium.StripeMaterialProperty({ evenColor: Cesium.Color.WHITE, oddColor: Cesium.Color.BLUE, repeat: 10, })

4.GridMaterialProperty（网格）

material: new Cesium.GridMaterialProperty({ color: Cesium.Color.YELLOW })

5.PolylineGlowMaterialProperty（发光线）

material: new Cesium.PolylineGlowMaterialProperty({ glowPower: 0.2, color: Cesium.Color.CYAN })

6.PolylineDashMaterialProperty（虚线）

material: new Cesium.PolylineDashMaterialProperty({ color: Cesium.Color.YELLOW })

十三、总结

1.withAlpha 是透明度

Cesium.Color.BLUE.withAlpha(0.4)

意思：

40%透明度的蓝色

2.material 本质

material = 材质 = 表面渲染方式

不仅仅是颜色。

3.point 和其他图形区别

4.material 最常见写法

material: Cesium.Color.RED

或者：

material: Cesium.Color.R

Cesium 模型加载详解（Entity 与 Primitive）

大家好，这篇文章来详细讲一下 Cesium 中如何加载 3D 模型。

在实际开发中：

• 数字孪生
• BIM
• 智慧园区
• 智慧城市
• 车辆轨迹
• 无人机

这些场景都会使用到模型加载。

而 Cesium 中最常见的模型格式是：

gltf glb

其中：

• gltf：json + 贴图分离
• glb：二进制一体化模型

实际项目推荐：

优先使用 glb

因为部署简单、体积更小。

一、Cesium 中加载模型的两种方式

Cesium 里面主要有两种加载模型的方式：

新手建议：

先学 Entity

后面再学习 Primitive。

二、最简单的模型加载（Entity方式）

这是实际业务开发中最常见的方式。

import * as Cesium from 'cesium' const viewer = new Cesium.Viewer('cesiumContainer') const entity = viewer.entities.add({ name: '汽车模型', // 模型位置 position: Cesium.Cartesian3.fromDegrees( 120.15, 30.28, 0 ), // 模型配置 model: { // 模型路径 uri: '/model/car.glb', // 缩放 scale: 1, // 最小像素 minimumPixelSize: 64, // 最大缩放 maximumScale: 20000 } }) // 相机飞到模型位置 viewer.flyTo(entity)

效果：

模型会出现在对应经纬度的位置

三、Cesium 最核心的坐标系统

Cesium 内部使用的是：

Cartesian3

但是我们平时使用的是：

经度 纬度 高度

所以需要转换：

Cesium.Cartesian3.fromDegrees( 经度, 纬度, 高度 )

例如：

Cesium.Cartesian3.fromDegrees( 120, 30, 100 )

表示：

经度120 纬度30 高度100米

四、模型配置详解

1、uri

模型路径。

uri: '/model/car.glb'

2、scale

模型缩放。

scale: 10

很多模型真实尺寸特别小。

所以实际开发经常需要：

放大几十倍甚至几百倍

3、minimumPixelSize

最小像素。

minimumPixelSize: 64

作用：

即使镜头拉远 模型也不会太小

4、maximumScale

最大缩放限制。

maximumScale: 20000

避免模型无限放大。

五、模型不显示的常见原因

这是新手最容易踩坑的地方。

1、模型路径错误

例如：

uri: '/model/car.glb'

必须保证：

http://localhost:xxxx/model/car.glb

浏览器能够访问。

2、模型太小

很多模型真实尺寸可能只有几厘米。

解决：

scale: 100

3、镜头没飞过去

模型其实已经加载成功。

只是镜头不在附近。

解决：

viewer.flyTo(entity)

4、模型被埋地下

高度可能不正确。

尝试：

Cesium.Cartesian3.fromDegrees( 120, 30, 100 )

增加高度。

六、模型方向控制

很多时候模型朝向不正确。

Cesium 中使用：

例如：

const hpr = new Cesium.HeadingPitchRoll( Cesium.Math.toRadians(90), 0, 0 ) entity.orientation = Cesium.Transforms.headingPitchRollQuaternion( entity.position.getValue(), hpr )

七、为什么 Cesium 要使用弧度

Cesium 所有旋转：

都使用弧度

所以：

Cesium.Math.toRadians(90)

作用：

角度转弧度

八、动态移动模型

修改 position 即可。

例如：

entity.position = Cesium.Cartesian3.fromDegrees( lng, lat, height )

实现动态移动：

let lng = 120 setInterval(() => { lng += 0.001 entity.position = Cesium.Cartesian3.fromDegrees( lng, 30, 0 ) }, 100)

效果：

模型会持续移动

九、Primitive / Model 加载方式

这是更底层的方式。

适合：

• BIM
• 数字孪生
• 倾斜摄影
• 大批量模型
• 高性能场景

示例：

const model = await Cesium.Model.fromGltfAsync({ url: '/model/car.glb', modelMatrix: Cesium.Transforms.eastNorthUpToFixedFrame( Cesium.Cartesian3.fromDegrees( 120, 30 ) ), scale: 1 }) viewer.scene.primitives.add(model)

十、Entity 与 Primitive 区别

十一、模型动画

有些 glb 模型自带动画。

例如：

• 人物走路
• 飞机旋转
• 机械运动

开启方式：

model: { uri: '/model/man.glb', runAnimations: true }

十二、模型贴地

模型可能会悬空。

Cesium 提供：

heightReference: Cesium.HeightReference.CLAMP_TO_GROUND

例如：

model: { uri: '/model/car.glb', heightReference: Cesium.HeightReference.CLAMP_TO_GROUND }

效果：

模型会贴合地形

十三、项目中的常见封装

实际开发中一般都会封装：

addModel()

例如：

function addModel(viewer, options) { return viewer.entities.add({ name: options.name, position: Cesium.Cartesian3.fromDegrees( options.lng, options.lat, options.height || 0 ), model: { uri: options.url, scale: options.scale || 1, minimumPixelSize: 64 } }) }

使用：

addModel(viewer, { name: '汽车', lng: 120, lat: 30, url: '/model/car.glb', scale: 10 })

十四、Cesium 后续重点学习内容

学习模型之后，后面通常还会接触：

• billboard
• label
• polyline
• polygon
• primitive
• material
• shader
• 粒子系统
• 轨迹动画
• 热力图
• 聚合

但最核心的是：

3D Tiles

因为：

• 倾斜摄影
• 城市模型
• BIM
• 数字孪生

基本都依赖它。

十五、推荐学习路线

建议学习顺序：

1. Entity 2. billboard 3. label 4. polyline 5. polygon 6. model 7. primitive 8. material 9. shader 10. 3dtiles

这样会更容易理解 Cesium 的整体体系。

总结

Cesium 模型加载核心就两种：

Entity Primitive

其中：

• Entity 更适合业务开发
• Primitive 更适合大型项目和高性能场景

而模型开发中最核心的知识点包括：

• Cartesian3
• 经纬度转换
• heading/pitch/roll
• 模型缩放
• 模型贴地
• 动态移动
• 3D Tiles

掌握这些之后，就可以开始真正进入：

数字孪生开发

了。