BillboardCollection

new Cesium.BillboardCollection(options)

engine/Source/Scene/BillboardCollection.js 145

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.

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

Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

Default Value: false

Default Value: false

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

Default Value: true

Methods

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.

Returns:

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

Returns:

See:

• BillboardCollection#get

Throws:

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

Example:

billboards = billboards && billboards.destroy();

See:

• BillboardCollection#isDestroyed

Performance:

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

Returns:

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

Returns:

See:

• BillboardCollection#destroy

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.

Returns:

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

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

Throws:

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