Cesium 快速入门（六）实体类型介绍

Cesium 快速入门（六）实体类型介绍

看过的知识不等于学会。唯有用心总结、系统记录，并通过温故知新反复实践，才能真正掌握一二
作为一名摸爬滚打三年的前端开发，开源社区给了我饭碗，我也将所学的知识体系回馈给大家，助你少走弯路！
OpenLayers、Leaflet 快速入门 ，每周保持更新 2 个案例
Cesium 快速入门，每周保持更新 4 个案例

Cesium 快速入门（一）快速搭建项目
Cesium 快速入门（二）底图更换
Cesium 快速入门（三）Viewer：三维场景的“外壳”
Cesium 快速入门（四）相机控制完全指南
Cesium 快速入门（五）坐标系
Cesium 快速入门（六）实体类型介绍
Cesium 快速入门（七）材质详解
Cesium 快速入门（八）Primitive（图元）系统深度解析
Cesium 快速入门（九）Appearance（外观）系统深度解析
Cesium 快速入门（十） JulianDate（儒略日期）详解
Cesium 快速入门（十一）3D Tiles 大规模三维地理空间数据
Cesium 快速入门（十二）数据加载详解
Cesium 快速入门（十三）事件系统

Cesium 实体详解

实体核心概念

实体（Entity）是 Cesium 中用于表示动态时空对象的核心概念，是构建复杂三维场景的基础。通过实体系统，开发者可以轻松创建和管理点、线、面、模型等可视化元素，并支持时间动态属性、数据绑定和空间分析等高级功能。

实体系统的主要优势：

• 声明式 API：简化复杂三维对象的创建过程
• 时空动态性：支持随时间变化的属性动画
• 层次化管理：通过父子关系构建复杂对象结构
• 数据驱动：与数据源（DataSource）无缝集成
• 自动优化：内置渲染优化和内存管理

实体类型

实体公共属性

所有实体类型共享以下公共属性：

实体类型详解

点（Point）

点实体用于在三维空间中标记特定位置，始终以像素大小渲染，不受相机距离影响（除非设置了缩放属性）。

基础实例

<template>
  <div ref="cesiumContainer" class="container"></div>
</template>

<script setup>
import { ref, onMounted } from "vue";
import * as Cesium from "cesium";
const cesiumContainer = ref(null);
let viewer = null;

// 天地图TOKEN
const token = "05be06461004055923091de7f3e51aa6";

onMounted(() => {
  // 初始化Viewer
  viewer = new Cesium.Viewer(cesiumContainer.value, {
    geocoder: false, // 关闭地理编码搜索
    homeButton: false, // 关闭主页按钮
    sceneModePicker: false, // 关闭场景模式选择器
    baseLayerPicker: false, // 关闭底图选择器
    navigationHelpButton: false, // 关闭导航帮助
    animation: false, // 关闭动画控件
    timeline: false, // 关闭时间轴
    fullscreenButton: false, // 关闭全屏按钮
    baseLayer: false, // 关闭默认地图
  });
  // 清空logo
  viewer.cesiumWidget.creditContainer.style.display = "none";

  // 添加实体
  const pointEntity = viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075, 50),
    point: {
      color: Cesium.Color.RED.withAlpha(0.8), // 80%不透明的红色
      pixelSize: 20, // 直径20像素
      outlineColor: Cesium.Color.WHITE, // 白色轮廓
      outlineWidth: 3, // 轮廓宽度3像素
      heightReference: Cesium.HeightReference.CLAMP_TO_GROUND, // 贴地显示
    },
  });
  viewer.zoomTo(pointEntity); // 缩放到实体位置

  initMap();
});

