Billboard

new Billboard

A viewport-aligned image positioned in the 3D scene, that is created and rendered using a BillboardCollection. A billboard is created and its initial properties are set by calling BillboardCollection#add. Any of the billboard's properties can be changed at any time by calling the billboard's corresponding set function, e.g., Billboard#setShow.

Example billboards

Performance:

Calling any get function, e.g., Billboard#getShow, is constant time. Calling a set function, e.g., Billboard#setShow, is constant time but results in CPU to GPU traffic when BillboardCollection#update is called. The per-billboard traffic is the same regardless of how many properties were updated. If most billboards in a collection need to be updated, it may be more efficient to clear the collection with BillboardCollection#removeAll and add new billboards instead of modifying each one.

Throws:

• DeveloperError : scaleByDistance.far must be greater than scaleByDistance.near
• DeveloperError : translucencyByDistance.far must be greater than translucencyByDistance.near
• DeveloperError : pixelOffsetScaleByDistance.far must be greater than pixelOffsetScaleByDistance.near

Demo:

• Cesium Sandcastle Billboard Demo

See:

• BillboardCollection
• BillboardCollection#add
• Label

Source:

• /Source/Scene/Billboard.js

Members

<static> tempPixelOffset :DeveloperError

Computes the screen-space position of the billboard's origin, taking into account eye and pixel offsets. The screen space origin is the bottom, left corner of the canvas; x increases from left to right, and y increases from bottom to top.

Example

console.log(b.computeScreenSpacePosition(scene.context, scene.frameState).toString());

See:

• Billboard#setEyeOffset
• Billboard#setPixelOffset

Methods

equals

Determines if this billboard equals another billboard. Billboards are equal if all their properties are equal. Billboards in different collections can be equal.

Parameters:

Name	Type	Description
other	Billboard	The billboard to compare for equality.

Returns:

Boolean true if the billboards are equal; otherwise, false.

getAlignedAxis

Gets the aligned axis in world space. The aligned axis is the unit vector that the billboard up vector points towards. The default is the zero vector, which means the billboard is aligned to the screen up vector.

Returns:

Cartesian3 The aligned axis.

See:

• Billboard#setRotation
• Billboard#getRotation
• Billboard#setAlignedAxis

getColor

Returns the color that is multiplied with the billboard's texture. The red, green, blue, and alpha values are indicated by the returned object's red, green, blue, and alpha properties, which range from 0 (no intensity) to 1.0 (full intensity).

Returns:

Number The color that is multiplied with the billboard's texture.

See:

• Billboard#setColor

getEyeOffset

Returns the 3D Cartesian offset applied to this billboard in eye coordinates.

Returns:

Cartesian3 The 3D Cartesian offset applied to this billboard in eye coordinates.

See:

• Billboard#setEyeOffset

getHeight

Gets the billboards custom height or undefined if the image height is used.

Returns:

Number The billboard's height or undefined.

See:

• Billboard#setHeight
• Billboard#getWidth
• Billboard#setWidth

getHorizontalOrigin

Returns the horizontal origin of this billboard.

Returns:

HorizontalOrigin The horizontal origin of this billboard.

See:

• Billboard#setHorizontalOrigin

getId

Returns the user-defined object returned when the billboard is picked.

Returns:

Object The user-defined object returned when the billboard is picked.

getImageIndex

DOC_TBA

See:

• Billboard#setImageIndex
• BillboardCollection#textureAtlas

getPixelOffset

Returns the pixel offset from the origin of this billboard.

Returns:

Cartesian2 The pixel offset of this billboard.

See:

• Billboard#setPixelOffset

getPixelOffsetScaleByDistance

Returns the near and far pixel offset scaling properties of a Billboard based on the billboard's distance from the camera.

Returns:

NearFarScalar The near/far pixel offset scaling values based on camera distance to the billboard

See:

• Billboard#setPixelOffsetScaleByDistance
• Billboard#setPixelOffset
• Billboard#getPixelOffset

getPosition

