new LabelCollection(optionsopt)
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
Example labels
Labels are added and removed from the collection using
LabelCollection#add
and LabelCollection#remove
.
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
<optional> |
Object with the following properties:
Properties
|
- Source:
- See:
Example
// Create a label collection with two labels
var 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'
});
Members
debugShowBoundingVolume :Boolean
This property is for debugging only; it is not for production use nor is it optimized.
Draws the bounding sphere for each draw command in the primitive.
Type:
- Boolean
- Default Value:
- false
- Source:
length :Number
Returns the number of labels in this collection. This is commonly used with
LabelCollection#get
to iterate over all the labels
in the collection.
Type:
- Number
- Source:
modelMatrix :Matrix4
The 4x4 transformation matrix that transforms each label in this collection from model to world coordinates.
When this is the identity matrix, the labels are drawn in world coordinates, i.e., Earth's WGS84 coordinates.
Local reference frames can be used by providing a different transformation matrix, like that returned
by
Transforms.eastNorthUpToFixedFrame
.
Type:
- Default Value:
- Source:
Example
var 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'
});
Methods
add(optionsopt) → {Label}
Creates and adds a label with the specified initial properties to the collection.
The added label is returned so it can be modified or removed from the collection later.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
options |
Object |
<optional> |
A template describing the label's properties as shown in Example 1. |
Throws:
-
This object was destroyed, i.e., destroy() was called.
- Type
- DeveloperError
Returns:
The label that was added to the collection.
- Type
- Label
Examples
// Example 1: Add a label, specifying all the default values.
var l = labels.add({
show : true,
position : Cesium.Cartesian3.ZERO,
text : '',
font : '30px sans-serif',
fillColor : Cesium.Color.WHITE,
outlineColor : Cesium.Color.BLACK,
style : Cesium.LabelStyle.FILL,
pixelOffset : Cesium.Cartesian2.ZERO,
eyeOffset : Cesium.Cartesian3.ZERO,
horizontalOrigin : Cesium.HorizontalOrigin.LEFT,
verticalOrigin : Cesium.VerticalOrigin.BOTTOM,
scale : 1.0
});
// Example 2: Specify only the label's cartographic position,
// text, and font.
var l = labels.add({
position : Cesium.Cartesian3.fromRadians(longitude, latitude, height),
text : 'Hello World',
font : '24px Helvetica',
});
contains(label) → {Boolean}
Check whether this collection contains a given label.
Parameters:
Name | Type | Description |
---|---|---|
label |
Label | The label to check for. |
- Source:
- See:
Returns:
true if this collection contains the label, false otherwise.
- Type
- Boolean
destroy() → {undefined}
Destroys the WebGL resources held by this object. Destroying an object allows for deterministic
release of WebGL resources, instead of relying on the garbage collector to destroy this object.
Once an object is destroyed, it should not be used; calling any function other than
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.
- Source:
- See:
Throws:
-
This object was destroyed, i.e., destroy() was called.
- Type
- DeveloperError
Returns:
- Type
- undefined
Example
labels = labels && labels.destroy();
get(index) → {Label}
Returns the label in the collection at the specified index. Indices are zero-based
and increase as labels are added. Removing a label shifts all labels after
it to the left, changing their indices. This function is commonly used with
LabelCollection#length
to iterate over all the labels
in the collection.
Parameters:
Name | Type | Description |
---|---|---|
index |
Number | The zero-based index of the billboard. |
- Source:
- See:
Throws:
-
This object was destroyed, i.e., destroy() was called.
- Type
- DeveloperError
Returns:
The label at the specified index.
- Type
- Label
Example
// Toggle the show property of every label in the collection
var len = labels.length;
for (var i = 0; i < len; ++i) {
var l = billboards.get(i);
l.show = !l.show;
}
isDestroyed() → {Boolean}
Returns true if this object was destroyed; otherwise, false.
If this object was destroyed, it should not be used; calling any function other than
If this object was destroyed, it should not be used; calling any function other than
isDestroyed
will result in a DeveloperError
exception.
- Source:
- See:
Returns:
True if this object was destroyed; otherwise, false.
- Type
- Boolean
remove(label) → {Boolean}
Removes a label from the collection. Once removed, a label is no longer usable.
Parameters:
Name | Type | Description |
---|---|---|
label |
Label | The label to remove. |
- Source:
- See:
Throws:
-
This object was destroyed, i.e., destroy() was called.
- Type
- DeveloperError
Returns:
true
if the label was removed; false
if the label was not found in the collection.
- Type
- Boolean
Example
var l = labels.add(...);
labels.remove(l); // Returns true
removeAll()
Removes all labels from the collection.
Throws:
-
This object was destroyed, i.e., destroy() was called.
- Type
- DeveloperError
Example
labels.add(...);
labels.add(...);
labels.removeAll();