# BillboardCollection

#### new Cesium.BillboardCollection(options)
engine/Source/Scene/BillboardCollection.js 148

A renderable collection of billboards. Billboards are viewport-aligned images positioned in the 3D scene.
Example billboards
Billboards are added and removed from the collection using `BillboardCollection#add` and `BillboardCollection#remove`. Billboards in a collection automatically share textures for images with the same identifier.

##### Performance:

For best performance, prefer a few collections, each with many billboards, to many collections with only a few billboards each. Organize collections so that billboards with the same update frequency are in the same collection, i.e., billboards that do not change should be in one collection; billboards that change every frame should be in another collection; and so on.

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 billboard 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 billboards that use the height reference property or will be depth tested against the globe.
`blendOption` | BlendOption | `BlendOption.OPAQUE_AND_TRANSLUCENT` | optional The billboard blending option. The default is used for rendering both opaque and translucent billboards. However, if either all of the billboards 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 billboards in the collection will be shown.
`coarseDepthTestDistance` | number |  | optional The distance from the camera, beyond which, billboards 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, billboards with a `Billboard#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 billboard is visible, the whole billboard will be visible. If unspecified, the default value is determined relative to the value of `Ellipsoid.default`.

##### Example:

    // Create a billboard collection with two billboards
    const billboards = scene.primitives.add(new Cesium.BillboardCollection());
    billboards.add({
      position : new Cesium.Cartesian3(1.0, 2.0, 3.0),
      image : 'url/to/image'
    });
    billboards.add({
      position : new Cesium.Cartesian3(4.0, 5.0, 6.0),
      image : 'url/to/another/image'
    });

##### Demo:

- Cesium Sandcastle Billboard Demo

##### See:

- BillboardCollection#add
- BillboardCollection#remove
- Billboard
- LabelCollection

### Members

#### blendOption : BlendOption
engine/Source/Scene/BillboardCollection.js 294

The billboard blending option. The default is used for rendering both opaque and translucent billboards. However, if either all of the billboards 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/BillboardCollection.js 482

The distance from the camera, beyond which, billboards 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 billboard's `Billboard#disableDepthTestDistance` value would otherwise allow depth testing—i.e., distance from the camera to the billboard is less than a billboard's `Billboard#disableDepthTestDistance` value.

