# 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

#### blendOption : BlendOption
engine/Source/Scene/LabelCollection.js 717

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.

Default Value: `BlendOption.OPAQUE_AND_TRANSLUCENT`

#### coarseDepthTestDistance : number
engine/Source/Scene/LabelCollection.js 781

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. When set to `0`, the approximate depth test is always applied. When set to `Number.POSITIVE_INFINITY`, the approximate depth test is never applied.
This setting only applies when a label's `Label#disableDepthTestDistance` value would otherwise allow depth testing—i.e., distance from the camera to the label is less than the label's `Label#disableDepthTestDistance` value.

#### debugShowBoundingVolume : boolean
engine/Source/Scene/LabelCollection.js 707

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.

Default Value: `false`

#### readonly length : number
engine/Source/Scene/LabelCollection.js 729

Returns the number of labels in this collection. This is commonly used with `LabelCollection#get` to iterate over all the labels in the collection.

#### modelMatrix : Matrix4
engine/Source/Scene/LabelCollection.js 695

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`.

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'
    });

#### show : boolean
engine/Source/Scene/LabelCollection.js 664

Determines if labels in this collection will be shown.

Default Value: `true`

#### threePointDepthTestDistance : number
engine/Source/Scene/LabelCollection.js 808

The distance from the camera, within which, labels 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. When set to `0`, this feature is disabled and portions of a label behind terrain be clipped.
This setting only applies when a labels's `Label#disableDepthTestDistance` value would otherwise allow depth testing—i.e., distance from the camera to the label is less than the labels's `Label#disableDepthTestDistance` value.

##### See:

- Billboards and Labels on Terrain Improvements

### Methods

#### add(options) → Label
engine/Source/Scene/LabelCollection.js 874

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.

##### 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` | Label.ConstructorOptions | optional A template describing the label's properties as shown in Example 1.

##### Returns:

The label that was added to the collection.

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

#### contains(label) → boolean
engine/Source/Scene/LabelCollection.js 954

Check whether this collection contains a given label.

Name | Type | Description
--- | --- | ---
`label` | Label | The label to check for.

##### Returns:

true if this collection contains the label, false otherwise.

##### See:

- LabelCollection#get

#### destroy()
engine/Source/Scene/LabelCollection.js 1082

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 `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:

- LabelCollection#isDestroyed

#### get(index) → Label
engine/Source/Scene/LabelCollection.js 986

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.

##### 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:

The label at the specified index.

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

#### isDestroyed() → boolean
engine/Source/Scene/LabelCollection.js 1062

Returns true if this object was destroyed; otherwise, false.
If this object was destroyed, it should not be used; calling any function other than `isDestroyed` will result in a `DeveloperError` exception.

##### Returns:

True if this object was destroyed; otherwise, false.

##### See:

- LabelCollection#destroy

#### remove(label) → boolean
engine/Source/Scene/LabelCollection.js 906

Removes a label from the collection. Once removed, a label is no longer usable.

##### 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:

- LabelCollection#add
- LabelCollection#removeAll
- Label#show

#### removeAll()
engine/Source/Scene/LabelCollection.js 935

Removes all labels from the collection.

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

Need help? The fastest way to get answers is from the community and team on the Cesium Forum.