LabelCollection

new Cesium.LabelCollection(options)

engine/Source/Scene/LabelCollection.js 624

可渲染的标签集合。标签是位于 3D 场景中的与视口对齐的文本。每个标签可以有不同的字体、颜色、比例等。 A renderable collection of labels. Labels are viewport-aligned text positioned in the 3D scene. Each label can have a different font, color, scale, etc.

标签示例 Example labels

使用以下命令在集合中添加和删除标签 Labels are added and removed from the collection using LabelCollection#add and LabelCollection#remove.

性能： Performance:

为了获得最佳性能，最好选择几个集合，每个集合都有许多标签，而不是多个集合，每个集合只有几个标签。避免集合中某些标签每帧都会发生变化，而其他标签则不会；相反，为静态标签创建一个或多个集合，为动态标签创建一个或多个集合。 For best performance, prefer a few collections, each with many labels, to many collections with only a few labels each. Avoid having collections where some labels change every frame and others do not; instead, create one or more collections for static labels, and one or more collections for dynamic labels.

名称 Name	类型 Type	说明 Description
options	object	可选 optional 具有以下属性的对象： Object with the following properties: 名称 Name 类型 Type 默认值 Default 说明 Description modelMatrix Matrix4 Matrix4.IDENTITY 可选 optional 将每个标签从模型转换为世界坐标的 4x4 转换矩阵。 The 4x4 transformation matrix that transforms each label from model to world coordinates. debugShowBoundingVolume boolean false 可选 optional 仅用于调试。确定是否显示该图元的命令的边界球体。 For debugging only. Determines if this primitive's commands' bounding spheres are shown. scene Scene 可选 optional 必须传入使用高度参考属性的标签或将针对地球进行深度测试。 Must be passed in for labels that use the height reference property or will be depth tested against the globe. blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT 可选 optional 标签混合选项。默认值用于渲染不透明和半透明标签。但是，如果所有标签都完全不透明或全部完全半透明，则将技术设置为 BlendOption.OPAQUE 或 BlendOption.TRANSLUCENT 可以将性能提高多达 2 倍。 The label blending option. The default is used for rendering both opaque and translucent labels. However, if either all of the labels are completely opaque or all are completely translucent, setting the technique to BlendOption.OPAQUE or BlendOption.TRANSLUCENT can improve performance by up to 2x. show boolean true 可选 optional 确定是否显示集合中的标签。 Determines if the labels in the collection will be shown. coarseDepthTestDistance number 可选 optional 距相机的距离，超过该距离，标签将针对地球椭球体的近似值而不是针对完整的地球深度缓冲区进行深度测试。如果未指定，则默认值是相对于以下值确定的 The distance from the camera, beyond which, labels are depth-tested against an approximation of the globe ellipsoid rather than against the full globe depth buffer. If unspecified, the default value is determined relative to the value of Ellipsoid.default. threePointDepthTestDistance number 可选 optional 距相机的距离，在该距离内，用 The distance from the camera, within which, lables with a Label#heightReference 的价值 value of HeightReference.CLAMP_TO_GROUND or HeightReference.CLAMP_TO_TERRAIN 针对三个关键点进行深度测试。这确保了如果标签的任何关键点可见，则整个标签也将可见。如果未指定，则默认值是相对于以下值确定的 are depth tested against three key points. This ensures that if any key point of the label is visible, the whole label will be visible. If unspecified, the default value is determined relative to the value of Ellipsoid.default.

示例： Example:

// Create a label collection with two labels
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 Labels Demo

另见： 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) 并且还会产生 CPU 到 GPU 的开销。为了获得最佳性能，请在调用之前添加尽可能多的广告牌 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) 操作也会产生 CPU 到 GPU 的开销。为了获得最佳性能，请在调用之前删除尽可能多的标签 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