Billboard

internal constructor new Cesium.Billboard(options, billboardCollection)

engine/Source/Scene/Billboard.js 98

创建了一个广告牌，并通过调用设置其初始属性 A billboard is created and its initial properties are set by calling BillboardCollection#add。不要直接调用构造函数。 . Do not call the constructor directly.

位于 3D 场景中的视口对齐图像，使用 A viewport-aligned image positioned in the 3D scene, that is created and rendered using a BillboardCollection.

广告牌示例 Example billboards

性能： Performance:

读取属性，例如 Reading a property, e.g., Billboard#show，是常数时间。分配给属性的时间是恒定的，但会导致 CPU 到 GPU 的流量 , is constant time. Assigning to a property 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.

名称 Name	类型 Type	说明 Description
options	Billboard.ConstructorOptions	描述初始化选项的对象 Object describing initialization options
billboardCollection	BillboardCollection	BillboardCollection 实例 Instance of BillboardCollection

抛出： Throws:

• DeveloperError ：scaleByDistance.far 必须大于scaleByDistance.near : scaleByDistance.far must be greater than scaleByDistance.near
• DeveloperError ：translucencyByDistance.far 必须大于 translucencyByDistance.near : translucencyByDistance.far must be greater than translucencyByDistance.near
• DeveloperError ：pixelOffsetScaleByDistance.far 必须大于 PixelOffsetScaleByDistance.near : pixelOffsetScaleByDistance.far must be greater than pixelOffsetScaleByDistance.near
• DeveloperError ：distanceDisplayCondition.far 必须大于 distanceDisplayCondition.near : distanceDisplayCondition.far must be greater than distanceDisplayCondition.near

演示： Demo:

• Cesium Sandcastle Billboard Demo

另见： See:

• BillboardCollection
• BillboardCollection#add
• Label

成员 Members

示例： Examples:

// Example 1.
// Have the billboard up vector point north
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;

// Example 2.
// Have the billboard point east.
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;
billboard.rotation = -Cesium.Math.PI_OVER_TWO;

// Example 3.
// Reset the aligned axis
billboard.alignedAxis = Cesium.Cartesian3.ZERO;

获取或设置与广告牌纹理相乘的颜色。这有两个常见的用例。首先，相同的白色纹理可以被许多不同的广告牌使用，每个广告牌具有不同的颜色，以创建彩色广告牌。其次，颜色的 Alpha 分量可用于使广告牌半透明，如下所示。阿尔法 Gets or 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

红色、绿色、蓝色和 alpha 值由下式表示 The red, green, blue, and alpha values are indicated by value的 's red, green, blue, 和 , and alpha 特性如示例 1 所示。这些组件的范围为 properties as shown in Example 1. These components range from 0.0 （无强度）至 (no intensity) to 1.0 （全强度）。 (full intensity).

示例： Examples:

// Example 1. Assign yellow.
b.color = Cesium.Color.YELLOW;

// Example 2. Make a billboard 50% translucent.
b.color = new Cesium.Color(1.0, 1.0, 1.0, 0.5);

默认值： Default Value: undefined

默认值： Default Value: undefined

获取或设置在眼睛坐标中应用于此广告牌的 3D 笛卡尔偏移。眼坐标是左手坐标系，其中 Gets or 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.

眼睛偏移通常用于将多个广告牌或对象布置在同一位置，例如，将广告牌布置在其相应的 3D 模型之上。 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.

下面，广告牌位于地球中心，但眼睛偏移使其始终显示在地球顶部，无论观看者或地球的方向如何。 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.eyeOffset = new Cartesian3(0.0, 8000000.0, 0.0);

默认值： Default Value: HeightReference.NONE

获取或设置此广告牌的水平原点，它确定广告牌是在其锚点位置的左侧、中心还是右侧。 Gets or sets the horizontal origin of this billboard, which determines if the billboard is to the left, center, or right of its anchor position.

