首页 / Cesium / API 文档

GroundPrimitive

先看结论

把几何体贴到地形表面绘制。与普通 Primitive 的区别是顶点高度会被地形覆盖，且能跨越地形与 3D Tiles 做深度贴合。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-29 · 引用本文

new Cesium.GroundPrimitive(options)

参数

参数	默认	说明
`geometry`	—	单个 `Geometry`
`geometryInstances`	—	`GeometryInstance` 或数组，与 `geometry` 二选一
`appearance`	—	外观对象；每个实例自带 appearance 时可省略
`asynchronous`	true	是否在 Web Worker 中创建顶点数据
`classificationType`	ClassificationType.BOTH	影响地形、3D Tiles 或两者

成员与方法

成员	说明
`ready`	异步构建完成前为 false
`readyPromise`	构建完成时 resolve 的 Promise
`show`	显隐开关，默认 true
`classificationType`	分类目标，可在运行时改写
`geometryInstances`	提交的实例或实例数组
`debugShowBoundingVolume`	绘制包围体，排查显示不出的问题
`GroundPrimitive.isSupported(scene)`	静态方法，判断当前环境是否支持贴地
`GroundPrimitive.supportsMaterials(scene)`	静态方法，判断是否支持材质贴地
`destroy()` / `isDestroyed()`	释放 GPU 资源

最小示例

if (!Cesium.GroundPrimitive.isSupported(viewer.scene)) {
  throw new Error('当前设备不支持贴地图元');
}

var instance = new Cesium.GeometryInstance({
  geometry: new Cesium.PolygonGeometry({
    polygonHierarchy: new Cesium.PolygonHierarchy(
      Cesium.Cartesian3.fromDegreesArray([
        116.30, 39.86,
        116.48, 39.86,
        116.48, 40.00,
        116.30, 40.00
      ])
    ),
    vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  attributes: {
    color: Cesium.ColorGeometryInstanceAttribute.fromColor(
      Cesium.Color.fromCssColorString('#2f7cd6').withAlpha(0.7)
    )
  }
});

var primitive = new Cesium.GroundPrimitive({
  geometryInstances: instance,
  appearance: new Cesium.PerInstanceColorAppearance({
    flat: true,
    translucent: true
  }),
  classificationType: Cesium.ClassificationType.TERRAIN
});

viewer.scene.primitives.add(primitive);

与 ClassificationPrimitive 的区别

GroundPrimitive 在贴地的同时保留几何自身的颜色与外观，呈现的是一块「印在地形上的图形」；ClassificationPrimitive 则改写地形本身的着色，用于把建筑占地范围染成另一种颜色并让地形参与光照。两者都用 classificationType 控制作用对象，但前者可带材质，后者只能着色。

不支持的几何

不支持拉伸体：extrudedHeight 大于 0 的多边形贴地后会被忽略。
不支持 PolylineGeometry，贴地线请用 PolylineGraphics 的 clampToGround。
需要在支持深度纹理的 WebGL 环境运行，isSupported 为 false 时整个图元不显示。

贴地图元与地形加载顺序有关。地形瓦片尚未加载时，贴地图元会画在椭球面上，瓦片到达后跳变到真实高度。需要稳定效果时，等 viewer.scene.globe.tileLoadProgressEvent 归零后再添加。

引用本文

经纬志（2026）。《GroundPrimitive》。https://www.jingweizhi.com/cesium/api/ground-primitive.html（访问日期 2026-11-03）。