LabelCollection

new Cesium.LabelCollection(options)

engine/Source/Scene/LabelCollection.js 618

可渲染的标签集合。标签是场景中视口对齐的文本。 每个标签可以有不同的字体、颜色、缩放等。

标签示例

使用 LabelCollection#add 和 LabelCollection#remove 来添加和移除标签。

Performance:

为了获得最佳性能，建议使用少量集合，每个集合包含多个标签，而不是多个集合，每个集合只有少量标签。避免集合中的某些标签每帧都更改而其他标签不更改；相反，为静态标签创建一个或多个集合，为动态标签创建一个或多个集合。

Name	Type	Description
options	object	optional 包含以下属性的对象： Name Type Default Description modelMatrix Matrix4 Matrix4.IDENTITY optional 4x4 变换矩阵，将每个标签从模型坐标转换为世界坐标。 debugShowBoundingVolume boolean false optional 仅用于调试。确定是否显示此图元的命令边界球。 scene Scene optional 对于使用高度参考属性或将与地球进行深度测试的标签，必须传入此参数。 blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT optional 标签混合选项。默认值用于渲染不透明和半透明标签。但是，如果所有标签完全不透明或完全半透明，将技术设置为 BlendOption.OPAQUE 或 BlendOption.TRANSLUCENT 可以将性能提高多达 2 倍。 show boolean true optional 确定集合中的标签是否显示。 coarseDepthTestDistance number optional 与相机的距离，超过此距离后，标签将针对地球椭球的近似值进行深度测试，而不是针对完整的地球深度缓冲区。如果未指定，默认值将相对于 Ellipsoid.default 的值确定。 threePointDepthTestDistance number optional 与相机的距离，在此距离内，具有 Label#heightReference 值为 HeightReference.CLAMP_TO_GROUND 或 HeightReference.CLAMP_TO_TERRAIN 的标签将针对三个关键点进行深度测试。这确保如果标签的任何关键点可见，整个标签都将可见。如果未指定，默认值将相对于 Ellipsoid.default 的值确定。

Example:

// 创建包含两个标签的标签集合
const labels = scene.primitives.add(new Cesium.LabelCollection());
labels.add({
  position : new Cesium.Cartesian3(1.0, 2.0, 3.0),
  text : 'A label'
});
labels.add({
  position : new Cesium.Cartesian3(4.0, 5.0, 6.0),
  text : 'Another label'
});

Demo:

• Cesium Sandcastle 标签示例

See:

• LabelCollection#add
• LabelCollection#remove
• Label
• BillboardCollection

Members

Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

Default Value: false

Default Value: Matrix4.IDENTITY

Example:

const center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
labels.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
labels.add({
  position : new Cesium.Cartesian3(0.0, 0.0, 0.0),
  text     : 'Center'
});
labels.add({
  position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0),
  text     : 'East'
});
labels.add({
  position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0),
  text     : 'North'
});
labels.add({
  position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0),
  text     : 'Up'
});

Default Value: true

See:

• Billboards and Labels on Terrain Improvements

Methods

Performance:

Calling add is expected constant time. However, the collection's vertex buffer is rewritten; this operations is O(n) and also incurs CPU to GPU overhead. For best performance, add as many billboards as possible before calling update.

Returns:

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

Examples:

// Example 1:  Add a label, specifying all the default values.
const l = labels.add({
  show : true,
  position : Cesium.Cartesian3.ZERO,
  text : '',
  font : '30px sans-serif',
  fillColor : Cesium.Color.WHITE,
  outlineColor : Cesium.Color.BLACK,
  outlineWidth : 1.0,
  showBackground : false,
  backgroundColor : new Cesium.Color(0.165, 0.165, 0.165, 0.8),
  backgroundPadding : new Cesium.Cartesian2(7, 5),
  style : Cesium.LabelStyle.FILL,
  pixelOffset : Cesium.Cartesian2.ZERO,
  eyeOffset : Cesium.Cartesian3.ZERO,
  horizontalOrigin : Cesium.HorizontalOrigin.LEFT,
  verticalOrigin : Cesium.VerticalOrigin.BASELINE,
  scale : 1.0,
  translucencyByDistance : undefined,
  pixelOffsetScaleByDistance : undefined,
  heightReference : HeightReference.NONE,
  distanceDisplayCondition : undefined
});

// Example 2:  Specify only the label's cartographic position,
// text, and font.
const l = labels.add({
  position : Cesium.Cartesian3.fromRadians(longitude, latitude, height),
  text : 'Hello World',
  font : '24px Helvetica',
});

See:

• LabelCollection#remove
• LabelCollection#removeAll

Returns:

See:

• LabelCollection#get

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

Example:

labels = labels && labels.destroy();

See:

• LabelCollection#isDestroyed

Performance:

Expected constant time. If labels were removed from the collection and Scene#render was not called, an implicit O(n) operation is performed.

Returns:

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

Example:

// Toggle the show property of every label in the collection
const len = labels.length;
for (let i = 0; i < len; ++i) {
  const l = billboards.get(i);
  l.show = !l.show;
}

See:

• LabelCollection#length

Returns:

See:

• LabelCollection#destroy

Performance:

Calling remove is expected constant time. However, the collection's vertex buffer is rewritten - an O(n) operation that also incurs CPU to GPU overhead. For best performance, remove as many labels as possible before calling update. If you intend to temporarily hide a label, it is usually more efficient to call Label#show instead of removing and re-adding the label.

Returns:

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

Example:

const l = labels.add(...);
labels.remove(l);  // Returns true

See:

• LabelCollection#add
• LabelCollection#removeAll
• Label#show

Performance:

O(n). It is more efficient to remove all the labels from a collection and then add new ones than to create a new collection entirely.

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

Example:

labels.add(...);
labels.add(...);
labels.removeAll();

See:

• LabelCollection#add
• LabelCollection#remove