cesium entity polygon 完整属性指南属性分类属性名类型/选项描述默认值/常用值几何与位置

属性分类	属性名	类型/选项	描述	默认值/常用值
几何与位置	`hierarchy`	`Cesium.PolygonHierarchy`	【必需】定义多边形的顶点坐标和内部孔洞（holes）的层次结构。	`new Cesium.PolygonHierarchy(positions, holes)`
	`height`	`number`	多边形相对于椭球面的基准高度（米）。	`0`
	`extrudedHeight`	`number`	多边形的挤压高度（米），设置后多边形会变为3D立体形状。	-
	`perPositionHeight`	`boolean`	是否使用 `hierarchy` 中每个点自身的海拔高度。为 `true` 时可创建倾斜平面。	`false`
	`granularity`	`number`	指定经纬度点之间的角度距离（弧度），用于控制曲面上多边形的细分程度。	`Cesium.Math.RADIANS_PER_DEGREE`
	`stRotation`	`number`	多边形纹理的旋转角度（弧度），不影响几何形状。	`0`
外观与材质	`material`	`Cesium.Color` \ `Cesium.MaterialProperty` \ `String` (图片URL)	多边形的填充材质。	`Cesium.Color.WHITE`
	`fill`	`boolean`	是否填充多边形。	`true`
	`outline`	`boolean`	是否显示轮廓线。	`false`
	`outlineColor`	`Cesium.Color`	轮廓线的颜色。	`Cesium.Color.BLACK`
	`outlineWidth`	`number`	轮廓线的宽度（像素），注意：通常被限制为1.0。	`1.0`
显示与行为	`show`	`boolean`	控制整个多边形实体是否显示。	`true`
	`distanceDisplayCondition`	`Cesium.DistanceDisplayCondition`	根据与相机的距离条件显示/隐藏多边形。	-
	`classificationType`	`Cesium.ClassificationType.TERRAIN` \ `CESIUM_3D_TILE` \ `BOTH`	指定多边形与地形或3D Tiles的相互作用方式。	`Cesium.ClassificationType.BOTH`
	`arcType`	`Cesium.ArcType.GEODESIC` \ `Cesium.ArcType.RHUMB`	指定多边形边缘的线型（测地线或恒向线）。	`Cesium.ArcType.GEODESIC`
	`zIndex`	`number`	指定用于排序地面几何图形的zIndex。仅在多边形为常数且未指定height或extrudedHeight时才有效。	`0`
高度参考	`heightReference`	`Cesium.HeightReference.NONE` \ `CLAMP_TO_GROUND` \ `RELATIVE_TO_GROUND`	`height` 的参考基准。	`Cesium.HeightReference.NONE`
	`extrudedHeightReference`	`Cesium.HeightReference.NONE` \ `CLAMP_TO_GROUND` \ `RELATIVE_TO_GROUND`	`extrudedHeight` 的参考基准。	`Cesium.HeightReference.NONE`
挤压体选项	`closeTop`	`boolean`	当有挤压高度时，是否关闭挤压体的顶部。	`true`
	`closeBottom`	`boolean`	当有挤压高度时，是否关闭挤压体的底部。	`true`
阴影	`shadows`	`Cesium.ShadowMode.DISABLED` \ `ENABLED` \ `CAST_ONLY` \ `RECEIVE_ONLY`	指定多边形是否投射或接收阴影。	`Cesium.ShadowMode.DISABLED`

基本用法与代码示例

创建一个简单的多边形实体并添加到 Viewer 中：

// 创建 Viewer 实例
const viewer = new Cesium.Viewer('cesiumContainer');

// 添加一个多边形实体
const polygonEntity = viewer.entities.add({
  name: '我的多边形',
  polygon: {
    hierarchy: new Cesium.PolygonHierarchy(
      Cesium.Cartesian3.fromDegreesArray([
        -107.0, 27.0, // 顶点1 经度, 纬度
        -107.0, 22.0, // 顶点2
        -102.0, 23.0, // 顶点3
        -97.0, 21.0,  // 顶点4
        -97.0, 25.0   // 顶点5
      ])
    ),
    material: Cesium.Color.RED.withAlpha(0.5), // 半透明红色填充
    outline: true, // 显示轮廓
    outlineColor: Cesium.Color.WHITE, // 白色轮廓
    height: 0, // 基准高度
    extrudedHeight: 100000.0, // 挤压高度，形成3D形状
    heightReference: Cesium.HeightReference.RELATIVE_TO_GROUND, // 高度基准
  }
});

// 飞行到多边形
viewer.zoomTo(viewer.entities);

创建一个带孔洞的复杂多边形

// 定义外部多边形轮廓的顶点
var outerRing = Cesium.Cartesian3.fromDegreesArray([
  -90.0, 30.0,
  -60.0, 30.0,
  -60.0, 40.0,
  -90.0, 40.0
]);

// 定义内部孔洞的顶点
var innerRing = Cesium.Cartesian3.fromDegreesArray([
  -85.0, 32.0,
  -83.0, 32.0,
  -83.0, 38.0,
  -85.0, 38.0
]);

// 创建多边形层次结构，包含外部轮廓和内部孔洞
var hierarchy = new Cesium.PolygonHierarchy(outerRing, [innerRing]);

// 添加带孔洞的多边形实体
var polygonWithHole = viewer.entities.add({
  polygon: {
    hierarchy: hierarchy,
    material: Cesium.Color.BLUE.withAlpha(0.5),
    outline: true,
    outlineColor: Cesium.Color.BLACK,
    height: 1000, // 抬升高度，使多边形高于地面
    extrudedHeight: 5000.0, // 挤压高度，形成3D盒子
  }
});

实用技巧和注意事项

hierarchy 的创建：hierarchy 是定义多边形形状的核心，使用 new Cesium.PolygonHierarchy(positions, holes) 创建，其中 positions 是定义多边形外部环的 Cartesian3 数组，holes 是（可选的）一个或多个内部环（孔洞）的 PolygonHierarchy 数组1。
轮廓线宽度限制：由于 WebGL 的技术限制，outlineWidth 大于 1.0 通常不会生效，在所有硬件上都可能显示为 1 像素宽。
性能考量：对于大量静态或需要极高性能的多边形，考虑使用 Primitive API 或 GroundPrimitive（用于贴地图形）。Entity API 更易于使用，但抽象层次更高，对于超大规模数据，Primitive API 通常能提供更好的控制性和性能。
多边形有效性：确保多边形的顶点坐标是有效的（例如，不自相交），否则可能无法正确渲染1。
perPositionHeight 的使用：当需要创建不规则或倾斜的多边形表面时（例如模拟地形起伏），将 perPositionHeight 设置为 true，并为 hierarchy 中的每个点提供不同的高度值（Z坐标）

处理轮廓（Outline）在 terrain 上不显示的问题

当你在地形上绘制多边形时，可能会遇到轮廓（outline）不显示的情况，并可能在控制台看到类似警告："Entity geometry outlines are unsupported on terrain. Outlines will be disabled. To enable outlines, disable geometry terrain clamping by explicitly setting height to 0."

解决方法是显式地将 height 设置为 0（即使默认值是0，也需要明确设置），并将 heightReference 设置为 Cesium.HeightReference.NONE（同样，即使这是默认值）。这实际上是告诉 Cesium 不要将几何图形 clamping 到地形上，从而允许轮廓线正常显示

polygon: {
  hierarchy: ...,
  material: ...,
  outline: true,
  outlineColor: Cesium.Color.WHITE,
  height: 0, // 明确设置 height 为 0
  heightReference: Cesium.HeightReference.NONE // 明确设置 heightReference
}