Class: BillboardCollection

BillboardCollection

new BillboardCollection(optionsopt)

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.
Parameters:
Name Type Attributes Description
options Object <optional>
 Object with the following properties:
Properties
Name Type Attributes Default Description
modelMatrix Matrix4 <optional>
 Matrix4.IDENTITY The 4x4 transformation matrix that transforms each billboard from model to world coordinates.
debugShowBoundingVolume Boolean <optional>
 false 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.
Source:
See:
Example
// Create a billboard collection with two billboards
var 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'
});

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 billboards in this collection. This is commonly used with BillboardCollection#get to iterate over all the billboards in the collection.
Type:
  • Number
Source:

modelMatrix :Matrix4

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.
Type:
Default Value:
Source:
See:
  • Transforms.eastNorthUpToFixedFrame
Example
var 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
});

Methods

add(billboardopt) → {Billboard}

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.
Parameters:
Name Type Attributes Description
billboard Object <optional>
 A template describing the billboard's properties as shown in Example 1.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
The billboard that was added to the collection.
Type
Billboard
Examples
// Example 1:  Add a billboard, specifying all the default values.
var b = billboards.add({
  show : true,
  position : Cesium.Cartesian3.ZERO,
  pixelOffset : Cesium.Cartesian2.ZERO,
  eyeOffset : Cesium.Cartesian3.ZERO,
  horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
  verticalOrigin : Cesium.VerticalOrigin.CENTER,
  scale : 1.0,
  image : 'url/to/image',
  color : Cesium.Color.WHITE,
  id : undefined
});
// Example 2:  Specify only the billboard's cartographic position.
var b = billboards.add({
  position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
});

contains(billboardopt) → {Boolean}

Check whether this collection contains a given billboard.
Parameters:
Name Type Attributes Description
billboard Billboard <optional>
 The billboard to check for.
Source:
See:
Returns:
true if this collection contains the billboard, 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 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
billboards = billboards && billboards.destroy();

get(index) → {Billboard}

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.
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 billboard at the specified index.
Type
Billboard
Example
// Toggle the show property of every billboard in the collection
var len = billboards.length;
for (var i = 0; i < len; ++i) {
  var b = billboards.get(i);
  b.show = !b.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 isDestroyed will result in a DeveloperError exception.
Source:
See:
Returns:
true if this object was destroyed; otherwise, false.
Type
Boolean

remove(billboard) → {Boolean}

Removes a billboard from the collection.
Parameters:
Name Type Description
billboard Billboard The billboard to remove.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
true if the billboard was removed; false if the billboard was not found in the collection.
Type
Boolean
Example
var b = billboards.add(...);
billboards.remove(b);  // Returns true

removeAll()

Removes all billboards from the collection.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Example
billboards.add(...);
billboards.add(...);
billboards.removeAll();

update()

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:

Source:
Throws:
image with id must be in the atlas.
Type
RuntimeError