Cesium快速入门到精通系列教程八：Primitive和Entity的相似点与不同点

在 Cesium1.95 中，Primitive和Entity是两种创建和管理三维对象的核心方式，它们在功能上有相似之处，但设计目标和使用场景差异明显。以下是详细对比：一、相似点​​1、基础渲染目标​​两者均用于在 3D 场景中绘制图形（点、线、面、模型等）。最终都会通过底层 WebGL 渲染管线生成可视化效果 。​​2、支持动态属性​​均支持随时间变化的属性（如位置移动、颜色渐变）。二、核心差异​​维度​​​​Primitive​​​​Entity​​​​设计定位​​底层图形 API（面向 GPU 优化）高级数据 API（面向业务逻辑）​​灵活性​​直接控制几何体/材质，支持复杂渲染封装底层细节，API 简单易用​​性能表现​​高频渲染场景更优（如 10W+ 静态模型）动态更新时开销较大​​代码复杂度​​需处理几何实例、着色器等细节声明式配置，无需关注底层实现​​动态更新​​更新需重构整个 Primitive直接修改属性（如entity.position）三、性能关键差异详解​​1、渲染机制​​Primitive​​：通过合并几何实例（GeometryInstance）减少 Draw Call，适合​​静态/批量数据​​。例如：// 10W 个盒子实例合并渲染 const instances = positions.map(pos = new Cesium.GeometryInstance({ geometry: boxGeometry, modelMatrix: Cesium.Matrix4.fromTranslation(pos) })); viewer.scene.primitives.add(new Cesium.Primitive({ geometryInstances: instances, appearance: new Cesium.PerInstanceColorAppearance() }));​Entity​​：每个实体独立生成 Primitive，​​大量实体时 GPU 压力剧增​​。2、内存与更新效率​​Primitive​​：静态数据内存占用低，但动态更新需重建几何。​​Entity​​：属性绑定（如 CallbackProperty）灵活，适合​​频繁交互​​的场景（如移动车辆）。四、适用场景建议​​场景​​​​推荐 API​​​​原因​​静态大规模模型（如城市建筑）Primitive合并渲染降低 CPU/GPU 开销动态对象（如飞机、车辆轨迹）Entity属性更新便捷，支持交互（点击弹窗、路径动画）自定义着色器效果（如热力图）Primitive直接操控材质与 GLSL 着色器快速原型开发Entity简化代码（如viewer.entities.add({ point: { ... } })）五、Entity实例1、画点const point = viewer.entities.add({ position: Cesium.Cartesian3.fromDegrees(116.391, 39.904, 0), point: { pixelSize: 100, color: Cesium.Color.RED, }, }); viewer.flyTo(point);2、添加文本new Cesium.LabelGraphics(options)NameTypeAttributesDefaultDescriptionshowProperty|booleanoptionaltrue是否显示标签。textProperty|stringoptional标签显示的文本内容，唯一的「逻辑必填项」，未配置时标签不会显示fontProperty|stringoptional'30px sans-serif'字体样式，格式与 CSS font 属性一致（如 '24px Arial'）。styleProperty|LabelStyleoptionalLabelStyle.FILL文本样式，可选值：- LabelStyle.FILL（仅填充）- LabelStyle.OUTLINE（仅描边）- LabelStyle.FILL_AND_OUTLINE（填充+描边）。scaleProperty|numberoptional1.0整体缩放比例。showBackgroundProperty|booleanoptionalfalseA boolean Property specifying the visibility of the background behind the label.backgroundColorProperty|Coloroptionalnew Color(0.165, 0.165, 0.165, 0.8)A Property specifying the backgroundColor.backgroundPaddingProperty|Cartesian2optionalnew Cartesian2(7, 5)ACartesian2Property specifying the horizontal and vertical background padding in pixels.pixelOffsetProperty|Cartesian2optionalCartesian2.ZERO标签相对于其锚点的屏幕空间偏移量（像素）。Cartesian2(x, y)中，x 为正向右偏移，y 为正向上偏移。eyeOffsetProperty|Cartesian3optionalCartesian3.ZEROACartesian3Property specifying the eye offset.horizontalOriginProperty|HorizontalOriginoptionalHorizontalOrigin.CENTER标签的水平对齐方式，相对于锚点：HorizontalOrigin.LEFT: 左对齐HorizontalOrigin.CENTER: 居中对齐HorizontalOrigin.RIGHT: 右对齐verticalOriginProperty|VerticalOriginoptionalVerticalOrigin.CENTER标签的垂直对齐方式，相对于锚点：VerticalOrigin.TOP: 顶部对齐VerticalOrigin.CENTER: 居中对齐VerticalOrigin.BOTTOM: 底部对齐VerticalOrigin.BASELINE: 基线对齐（文本基线，如字母 x 的底部）heightReferenceProperty|HeightReferenceoptionalHeightReference.NONE高度参考系：- NONE：绝对高度（默认）- CLAMP_TO_GROUND：贴地- RELATIVE_TO_GROUND：相对地面高度。CLAMP_TO_GROUND 时，eyeOffset 可能失效，建议用 pixelOffset 调整位置；fillColorProperty|ColoroptionalColor.WHITE文本填充颜色（如 Cesium.Color.RED）。outlineColorProperty|ColoroptionalColor.BLACK文本描边颜色。outlineWidthProperty|numberoptional1.0描边宽度（像素）。translucencyByDistanceProperty|NearFarScalaroptional根据相机距离设置标签的透明度。格式：NearFarScalar(near, nearValue, far, farValue)，其中 near和 far是相机到标签的距离（米），nearValue和 farValue是对应的透明度（0~1）。pixelOffsetScaleByDistanceProperty|NearFarScalaroptional根据相机距离缩放 pixelOffset，pixelOffsetScaleByDistance: new Cesium.NearFarScalar(100, 1.0, 1000, 0.5)（1000 米外偏移缩小 50%）scaleByDistanceProperty|NearFarScalaroptional根据距离调整缩放（如 new Cesium.NearFarScalar(1000, 1.0, 5000, 0.5)）。distanceDisplayConditionProperty|DistanceDisplayConditionoptional控制标签在哪个距离范围内显示。格式：DistanceDisplayCondition(minimumDistance, maximumDistance)（米）。disableDepthTestDistanceProperty|numberoptional禁用深度测试的距离（米）。当相机距离小于此值时，标签将始终绘制在其他物体之上（避免被地形/模型遮挡）。设为 Number.POSITIVE_INFINITY可完全禁用深度测试。注意事项必填属性：text 是唯一的「逻辑必填项」，未配置时标签不会显示；动态属性：所有属性支持 CallbackProperty 实现实时更新，例如：深度测试：设置 disableDepthTestDistance: Number.POSITIVE_INFINITY 可避免标签被地形 / 模型遮挡；贴地标签：heightReference: CLAMP_TO_GROUND 时，eyeOffset 可能失效，建议用 pixelOffset 调整位置；性能优化：大量标签时，合理设置 distanceDisplayCondition 可减少渲染压力。// 动态更新标签文本 text: new Cesium.CallbackProperty(() = { return `当前时间：${new Date().toLocaleTimeString()}`; }, false)// 使用 viewer.entities.add() 添加一个带有文本的实体 const entity = viewer.entities.add({ name: "示例文本标签", // 可选，用于标识该实体 position: Cesium.Cartesian3.fromDegrees(116.391, 39.904, 0), // 北京天安门附近的经纬度 label: { text: "你好，Cesium!", // 要显示的文本内容 font: "14px sans-serif", // 字体样式 fillColor: Cesium.Color.WHITE, // 文本颜色 outlineColor: Cesium.Color.BLACK, // 文本轮廓颜色 outlineWidth: 2, // 轮廓宽度 style: Cesium.LabelStyle.FILL_AND_OUTLINE, // 填充和轮廓样式 verticalOrigin: Cesium.VerticalOrigin.BOTTOM, // 垂直对齐方式 horizontalOrigin: Cesium.HorizontalOrigin.CENTER, // 水平对齐方式 pixelOffset: new Cesium.Cartesian2(0, -10), // 像素偏移，用于调整位置 heightReference: Cesium.HeightReference.RELATIVE_TO_GROUND, distanceDisplayCondition: new Cesium.DistanceDisplayCondition(100, 50000), disableDepthTestDistance: Number.POSITIVE_INFINITY // 强制始终显示，不受深度测试影响 }, }); viewer.zoomTo(entity);3、添加线new Cesium.PolylineGraphics(options)NameTypeAttributesDefaultDescriptionshowProperty|booleanoptionaltrueA boolean Property specifying the visibility of the polyline.positionsProperty|Array.Cartesian3optionalA Property specifying the array ofCartesian3positions that define the line strip.widthProperty|numberoptional1.0A numeric Property specifying the width in pixels.granularityProperty|numberoptionalCesium.Math.RADIANS_PER_DEGREEA numeric Property specifying the angular distance between each latitude and longitude if arcType is not ArcType.NONE.material