Returns the Cartesian position of this billboard.

Returns:

Cartesian3 The Cartesian position of this billboard.

See:

• Billboard#setPosition

getRotation

Gets the rotation angle in radians.

Returns:

Number The rotation angle in radians.

See:

• Billboard#setRotation
• Billboard#getAlignedAxis
• Billboard#setAlignedAxis

getScale

Returns the uniform scale that is multiplied with the billboard's image size in pixels.

Returns:

Number The scale used to size the billboard.

See:

• Billboard#setScale

getScaleByDistance

Returns the near and far scaling properties of a Billboard based on the billboard's distance from the camera.

Returns:

NearFarScalar The near/far scaling values based on camera distance to the billboard

See:

• Billboard#setScaleByDistance

getShow

Returns true if this billboard will be shown. Call Billboard#setShow to hide or show a billboard, instead of removing it and re-adding it to the collection.

Returns:

Boolean true if this billboard will be shown; otherwise, false.

See:

• Billboard#setShow

getTranslucencyByDistance

Returns the near and far translucency properties of a Billboard based on the billboard's distance from the camera.

Returns:

NearFarScalar The near/far translucency values based on camera distance to the billboard

See:

• Billboard#setTranslucencyByDistance

getVerticalOrigin

Returns the vertical origin of this billboard.

Returns:

VerticalOrigin The vertical origin of this billboard.

See:

• Billboard#setVerticalOrigin

getWidth

Gets the billboards custom width or undefined if the image width is used.

Returns:

Number The billboard's width or undefined.

See:

• Billboard#setWidth
• Billboard#getHeight
• Billboard#setHeight

setAlignedAxis

Sets the aligned axis in world space. The aligned axis is the unit vector that the billboard up vector points towards. The default is the zero vector, which means the billboard is aligned to the screen up vector.

Parameters:

Name	Type	Description
value	Cartesian3	The aligned axis.

Example

// Example 1.
// Have the billboard up vector point north
billboard.setAlignedAxis(Cesium.Cartesian3.UNIT_Z);

// Example 2.
// Have the billboard point east.
billboard.setAlignedAxis(Cartesian3.UNIT_Z);
billboard.setRotation(-Cesium.Math.PI_OVER_TWO);

// Example 3.
// Reset the aligned axis
billboard.setAlignedAxis(Cesium.Cartesian3.ZERO);

See:

• Billboard#setRotation
• Billboard#getRotation
• Billboard#setAlignedAxis

setColor

Sets the color that is multiplied with the billboard's texture. This has two common use cases. First, the same white texture may be used by many different billboards, each with a different color, to create colored billboards. Second, the color's alpha component can be used to make the billboard translucent as shown below. An alpha of 0.0 makes the billboard transparent, and 1.0 makes the billboard opaque.

default

alpha : 0.5

The red, green, blue, and alpha values are indicated by value's red, green, blue, and alpha properties as shown in Example 1. These components range from 0.0 (no intensity) to 1.0 (full intensity).

Parameters:

Name	Type	Description
value	Object	The color's red, green, blue, and alpha components.

Example

// Example 1. Assign yellow.
b.setColor({
  red   : 1.0,
  green : 1.0,
  blue  : 0.0,
  alpha : 1.0
});

// Example 2. Make a billboard 50% translucent.
b.setColor({
  red   : 1.0,
  green : 1.0,
  blue  : 1.0,
  alpha : 0.5
});

See:

• Billboard#getColor

setEyeOffset

Sets the 3D Cartesian offset applied to this billboard in eye coordinates. Eye coordinates is a left-handed coordinate system, where x points towards the viewer's right, y points up, and z points into the screen. Eye coordinates use the same scale as world and model coordinates, which is typically meters.

An eye offset is commonly used to arrange multiple billboards or objects at the same position, e.g., to arrange a billboard above its corresponding 3D model.

value can be either a Cartesian3 or an object literal with x, y, and z properties. A copy of value is made, so changing it after calling setEyeOffset does not affect the billboard's eye offset; an explicit call to setEyeOffset is required.