示例： Example:

// Use a bottom, left origin
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

示例： Example:

// load an image from a URL
b.image = 'some/image/url.png';

// assuming b1 and b2 are billboards in the same billboard collection,
// use the same image for both billboards.
b2.image = b1.image;

获取或设置屏幕空间中距此广告牌原点的像素偏移量。这通常用于在同一位置对齐多个广告牌和标签，例如图像和文本。屏幕空间原点是画布的左上角； Gets or 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 top, left corner of the canvas; x 从左到右增加，并且 increases from left to right, and y 从上到下增加。 increases from top to bottom.

default

b.pixeloffset = new Cartesian2(50, 25);

广告牌的原点由黄点表示。 The billboard's origin is indicated by the yellow point.

示例： Examples:

// 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.pixelOffset = new Cesium.Cartesian2(0.0, 1.0);
b.pixelOffsetScaleByDistance = new Cesium.NearFarScalar(1.5e2, 0.0, 8.0e6, 10.0);

// Example 2.
// disable pixel offset by distance
b.pixelOffsetScaleByDistance = undefined;

默认值： Default Value: false

获取或设置与广告牌图像大小（以像素为单位）相乘的统一比例。规模为 Gets or 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.

示例： Examples:

// 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.scaleByDistance = new Cesium.NearFarScalar(1.5e2, 1.5, 8.0e6, 0.0);

// Example 2.
// disable scaling by distance
b.scaleByDistance = undefined;

默认值： Default Value: true

默认值： Default Value: false

默认值： Default Value: SplitDirection.NONE

示例： Examples:

// 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.translucencyByDistance = new Cesium.NearFarScalar(1.5e2, 1.0, 8.0e6, 0.0);

// Example 2.
// disable translucency by distance
b.translucencyByDistance = undefined;

获取或设置此广告牌的垂直原点，它确定广告牌是位于其锚点位置的上方、下方还是中心。 Gets or sets the vertical origin of this billboard, which determines if the billboard is to the above, below, or at the center of its anchor position.

示例： Example:

// Use a bottom, left origin
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

方法 Methods

返回： Returns:

抛出： Throws:

• DeveloperError ：广告牌必须在集合中。 : Billboard must be in a collection.

示例： Example:

console.log(b.computeScreenSpacePosition(scene).toString());

另见： See:

• Billboard#eyeOffset
• Billboard#pixelOffset

返回： Returns:

示例： Example:

// create a billboard image dynamically
function drawImage(id) {
  // create and draw an image using a canvas
  const canvas = document.createElement('canvas');
  const context2D = canvas.getContext('2d');
  // ... draw image
  return canvas;
}
// drawImage will be called to create the texture
b.setImage('myImage', drawImage);

// subsequent billboards created in the same collection using the same id will use the existing
// texture, without the need to create the canvas or draw the image
b2.setImage('myImage', drawImage);

抛出： Throws:

• RuntimeError : 带有id的图片必须在图集中 : image with id must be in the atlas

类型定义 Type Definitions

属性： Properties:

