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:
|
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:
See:
Members
blendOption : BlendOption
-
Default Value:
BlendOption.OPAQUE_AND_TRANSLUCENT
Draws the bounding sphere for each draw command in the primitive.
-
Default Value:
false
LabelCollection#get
to iterate over all the labels
in the collection.
modelMatrix : Matrix4
Transforms.eastNorthUpToFixedFrame
.
-
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
Methods
add(options) → Label
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
.
Name | Type | Description |
---|---|---|
options |
Object | optional A template describing the label's properties as shown in Example 1. |
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:
Name | Type | Description |
---|---|---|
label |
Label | The label to check for. |
Returns:
See:
Once an object is destroyed, it should not be used; calling any function other than
isDestroyed
will result in a DeveloperError
exception. Therefore,
assign the return value (undefined
) to the object as done in the example.
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
labels = labels && labels.destroy();
See:
get(index) → Label
LabelCollection#length
to iterate over all the labels
in the collection.
Performance:
Expected constant time. If labels were removed from the collection and
Scene#render
was not called, an implicit O(n)
operation is performed.
Name | Type | Description |
---|---|---|
index |
Number | The zero-based index of the billboard. |
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:
If this object was destroyed, it should not be used; calling any function other than
isDestroyed
will result in a DeveloperError
exception.
Returns:
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.
Name | Type | Description |
---|---|---|
label |
Label | The label to remove. |
Returns:
true
if the label was removed; false
if the label was not found in the collection.
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
const l = labels.add(...);
labels.remove(l); // Returns true
See:
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();