// 加载天地图
const initMap = () => {
  // 以下为天地图及天地图标注加载
  const tiandituProvider = new Cesium.WebMapTileServiceImageryProvider({
    url:
      "http://{s}.tianditu.gov.cn/img_w/wmts?service=wmts&request=GetTile&version=1.0.0&LAYER=img&tileMatrixSet=w&TileMatrix={TileMatrix}&TileRow={TileRow}&TileCol={TileCol}&style=default&format=tiles&tk=" +
      token,
    layer: "img",
    style: "default",
    format: "tiles",
    tileMatrixSetID: "w", // 天地图使用 Web 墨卡托投影（EPSG:3857），需确保 tileMatrixSetID: "w"
    subdomains: ["t0", "t1", "t2", "t3", "t4", "t5", "t6", "t7"], // 子域名
    maximumLevel: 18,
    credit: new Cesium.Credit("天地图影像"),
  });

  // 添加地理标注
  const labelProvider = new Cesium.WebMapTileServiceImageryProvider({
    url:
      "http://{s}.tianditu.gov.cn/cia_w/wmts?service=wmts&request=GetTile&version=1.0.0&LAYER=cia&tileMatrixSet=w&tileMatrix={TileMatrix}&tileRow={TileRow}&tileCol={TileCol}&style=default&format=tiles&tk=" +
      token,
    layer: "img",
    style: "default",
    format: "tiles",
    tileMatrixSetID: "w",
    subdomains: ["t0", "t1", "t2", "t3", "t4", "t5", "t6", "t7"], // 子域名轮询
    maximumLevel: 18,
    credit: new Cesium.Credit("天地图影像"),
  });
  // 天地图影像添加到viewer实例的影像图层集合中
  viewer.imageryLayers.addImageryProvider(tiandituProvider);
  // 天地图地理标注（后添加的会覆盖前面的）
  viewer.imageryLayers.addImageryProvider(labelProvider);
};
</script>
<style scoped>
.container {
  width: 100vw;
  height: 100vh;
}
</style>

动态属性应用

实现点的距离相关缩放和透明度变化：

// 距离越近越大，越远越小
pointEntity.point.scaleByDistance = new Cesium.NearFarScalar(
  1000, // 相机距离1000米时
  2.0, // 缩放至2倍大小
  5000, // 相机距离5000米时
  0.5 // 缩放至0.5倍大小
);

// 距离越近越不透明，越远越透明
pointEntity.point.translucencyByDistance = new Cesium.NearFarScalar(
  500,
  1.0, // 500米时完全不透明
  2000,
  0.2 // 2000米时20%透明度
);

// 相机距离 100-5000 米之间显示点
pointEntity.point.distanceDisplayCondition =
  new Cesium.DistanceDisplayCondition(
    100, // 最小可见距离（米）
    5000 // 最大可见距离（米）
  );

高级技巧

聚合大量点（Cluster）

<template>
  <div ref="cesiumContainer" class="container"></div>
</template>

<script setup>
import { ref, onMounted } from "vue";
import * as Cesium from "cesium";
const cesiumContainer = ref(null);
let viewer = null;

// 天地图TOKEN
const token = "05be06461004055923091de7f3e51aa6";

onMounted(() => {
  // 初始化Viewer
  viewer = new Cesium.Viewer(cesiumContainer.value, {
    geocoder: false, // 关闭地理编码搜索
    homeButton: false, // 关闭主页按钮
    sceneModePicker: false, // 关闭场景模式选择器
    baseLayerPicker: false, // 关闭底图选择器
    navigationHelpButton: false, // 关闭导航帮助
    animation: false, // 关闭动画控件
    timeline: false, // 关闭时间轴
    fullscreenButton: false, // 关闭全屏按钮
    baseLayer: false, // 关闭默认地图
  });
  // 清空logo
  viewer.cesiumWidget.creditContainer.style.display = "none";

  // 创建支持聚合的数据源
  const clusteredDataSource = new Cesium.CustomDataSource("clusteredData");

  // 添加到 Viewer
  viewer.dataSources.add(clusteredDataSource);

  // 启用聚合
  clusteredDataSource.clustering.enabled = true;

  // 配置聚合参数
  clusteredDataSource.clustering.pixelRange = 48; // 聚合像素范围
  clusteredDataSource.clustering.minimumClusterSize = 3; // 最小聚合点数

  // 添加点实体
  for (let i = 0; i < 1000; i++) {
    clusteredDataSource.entities.add({
      position: Cesium.Cartesian3.fromDegrees(
        116.3975 + Math.random() * 0.01, // 随机偏移
        39.9075 + Math.random() * 0.01, // 随机偏移
        50
      ),
      point: {
        pixelSize: 15,
        color: Cesium.Color.fromRandom(),
      },
      id: `point-${i}`,
    });
  }
  // 缩放到所有点
  viewer.zoomTo(clusteredDataSource);

  initMap();
});