Below, the billboard is positioned at the center of the Earth but an eye offset makes it always appear on top of the Earth regardless of the viewer's or Earth's orientation.

b.setEyeOffset({ x : 0.0, y : 8000000.0, z : 0.0 });

Parameters:

Name	Type	Description
value	Cartesian3	The 3D Cartesian offset in eye coordinates.

See:

• Billboard#getEyeOffset

setHeight

Sets a custom height for the billboard. If undefined, the image height will be used.

Parameters:

Name	Type	Description
value	Number	The height of the billboard or undefined to use the image height.

See:

• Billboard#getHeight
• Billboard#getWidth
• Billboard#setWidth

setHorizontalOrigin

Sets the horizontal origin of this billboard, which determines if the billboard is to the left, center, or right of its position.

Parameters:

Name	Type	Description
value	HorizontalOrigin	The horizontal origin.

Example

// Use a bottom, left origin
b.setHorizontalOrigin(Cesium.HorizontalOrigin.LEFT);
b.setVerticalOrigin(Cesium.VerticalOrigin.BOTTOM);

See:

• Billboard#getHorizontalOrigin
• Billboard#setVerticalOrigin

setImageIndex

DOC_TBA

See:

• Billboard#getImageIndex
• BillboardCollection#textureAtlas

setPixelOffset

Sets the pixel offset in screen space from the origin of this billboard. This is commonly used to align multiple billboards and labels at the same position, e.g., an image and text. The screen space origin is the bottom, left corner of the canvas; x increases from left to right, and y increases from bottom to top.

value can be either a Cartesian2 or an object literal with x and y properties. A copy of value is made, so changing it after calling setPixelOffset does not affect the billboard's pixel offset; an explicit call to setPixelOffset is required.

default

b.setPixelOffset({ x : 50, y : -25 });

The billboard's origin is indicated by the yellow point.

Parameters:

Name	Type	Description
value	Cartesian2	The 2D Cartesian pixel offset.

See:

• Billboard#getPixelOffset
• Label#setPixelOffset

setPixelOffsetScaleByDistance

Sets near and far pixel offset scaling properties of a Billboard based on the billboard's distance from the camera. A billboard's pixel offset will be scaled between the NearFarScalar#nearValue and NearFarScalar#farValue while the camera distance falls within the upper and lower bounds of the specified NearFarScalar#near and NearFarScalar#far. Outside of these ranges the billboard's pixel offset scale remains clamped to the nearest bound. If undefined, pixelOffsetScaleByDistance will be disabled.

Parameters:

Name	Type	Description
pixelOffsetScale	NearFarScalar	The configuration of near and far distances and their respective pixel offset scaling values

Throws:

DeveloperError : far distance must be greater than near distance.

Example