#### debugShowBoundingVolume : boolean
engine/Source/Scene/BillboardCollection.js 272

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`

#### debugShowTextureAtlas : boolean
engine/Source/Scene/BillboardCollection.js 284

This property is for debugging only; it is not for production use nor is it optimized.

Draws the texture atlas for this BillboardCollection as a fullscreen quad.

Default Value: `false`

#### readonly length : number
engine/Source/Scene/BillboardCollection.js 368

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

#### modelMatrix : Matrix4
engine/Source/Scene/BillboardCollection.js 259

The 4x4 transformation matrix that transforms each billboard in this collection from model to world coordinates. When this is the identity matrix, the billboards 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);
    billboards.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
    billboards.add({
      image : 'url/to/image',
      position : new Cesium.Cartesian3(0.0, 0.0, 0.0) // center
    });
    billboards.add({
      image : 'url/to/image',
      position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0) // east
    });
    billboards.add({
      image : 'url/to/image',
      position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0) // north
    });
    billboards.add({
      image : 'url/to/image',
      position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0) // up
    });

##### See:

- Transforms.eastNorthUpToFixedFrame

#### show : boolean
engine/Source/Scene/BillboardCollection.js 225

Determines if billboards in this collection will be shown.

Default Value: `true`

#### threePointDepthTestDistance : number
engine/Source/Scene/BillboardCollection.js 508

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

##### See:

- Billboards and Labels on Terrain Improvements

### Methods

#### add(options) → Billboard
engine/Source/Scene/BillboardCollection.js 579

Creates and adds a billboard with the specified initial properties to the collection. The added billboard 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 - an `O(n)` operation that also incurs CPU to GPU overhead. For best performance, add as many billboards as possible before calling `update`.

Name | Type | Description
--- | --- | ---
`options` | Billboard.ConstructorOptions | optional A template describing the billboard's properties as shown in Example 1.

##### Returns:

The billboard that was added to the collection.

##### Throws:

- DeveloperError : This object was destroyed, i.e., destroy() was called.

##### Examples:

    // Example 1:  Add a billboard, specifying all the default values.
    const b = billboards.add({
      show : true,
      position : Cesium.Cartesian3.ZERO,
      pixelOffset : Cesium.Cartesian2.ZERO,
      eyeOffset : Cesium.Cartesian3.ZERO,
      heightReference : Cesium.HeightReference.NONE,
      horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
      verticalOrigin : Cesium.VerticalOrigin.CENTER,
      scale : 1.0,
      image : 'url/to/image',
      imageSubRegion : undefined,
      color : Cesium.Color.WHITE,
      id : undefined,
      rotation : 0.0,
      alignedAxis : Cesium.Cartesian3.ZERO,
      width : undefined,
      height : undefined,
      scaleByDistance : undefined,
      translucencyByDistance : undefined,
      pixelOffsetScaleByDistance : undefined,
      sizeInMeters : false,
      distanceDisplayCondition : undefined
    });

    // Example 2:  Specify only the billboard's cartographic position.
    const b = billboards.add({
      position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
    });

##### See:

- BillboardCollection#remove
- BillboardCollection#removeAll

#### contains(billboard) → boolean
engine/Source/Scene/BillboardCollection.js 689

Check whether this collection contains a given billboard.

Name | Type | Description
--- | --- | ---
`billboard` | Billboard | optional The billboard to check for.

##### Returns:

true if this collection contains the billboard, false otherwise.

##### See:

- BillboardCollection#get

#### destroy()
engine/Source/Scene/BillboardCollection.js 2432

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:

    billboards = billboards && billboards.destroy();

##### See:

- BillboardCollection#isDestroyed

#### get(index) → Billboard
engine/Source/Scene/BillboardCollection.js 720

Returns the billboard in the collection at the specified index. Indices are zero-based and increase as billboards are added. Removing a billboard shifts all billboards after it to the left, changing their indices. This function is commonly used with `BillboardCollection#length` to iterate over all the billboards in the collection.

##### Performance:

Expected constant time. If billboards were removed from the collection and `BillboardCollection#update` was not called, an implicit `O(n)` operation is performed.

Name | Type | Description
--- | --- | ---
`index` | number | The zero-based index of the billboard.

##### Returns:

The billboard at the specified index.

##### Throws:

- DeveloperError : This object was destroyed, i.e., destroy() was called.

##### Example:

    // Toggle the show property of every billboard in the collection
    const len = billboards.length;
    for (let i = 0; i < len; ++i) {
      const b = billboards.get(i);
      b.show = !b.show;
    }

##### See:

- BillboardCollection#length

#### isDestroyed() → boolean
engine/Source/Scene/BillboardCollection.js 2412

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:

- BillboardCollection#destroy

#### remove(billboard) → boolean
engine/Source/Scene/BillboardCollection.js 612

Removes a billboard from the collection.

##### 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 billboards as possible before calling `update`. If you intend to temporarily hide a billboard, it is usually more efficient to call `Billboard#show` instead of removing and re-adding the billboard.

Name | Type | Description
--- | --- | ---
`billboard` | Billboard | The billboard to remove.

##### Returns:

`true` if the billboard was removed; `false` if the billboard was not found in the collection.

##### Throws:

- DeveloperError : This object was destroyed, i.e., destroy() was called.

##### Example:

    const b = billboards.add(...);
    billboards.remove(b);  // Returns true

##### See:

- BillboardCollection#add
- BillboardCollection#removeAll
- Billboard#show

#### removeAll()
engine/Source/Scene/BillboardCollection.js 641

Removes all billboards from the collection.

##### Performance:

`O(n)`. It is more efficient to remove all the billboards 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:

    billboards.add(...);
    billboards.add(...);
    billboards.removeAll();

##### See:

- BillboardCollection#add
- BillboardCollection#remove

#### update()
engine/Source/Scene/BillboardCollection.js 1819

Called when `Viewer` or `CesiumWidget` render the scene to get the draw commands needed to render this primitive.

Do not call this function directly. This is documented just to list the exceptions that may be propagated when the scene is rendered:

##### Throws:

- RuntimeError : image with id must be in the atlas.

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