// 加载天地图
const initMap = () => {
  // 以下为天地图及天地图标注加载
  const tiandituProvider = new Cesium.WebMapTileServiceImageryProvider({
    url:
      "http://{s}.tianditu.gov.cn/img_w/wmts?service=wmts&request=GetTile&version=1.0.0&LAYER=img&tileMatrixSet=w&TileMatrix={TileMatrix}&TileRow={TileRow}&TileCol={TileCol}&style=default&format=tiles&tk=" +
      token,
    layer: "img",
    style: "default",
    format: "tiles",
    tileMatrixSetID: "w", // 天地图使用 Web 墨卡托投影（EPSG:3857），需确保 tileMatrixSetID: "w"
    subdomains: ["t0", "t1", "t2", "t3", "t4", "t5", "t6", "t7"], // 子域名
    maximumLevel: 18,
    credit: new Cesium.Credit("天地图影像"),
  });

  // 添加地理标注
  const labelProvider = new Cesium.WebMapTileServiceImageryProvider({
    url:
      "http://{s}.tianditu.gov.cn/cia_w/wmts?service=wmts&request=GetTile&version=1.0.0&LAYER=cia&tileMatrixSet=w&tileMatrix={TileMatrix}&tileRow={TileRow}&tileCol={TileCol}&style=default&format=tiles&tk=" +
      token,
    layer: "img",
    style: "default",
    format: "tiles",
    tileMatrixSetID: "w",
    subdomains: ["t0", "t1", "t2", "t3", "t4", "t5", "t6", "t7"], // 子域名轮询
    maximumLevel: 18,
    credit: new Cesium.Credit("天地图影像"),
  });
  // 天地图影像添加到viewer实例的影像图层集合中
  viewer.imageryLayers.addImageryProvider(tiandituProvider);
  // 天地图地理标注（后添加的会覆盖前面的）
  viewer.imageryLayers.addImageryProvider(labelProvider);
};
</script>
<style scoped>
.container {
  width: 100vw;
  height: 100vh;
}
</style>

线（Polyline）

线实体用于连接多个点形成连续线段，支持测地线（沿地球表面）、恒向线和直线三种模式。

基础实例：测地线

const positions = Cesium.Cartesian3.fromDegreesArray([
  116.3975,
  39.9075, // 北京
  121.4737,
  31.2304, // 上海
  114.1694,
  30.5812, // 武汉
]);

const polyline = viewer.entities.add({
  polyline: {
    positions: positions,
    width: 8,
    material: Cesium.Color.BLUE,
    arcType: Cesium.ArcType.GEODESIC, // 沿地球表面绘制
    clampToGround: true, // 贴地显示
  },
});

高级材质：虚线

// 虚线样式
polyline.polyline.material = new Cesium.PolylineDashMaterialProperty({
  color: Cesium.Color.GREEN,
  dashLength: 20,
  dashPattern: 0x9999, // 自定义虚线模式
});

多边形（Polygon）

多边形实体用于创建封闭的二维区域，支持孔洞、拉伸高度和纹理映射等高级特性。

基础实例