名称 Name	类型 Type	Attributes	默认值 Default	说明 Description
position	Cartesian3			广告牌的笛卡尔位置。 The cartesian position of the billboard.
id	*	<可选> &lt;optional>		选取广告牌时要返回的用户定义对象 A user-defined object to return when the billboard is picked with Scene#pick.
show	boolean	<可选> &lt;optional>	true	确定是否显示此广告牌。 Determines if this billboard will be shown.
image	string | HTMLImageElement | HTMLCanvasElement	<可选> &lt;optional>		加载的 HTMLImageElement、ImageData 或用于广告牌的图像的 url。 A loaded HTMLImageElement, ImageData, or a url to an image to use for the billboard.
scale	number	<可选> &lt;optional>	1.0	指定统一比例的数字，该比例乘以广告牌图像大小（以像素为单位）。 A number specifying the uniform scale that is multiplied with the billboard's image size in pixels.
pixelOffset	Cartesian2	<可选> &lt;optional>	Cartesian2.ZERO	A Cartesian2 指定屏幕空间中距此广告牌原点的像素偏移量。 Specifying the pixel offset in screen space from the origin of this billboard.
eyeOffset	Cartesian3	<可选> &lt;optional>	Cartesian3.ZERO	A Cartesian3 指定在眼睛坐标中应用于此广告牌的 3D 笛卡尔偏移。 Specifying the 3D Cartesian offset applied to this billboard in eye coordinates.
horizontalOrigin	HorizontalOrigin	<可选> &lt;optional>	HorizontalOrigin.CENTER	A HorizontalOrigin 指定此广告牌的水平原点。 Specifying the horizontal origin of this billboard.
verticalOrigin	VerticalOrigin	<可选> &lt;optional>	VerticalOrigin.CENTER	A VerticalOrigin 指定此广告牌的垂直原点。 Specifying the vertical origin of this billboard.
heightReference	HeightReference	<可选> &lt;optional>	HeightReference.NONE	A HeightReference 指定此广告牌的高度参考。 Specifying the height reference of this billboard.
color	Color	<可选> &lt;optional>	Color.WHITE	A Color 指定与广告牌纹理相乘的颜色。 Specifying the color that is multiplied with the billboard's texture.
rotation	number	<可选> &lt;optional>	0	以弧度指定旋转角度的数字。 A number specifying the rotation angle in radians.
alignedAxis	Cartesian3	<可选> &lt;optional>	Cartesian3.ZERO	A Cartesian3 指定世界空间中的对齐轴。 Specifying the aligned axis in world space.
sizeInMeters	boolean	<可选> &lt;optional>		一个布尔值，指定广告牌大小是以米还是像素为单位。 A boolean specifying if the billboard size is in meters or pixels.
width	number	<可选> &lt;optional>		指定广告牌宽度的数字。如果未定义，将使用图像宽度。 A number specifying the width of the billboard. If undefined, the image width will be used.
height	number	<可选> &lt;optional>		指定广告牌高度的数字。如果未定义，将使用图像高度。 A number specifying the height of the billboard. If undefined, the image height will be used.
scaleByDistance	NearFarScalar	<可选> &lt;optional>		A NearFarScalar 根据广告牌距摄像机的距离指定广告牌的近距和远距缩放属性。 Specifying near and far scaling properties of a Billboard based on the billboard's distance from the camera.
translucencyByDistance	NearFarScalar	<可选> &lt;optional>		A NearFarScalar 根据广告牌与相机的距离指定广告牌的近端和远端半透明属性。 Specifying near and far translucency properties of a Billboard based on the billboard's distance from the camera.
pixelOffsetScaleByDistance	NearFarScalar	<可选> &lt;optional>		A NearFarScalar 根据广告牌与相机的距离指定广告牌的近和远像素偏移缩放属性。 Specifying near and far pixel offset scaling properties of a Billboard based on the billboard's distance from the camera.
imageSubRegion	BoundingRectangle	<可选> &lt;optional>		A BoundingRectangle 指定用于广告牌的图像的子区域，而不是整个图像。 Specifying the sub-region of the image to use for the billboard, rather than the entire image.
distanceDisplayCondition	DistanceDisplayCondition	<可选> &lt;optional>		A DistanceDisplayCondition 指定显示此广告牌的距摄像机的距离。 Specifying the distance from the camera at which this billboard will be displayed.
disableDepthTestDistance	number	<可选> &lt;optional>		距相机的距离，超过该距离，深度测试将被禁用，例如，防止地形剪切。 The distance from the camera, beyond which, depth testing is disabled—to, for example, prevent clipping against terrain.
splitDirection	SplitDirection	<可选> &lt;optional>		A SplitDirection 指定广告牌的分割属性。 Specifying the split property of the billboard.

返回： Returns: