cesium entity rectangle 完整属性指南

属性分类	属性名	类型/选项	描述	默认值/常用值
几何与位置	coordinates	Cesium.Rectangle	【必需】  矩形的地理边界（西经、南纬、东经、北纬，单位是弧度）	Cesium.Rectangle.fromDegrees(west, south, east, north)
	height	number	矩形相对于椭球面的基准高度（米）	0
	extrudedHeight	number	矩形的挤压高度（米），设置后矩形会变为3D立体盒子	-
	rotation	number	矩形绕其中心点逆时针旋转的角度（弧度）	0
	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
高度参考	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

基本用法与代码示例

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

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

// 添加一个矩形实体
const rectangleEntity = viewer.entities.add({
  name: '我的矩形',
  rectangle: {
    coordinates: Cesium.Rectangle.fromDegrees(100.0, 20.0, 110.0, 30.0), // 西, 南, 东, 北（单位：度）
    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);

实用技巧和注意事项

• coordinates 的便捷创建：除了使用 Cesium.Rectangle.fromDegrees（传入度数），你也可以直接使用 new Cesium.Rectangle(west, south, east, north)，但此时参数是弧度。
• rotation 的旋转中心：rotation 属性是绕矩形中心点旋转的1。如果你需要以其他点（如某个顶点）为原点进行旋转，可能需要通过计算顶点坐标并使用 Polygon 来实现。
• 轮廓线宽度限制：由于 WebGL 的技术限制，outlineWidth 大于 1.0 通常不会生效，在所有硬件上都可能显示为 1 像素宽。
• 坐标顺序与矩形有效性：确保 coordinates 的西经（west）小于东经（east），南纬（south）小于北纬（north），否则矩形可能无法正确渲染或会覆盖整个地球。
• 性能考量：对于大量静态或需要极高性能的矩形，考虑使用 Primitive API 或 GroundPrimitive（用于贴地图形）。Entity API 更易于使用，但抽象层次更高，对于超大规模数据，Primitive API 通常能提供更好的控制性和性能。

处理轮廓（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 到地形上，从而允许轮廓线正常显示。

rectangle: {
  coordinates: Cesium.Rectangle.fromDegrees(...),
  material: ...,
  outline: true,
  outlineColor: Cesium.Color.WHITE,
  height: 0, // 明确设置 height 为 0
  heightReference: Cesium.HeightReference.NONE // 明确设置 heightReference
}