const positions = Cesium.Cartesian3.fromDegreesArray([
  116.397,
  39.907, // 第一个点
  116.407,
  39.907, // 第二个点
  116.407,
  39.917, // 第三个点
  116.397,
  39.917, // 第四个点
]);

const polygon = viewer.entities.add({
  polygon: {
    hierarchy: positions,
    material: Cesium.Color.RED.withAlpha(0.5), // 半透明红色
    outline: true,
    outlineWidth: 20,
    outlineColor: Cesium.Color.WHITE,
  },
});

带孔洞多边形实例

hierarchy 属性为 PolygonHierarchy 类型，该类型可以接受一个 Cartesian3 数组，也可以接受一个 PolygonHierarchy 数组，用于定义多边形的顶点位置和孔的位置。

// 外部轮廓
const outerPositions = Cesium.Cartesian3.fromDegreesArray([
  116.39, 39.9, 116.41, 39.9, 116.41, 39.92, 116.39, 39.92,
]);

// 内部孔洞
const innerPositions = Cesium.Cartesian3.fromDegreesArray([
  116.397, 39.907, 116.403, 39.907, 116.403, 39.913, 116.397, 39.913,
]);

const polygon = viewer.entities.add({
  polygon: {
    hierarchy: new Cesium.PolygonHierarchy(outerPositions, [
      new Cesium.PolygonHierarchy(innerPositions),
    ]),
    material: Cesium.Color.RED.withAlpha(0.5),
    outline: true,
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2,
    height: 100, // 从100米高度开始
    extrudedHeight: 300, // 拉伸至300米高度
  },
});

模型（Model）

模型实体用于加载和显示 3D 模型，支持 glTF/glb 格式，是实现复杂三维场景的关键技术。

注意:路径就是uri,不是url

基础实例

注意点: 无法使用import引入glb数据

1. 可以将模型放在 public 目录下,建一个 models 文件,使用/models/Cesium_Air.glb
2. 自定义模型路径,使用new URL("./models/Cesium_Air.glb", import.meta.url).href引入路径
3. 以下模型是我从 cesium 官网中下载的,放在了该开源项目上,路径/src/Aassets/Basics/models

const modelEntity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.397, 39.907, 100),
  model: {
    // uri: '/models/Cesium_Air.glb', // 模型在public目录下
    uri: new URL("./models/Cesium_Air.glb", import.meta.url).href,
    scale: 10.0,
    minimumPixelSize: 128, // 最小像素尺寸
    maximumScale: 20000, // 最大缩放比例
  },
});

动态位置

// 动态位置
let t = 0.000001;
modelEntity.position = new Cesium.CallbackProperty(() => {
  t += 0.000001;
  return Cesium.Cartesian3.fromDegrees(116.397 + t, 39.907, 100);
}, false);

// 相机跟随实体
viewer.trackedEntity = modelEntity;

模型裁剪与剖面分析

// 创建裁剪平面（垂直于X轴）
const clippingPlane = new Cesium.ClippingPlane(
  new Cesium.Cartesian3(1, 0, 0), // 法线方向
  0 // 距离原点的距离
);

modelEntity.model.clippingPlanes = new Cesium.ClippingPlaneCollection({
  planes: [clippingPlane],
  edgeWidth: 1.0, // 裁剪边缘宽度
  edgeColor: Cesium.Color.RED, // 裁剪边缘颜色
});

广告牌（Billboard）

广告牌实体用于在 3D 场景中显示 2D 图像，始终面向相机，适合标记位置或显示图标。

基础实例

const billboard = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075),
  billboard: {
    image: "/images/marker.png", // 图标路径
    scale: 0.5,
    color: Cesium.Color.WHITE,
    horizontalOrigin: Cesium.HorizontalOrigin.CENTER,
    verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
    // pixelOffset: new Cesium.Cartesian2(0, -20), // 向上偏移20像素
  },
});
billboard.billboard.pixelOffset = new Cesium.Cartesian2(0, -50); // 向下偏移 50 像素

