Cesium快速入门15：图元Primitive创建图像物体

前面我们一直用 Entity——也就是“实体”——画矩形、椭球、走廊、圆柱、多边形、球体等等。Entity 把底层细节包得严严实实，一两行代码就能出效果。
可如果想再“底层”一点，自己捏顶点、配材质、写外观，那就得请出今天的主角：Primitive（图元）。
思路跟 Three.js 很像：先造几何体 → 再搞实例 → 再给外观 → 最后扔进场景。
步骤多了，但自由度直接拉满，后面甚至能自己写着色器做烟雾、流体等特效。

下面咱们把“ Entity 画矩形”快速复习一遍，然后再用 Primitive 一模一样地复现它，每一步都拆开讲透。

一、Entity 版：两行代码画矩形

需求：在地球上贴两张“完全贴地”的矩形，红色半透明。

// 1. 直接调实体接口 const redRect = viewer.entities.add({ rectangle: { // 西南角 + 东北角 两个点定矩形 coordinates: Cesium.Rectangle.fromDegrees(113.3, 23.0, 113.4, 23.2), material: Cesium.Color.RED.withAlpha(0.5) // 红色半透明 } });

完事儿！简单，但黑盒。

二、Primitive 版：五步走，每一步都能改

我们把上面同样的矩形，用 Primitive 手敲一遍，看看底层到底干了啥。

【第 1 步】造几何体（Geometry）
告诉 Cesium：顶点怎么摆、要不要挤出高度、顶点格式用哪种。

/* 1. 创建矩形几何体 */ const rectGeom = new Cesium.RectangleGeometry({ rectangle: Cesium.Rectangle.fromDegrees(113.3, 23.0, 113.4, 23.2), // 贴地区域 height: 0, // 离地 0 米——贴地 extrudedHeight: 500, // 向上挤出 500 米，形成“盒子” vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT // 顶点格式：只保留“位置+颜色”属性，省内存，后面用实例颜色 });

小贴士

• extrudedHeight大于height时，矩形会被“挤”成盒子。

• vertexFormat决定每个顶点携带哪些属性（法线、UV、颜色等）。这里选“实例颜色”专用格式，省得带一堆用不到的数据。

【第 2 步】包成实例（GeometryInstance）
几何体是“模具”，实例才是“实物”。一个模具可以批量生产无数个实物，每个实物还能刷不同颜色。

/* 2. 创建几何实例，并给它刷颜色 */ const instance = new Cesium.GeometryInstance({ geometry: rectGeom, // 上面做的模具 attributes: { // 实例颜色属性：绿色半透明 color: Cesium.ColorGeometryInstanceAttribute.fromColor( Cesium.Color.GREEN.withAlpha(0.5)) } });

注意：
Cesium.ColorGeometryInstanceAttribute.fromColor是把普通颜色对象转成“实例属性”专用格式，别直接扔裸颜色进去。

【第 3 步】配外观（Appearance）
外观 = 材质 + 着色器 + 渲染状态。这里我们选“实例颜色外观”，意思是“颜色直接用实例里刷好的，不再贴纹理”。

/* 3. 定义外观（材质） */ const appearance = new Cesium.PerInstanceColorAppearance({ flat: true, // 关闭光照，颜色纯纯的，不受太阳角度影响 translucent: true // 允许半透明，方便看底层地形 });

【第 4 步】创建图元（Primitive）
把“实例”和“外观”合并成真正可渲染的“图元”。

/* 4. 生成图元（类似 Three.js 的 Mesh） */ const rectPrimitive = new Cesium.Primitive({ geometryInstances: instance, // 实物 appearance: appearance // 外观 });

【第 5 步】扔进场景

/* 5. 加入场景 */ viewer.scene.primitives.add(rectPrimitive);

三、小结：Entity vs Primitive

• Entity：封装厚，代码少，适合快速出活。

• Primitive：步骤多，粒度高，适合“想怎么画就怎么画”——顶点、索引、着色器、渲染状态全由你定。
  今天先开个头，后面我们拿 Primitive 写自定义着色器，做烟雾、水流、建筑生长动画，再慢慢感受它的威力。