LabelCollection

new Cesium.LabelCollection(options)

engine/Source/Scene/LabelCollection.js 624

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

示例标签

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 包含以下属性的对象： 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:

// 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) and also incurs CPU to GPU overhead. For best performance, add as many billboards as possible before calling update.

Returns:

Throws:

• DeveloperError : 此对象已被销毁，即调用了 destroy()。

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 : 此对象已被销毁，即调用了 destroy()。

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 : 此对象已被销毁，即调用了 destroy()。

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 : 此对象已被销毁，即调用了 destroy()。

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 : 此对象已被销毁，即调用了 destroy()。

Example:

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

See:

• LabelCollection#add
• LabelCollection#remove