LabelCollection

new Cesium.LabelCollection(options)

engine/Source/Scene/LabelCollection.js 623

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 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 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) 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