// Example 1.
// Set a billboard's pixel offset scale to 0.0 when the
// camera is 1500 meters from the billboard and scale pixel offset to 10.0 pixels
// in the y direction the camera distance approaches 8.0e6 meters.
b.setPixelOffset(new Cesium.Cartesian2(0.0, 1.0);
b.setPixelOffsetScaleByDistance(new Cesium.NearFarScalar(1.5e2, 0.0, 8.0e6, 10.0));

// Example 2.
// disable pixel offset by distance
b.setPixelOffsetScaleByDistance(undefined);

See:

• Billboard#getPixelOffsetScaleByDistance
• Billboard#setPixelOffset
• Billboard#getPixelOffset

setPosition

Sets the Cartesian position of this billboard.

As shown in the examples, value can be either a Cartesian3 or an object literal with x, y, and z properties. A copy of value is made, so changing it after calling setPosition does not affect the billboard's position; an explicit call to setPosition is required.

Parameters:

Name	Type	Description
value	Cartesian3	The Cartesian position.

Example

// Example 1. Set a billboard's position using a Cartesian3.
b.setPosition(new Cesium.Cartesian3(1.0, 2.0, 3.0));

// Example 2. Set a billboard's position using an object literal.
b.setPosition({
  x : 1.0,
  y : 2.0,
  z : 3.0
});

See:

• Billboard#getPosition

setRotation

Sets the rotation angle in radians.

Parameters:

Name	Type	Description
value	Number	The rotation angle in radians.

See:

• Billboard#getRotation
• Billboard#getAlignedAxis
• Billboard#setAlignedAxis

setScale

Sets the uniform scale that is multiplied with the billboard's image size in pixels. A scale of 1.0 does not change the size of the billboard; a scale greater than 1.0 enlarges the billboard; a positive scale less than 1.0 shrinks the billboard.

From left to right in the above image, the scales are 0.5, 1.0, and 2.0.

Parameters:

Name	Type	Description
value	Number	The scale used to size the billboard.

See:

• Billboard#getScale
• Billboard#setImageIndex

setScaleByDistance

Sets near and far scaling properties of a Billboard based on the billboard's distance from the camera. A billboard's scale will interpolate between the NearFarScalar#nearValue and NearFarScalar#farValue while the camera distance falls within the upper and lower bounds of the specified NearFarScalar#near and NearFarScalar#far. Outside of these ranges the billboard's scale remains clamped to the nearest bound. If undefined, scaleByDistance will be disabled.

Parameters:

Name	Type	Description
scale	NearFarScalar	The configuration of near and far distances and their respective scale values

Throws:

DeveloperError : far distance must be greater than near distance.

Example

// Example 1.
// Set a billboard's scaleByDistance to scale by 1.5 when the
// camera is 1500 meters from the billboard and disappear as
// the camera distance approaches 8.0e6 meters.
b.setScaleByDistance(new Cesium.NearFarScalar(1.5e2, 1.5, 8.0e6, 0.0));

// Example 2.
// disable scaling by distance
b.setScaleByDistance(undefined);

See:

• Billboard#getScaleByDistance

setShow

Determines if this billboard will be shown. Call this to hide or show a billboard, instead of removing it and re-adding it to the collection.

Parameters:

Name	Type	Description
value	Boolean	Indicates if this billboard will be shown.

See:

• Billboard#getShow

setTranslucencyByDistance

Sets near and far translucency properties of a Billboard based on the billboard's distance from the camera. A billboard's translucency will interpolate between the NearFarScalar#nearValue and NearFarScalar#farValue while the camera distance falls within the upper and lower bounds of the specified NearFarScalar#near and NearFarScalar#far. Outside of these ranges the billboard's translucency remains clamped to the nearest bound. If undefined, translucencyByDistance will be disabled.

Parameters:

Name	Type	Description
translucency	NearFarScalar	The configuration of near and far distances and their respective translucency values

Throws:

DeveloperError : far distance must be greater than near distance.

Example

// Example 1.
// Set a billboard's translucency to 1.0 when the
// camera is 1500 meters from the billboard and disappear as
// the camera distance approaches 8.0e6 meters.
b.setTranslucencyByDistance(new Cesium.NearFarScalar(1.5e2, 1.0, 8.0e6, 0.0));

// Example 2.
// disable translucency by distance
b.setTranslucencyByDistance(undefined);

See:

• Billboard#getTranslucencyByDistance

setVerticalOrigin

Sets the vertical origin of this billboard, which determines if the billboard is to the above, below, or at the center of its position.

Parameters:

Name	Type	Description
value	VerticalOrigin	The vertical origin.

Example

// Use a bottom, left origin
b.setHorizontalOrigin(Cesium.HorizontalOrigin.LEFT);
b.setVerticalOrigin(Cesium.VerticalOrigin.BOTTOM);

See:

• Billboard#getVerticalOrigin
• Billboard#setHorizontalOrigin

setWidth

Sets a custom width for the billboard. If undefined, the image width will be used.

Parameters:

Name	Type	Description
value	Number	The width of the billboard or undefined to use the image width.

See:

• Billboard#getWidth
• Billboard#getHeight
• Billboard#setHeight