箱（Box）

箱（Box）是 Cesium 中用于表示三维矩形的核心元素。它可以用于创建 3D 模型、表示物体的边界框、可视化数据等。

基础实例

const box = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075, 50),
  box: {
    dimensions: new Cesium.Cartesian3(1000, 1000, 500), // 长、宽、高
    material: Cesium.Color.RED.withAlpha(0.5), // 半透明红色
    outline: true,
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2,
    heightReference: Cesium.HeightReference.CLAMP_TO_GROUND, // 贴地显示
  },
});

矩形（Rectangle）

基础实例

const rectangle = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075, 50),
  rectangle: {
    coordinates: Cesium.Rectangle.fromDegrees(
      116.3975,
      39.9075,
      116.4075,
      39.9175
    ), // 矩形的坐标
    material: Cesium.Color.GREEN.withAlpha(0.5), // 半透明绿色
    outline: true,
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2,
    height: 100, // 矩形的高度
    extrudedHeight: 200, // 矩形的拉伸高度
    heightReference: Cesium.HeightReference.CLAMP_TO_GROUND, // 贴地显示
  },
});

椭圆（Ellipse）

基础实例

const ellipse = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075, 50),
  ellipse: {
    semiMajorAxis: 1000, // 长半轴
    semiMinorAxis: 500, // 短半轴
    material: Cesium.Color.BLUE.withAlpha(0.5), // 半透明蓝色
    outline: true,
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2,
    height: 100, // 椭圆的高度
    extrudedHeight: 200, // 椭圆的拉伸高度
    heightReference: Cesium.HeightReference.CLAMP_TO_GROUND, // 贴地显示
  },
});

椭圆体（Ellipsoid）

基础实例

const ellipsoid = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075, 50),
  ellipsoid: {
    radii: new Cesium.Cartesian3(1000, 500, 250), // 长半轴、短半轴、高半轴
    material: Cesium.Color.YELLOW.withAlpha(0.5), // 半透明黄色
    outline: true,
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2,
    extrudedHeight: 200, // 椭圆体的拉伸高度
    heightReference: Cesium.HeightReference.CLAMP_TO_GROUND, // 贴地显示
  },
});

圆柱体（Cylinder）

基础实例

const cylinder = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075, 50),
  cylinder: {
    length: 1000, // 圆柱体的长度
    topRadius: 500, // 顶部半径
    bottomRadius: 500, // 底部半径
    material: Cesium.Color.PURPLE.withAlpha(0.5), // 半透明紫色
    extrudedHeight: 200, // 圆柱体的拉伸高度
  },
});

标签（Label）

基础实例

const label = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.3975, 39.9075, 50),
  label: {
    text: "Hello World", // 标签文本
    font: "30px sans-serif", // 字体
    style: Cesium.LabelStyle.FILL, // 样式
    fillColor: Cesium.Color.WHITE, // 填充颜色
    outlineColor: Cesium.Color.BLACK, // 轮廓颜色
    outlineWidth: 2, // 轮廓宽度
    scale: 1.0, // 缩放比例
    showBackground: true, // 显示背景
    backgroundColor: Cesium.Color.TRANSPARENT, // 背景颜色
    backgroundPadding: new Cesium.Cartesian2(7, 5), // 背景填充
    heightReference: Cesium.HeightReference.CLAMP_TO_GROUND, // 贴地显示
    horizontalOrigin: Cesium.HorizontalOrigin.CENTER, // 水平对齐方式
    verticalOrigin: Cesium.VerticalOrigin.BOTTOM, // 垂直对齐方式
    pixelOffset: new Cesium.Cartesian2(0, -50), // 向下偏移 50 像素
    eyeOffset: new Cesium.Cartesian3(0, 0, 0), // 相对于相机的偏移量
  },
});

