Cesium API - Billboard 中文文档

new Cesium.Billboard()

Scene/Billboard.js 48

3D场景中与视图对齐的图像，使用BillboardCollection创建和渲染并通过调用BillboardCollection#add设置其初始属性。

Example billboards

效率优化说明：

如果集合中的大多数布告牌需要更新，使用BillboardCollection#removeAll清除集合，并添加新的布告牌可能更有效，而不是修改每个布告牌。

异常情况：

• DeveloperError : scaleByDistance.far 必须大于 scaleByDistance.near。
• DeveloperError : translucencyByDistance.far 必须大于 translucencyByDistance.near。
• DeveloperError : pixelOffsetScaleByDistance.far 必须大于 pixelOffsetScaleByDistance.near。
• DeveloperError : distanceDisplayCondition.far 必须大于 distanceDisplayCondition.near。

演示Demo：

• Cesium Sandcastle Billboard Demo

参考：

• BillboardCollection
• BillboardCollection#add
• Label

成员变量

示例：

// 例1
// 把布告牌的上向量指向北。
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;

// 例2
// 把布告牌指向东边。
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;
billboard.rotation = -Cesium.Math.PI_OVER_TWO;

// 例3
// 重设对齐轴
billboard.alignedAxis = Cesium.Cartesian3.ZERO;

获取或设置与布告牌纹理相乘的颜色。 这有两个常见的用例， 第一，相同的白色纹理可能会被许多不同的布告牌使用，每个布告牌都有不同的颜色，从而创建彩色布告牌。 第二，颜色的alpha分量可以用来使布告牌半透明，如下图所示。 如下所示。 0.0 的Alpha使布告牌透明，而 1.0 的Alpha使布告牌不透明。

default

alpha : 0.5

红色，绿色，蓝色和alpha值由 value 的 red ， green ， blue 和 alpha 属性，范围为 0.0到 1.0。

示例：

// 例1. 黄颜色
b.color = Cesium.Color.YELLOW;

// 例 2. 布告牌变成50%透明
b.color = new Cesium.Color(1.0, 1.0, 1.0, 0.5);

Default Value: undefined

获取或设置在视点坐标中应用于此布告牌的3D笛卡尔偏移。 视点坐标是左手坐标系，其中 x 指向查看者的右侧， y 指向上方，并且 z 指向屏幕。视点坐标与世界坐标和模型坐标使用相同的比例，通常是米。 在下方，布告牌位于地球中心，但视点偏移使它始终无论观看者或地球的方向如何，它都会出现在地球的顶部。

b.eyeOffset = new Cartesian3(0.0, 8000000.0, 0.0);

Default Value: HeightReference.NONE

获取或者设置布告牌的水平原点位置。（左侧，中心或者右侧）

示例：

// 原点在底部左侧
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

示例：

// 从url加载图像
b.image = 'some/image/url.png';
// 假设b1和b2是同一个布告牌集合中的布告牌，对两个布告牌使用相同的图像。
b2.image = b1.image;

获取或设置屏幕空间中距此布告牌原点的像素偏移， 屏幕空间原点是画布的左上角； x 从从左到右， y 从上到下增加。

default

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

布告牌的原点用黄点表示。

示例：

// 例1
// 当相机距离布告牌1500米时，将布告牌的像素偏移比例设置为0.0，相机距离布告牌8.0e6米时，在y方向将布告牌的像素偏移比例设置为10.0。
b.pixelOffset = new Cesium.Cartesian2(0.0, 1.0);
b.pixelOffsetScaleByDistance = new Cesium.NearFarScalar(1.5e2, 0.0, 8.0e6, 10.0);

// 例2
// 通过距离禁用像素偏移。
b.pixelOffsetScaleByDistance = undefined;

Default Value: false

获取或设置与布告牌的缩放系数。

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

示例：

// 例1：
// 当相机距离布告牌1500米时，将布告牌的scaleByDistance调整为1.5，当相机距离接近8.0e6米时，布告牌消失。
b.scaleByDistance = new Cesium.NearFarScalar(1.5e2, 1.5, 8.0e6, 0.0);

// 例2：
// 禁用按距离缩放
b.scaleByDistance = undefined;

Default Value: true

Default Value: false

示例：

// 例1
// 当相机距离布告牌1500米时，将布告牌的translucency调整为1.0，当相机距离接近8.0e6米时，布告牌消失。
b.translucencyByDistance = new Cesium.NearFarScalar(1.5e2, 1.0, 8.0e6, 0.0);

// 例2
// 通过距离禁用半透明。
b.translucencyByDistance = undefined;

获取或者设置布告牌的垂直原点位置。（上面，中心或者下面）

示例：

// 原点在底部左侧
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

内置方法

• DeveloperError : 布告牌的屏幕空间位置。

示例：

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

参考：

• Billboard#eyeOffset
• Billboard#pixelOffset

示例：

// 动态创建布告牌图像
function drawImage(id) {
  // create and draw an image using a canvas
  var canvas = document.createElement('canvas');
  var context2D = canvas.getContext('2d');
  // ... draw image
  return canvas;
}
//调用drawImage来创建纹理
b.setImage('myImage', drawImage);
// 使用相同id在同一集合中创建的后续布告牌将使用现有的纹理，而不需要创建画布或绘制图像
b2.setImage('myImage', drawImage);

• RuntimeError : 此id的图像必须在图集中

类型定义