首页 / Cesium / API 文档

ClassificationPrimitive

先看结论

分类图元。它不新增可见几何，而是把几何覆盖范围内的地形或 3D Tiles 重新着色，常用于建筑占地染色、水面覆盖层、区域高亮。

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

new Cesium.ClassificationPrimitive(options)

参数

参数	默认	说明
`geometry`	—	单个 `Geometry`，与 `geometryInstances` 二选一
`geometryInstances`	—	`GeometryInstance` 或数组
`appearance`	—	必须是无光照的 `PerInstanceColorAppearance`，实例自带时可省略
`asynchronous`	true	是否在 Web Worker 中生成顶点
`classificationType`	ClassificationType.BOTH	TERRAIN / CESIUM_3D_TILE / BOTH

成员与方法

成员	说明
`ready`	顶点数据构建完成前为 false
`readyPromise`	构建完成时 resolve
`show`	显隐，默认 true
`classificationType`	作用对象，可运行时修改
`geometryInstances`	已提交的实例
`ClassificationPrimitive.isSupported(scene)`	静态方法，判断设备是否支持分类
`destroy()` / `isDestroyed()`	释放资源

示例

var polygon = new Cesium.PolygonGeometry({
  polygonHierarchy: new Cesium.PolygonHierarchy(
    Cesium.Cartesian3.fromDegreesArray([
      121.40, 31.20,
      121.52, 31.20,
      121.52, 31.28,
      121.40, 31.28
    ])
  ),
  height: 0,
  vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
});

var primitive = new Cesium.ClassificationPrimitive({
  geometryInstances: new Cesium.GeometryInstance({
    geometry: polygon,
    attributes: {
      color: Cesium.ColorGeometryInstanceAttribute.fromColor(
        Cesium.Color.fromCssColorString('#e8f4ff').withAlpha(0.55)
      )
    }
  }),
  appearance: new Cesium.PerInstanceColorAppearance({
    flat: true,
    translucent: true
  }),
  classificationType: Cesium.ClassificationType.TERRAIN
});

viewer.scene.primitives.add(primitive);

外观必须无光照

分类是改写已有表面的颜色，不参与自己的光照计算。给 PerInstanceColorAppearance 设置 flat: true 并把 closed 保持为 false，能得到最稳定的结果。使用 MaterialAppearance 或开启光照会让颜色偏暗甚至完全不显示。

高度与范围

几何的 height 应贴住地面，extrudedHeight 用于把分类范围做成柱体，从而覆盖建筑立面。只分类地形时，把 classificationType 设为 TERRAIN 可以避免误改 3D Tiles 模型。

分类不会改变拾取结果。scene.pick 命中的仍是原始地形或模型，颜色只是渲染阶段的覆盖。要在点击时识别分类区域，得自己用几何范围做空间判断。

引用本文

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