墙（Wall）

基础实例

const wall = viewer.entities.add({
  wall: {
    positions: Cesium.Cartesian3.fromDegreesArrayHeights([
      116.3975, 39.9075, 100, 116.4075, 39.9075, 100, 116.4075, 39.9175, 100,
      116.3975, 39.9175, 100, 116.3975, 39.9075, 100,
    ]),
    material: Cesium.Color.GREEN.withAlpha(0.5), // 半透明绿色
    outline: true,
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2,
    maximumHeights: [100, 100, 200, 100, 100], // 每个顶点的最大高度
    minimumHeights: [0, 0, 0, 0, 0], // 每个顶点的最小高度
  },
});

走廊（Corridor）

基础实例

const corridor = viewer.entities.add({
  corridor: {
    positions: Cesium.Cartesian3.fromDegreesArrayHeights([
      116.3975, 39.9075, 100, 116.4075, 39.9075, 100, 116.4075, 39.9175, 100,
    ]),
    width: 100, // 走廊宽度
    height: 50, // 走廊高度
    material: Cesium.Color.ORANGE.withAlpha(0.5), // 半透明橙色
    extrudedHeight: 20, // 走廊拉伸高度
    outline: true,
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2,
  },
});

路径（Path）

性能优化建议

1. 实体数量控制

• 当实体数量超过 1000 时，考虑使用BillboardCollection和Primitive等底层 API
• 利用DataSource的clustering功能聚合大量实体：

dataSource.clustering.enabled = true;
dataSource.clustering.pixelRange = 40; // 聚合像素范围
dataSource.clustering.minimumClusterSize = 5; // 最小聚合数量

2. 属性优化

• 避免使用CallbackProperty（尤其是高频更新的），优先使用SampledProperty

• 对于静态属性，直接赋值而非使用属性对象：

  // 推荐
  entity.point.pixelSize = 10;
  
  // 不推荐（除非需要动态变化）
  entity.point.pixelSize = new Cesium.ConstantProperty(10);
  

3. 内存管理

• 及时移除不再需要的实体：

  // 移除单个实体
  viewer.entities.remove(entity);
  
  // 移除所有实体
  viewer.entities.removeAll();
  
  // 移除数据源中的实体
  dataSource.entities.removeAll();
  

• 对于临时效果（如粒子系统），设置lifetime自动销毁

4. 渲染优化

• 合理设置distanceDisplayCondition控制远距离实体的显示：

  entity.distanceDisplayCondition = new Cesium.DistanceDisplayCondition(
    100, // 最小可见距离（米）
    5000 // 最大可见距离（米）
  );
  

• 使用disableDepthTestDistance解决标签遮挡问题：

  entity.label.disableDepthTestDistance = Number.POSITIVE_INFINITY;
  

常见问题解答

Q1: 实体位置和模型位置有什么区别？

A1: 实体的position属性定义了实体的局部坐标系原点，而模型的modelMatrix定义了模型相对于实体原点的变换。对于简单使用，直接设置position即可；当需要复杂变换时，可以通过modelMatrix实现模型的平移、旋转和缩放。

Q2: 如何实现实体的点击事件？

A2: 使用ScreenSpaceEventHandler监听鼠标点击，并通过scene.pick方法检测实体：

const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction(function (click) {
  const pickedObject = viewer.scene.pick(click.position);
  if (
    Cesium.defined(pickedObject) &&
    pickedObject.id instanceof Cesium.Entity
  ) {
    const entity = pickedObject.id;
    console.log("点击了实体:", entity.name);
    // 显示实体信息面板等操作
  }
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

Q3: 实体属性的优先级是怎样的？

A3: Cesium 实体系统的属性优先级从高到低为：

1. 实体的具体属性（如point、polyline等）
2. 实体的公共属性（如position、orientation等）
3. 父实体的继承属性
4. 数据源的默认样式