Cesium API - BillboardCollection 中文文档

new Cesium.BillboardCollection(options)

Scene/BillboardCollection.js 134

一个可渲染的布告牌集合，布告牌是3D场景中与视图对齐的图像。

布告牌示例

使用BillboardCollection#add和BillboardCollection#remove从集合中添加和删除布告牌。 集合中的广告牌自动共享具有相同标识符的图像的纹理。

效率优化说明：

为了获取更好的性能，最好是创建较少的集合，每个集合有较多的布告牌，而不是较多的集合，每个集合中有较少的布告牌。 组织集合的时候，将有相同更新频率的布告牌放在一个集合，不更新的布告牌放在一个集合。

Name	Type	Description
options	Object	optional 具有下列属性的对象： Name Type Default Description modelMatrix Matrix4 Matrix4.IDENTITY optional 4x4转换矩阵，可将每个布告牌从模型坐标转换为世界坐标。 debugShowBoundingVolume Boolean false optional 仅用于调试。确定是否显示此图元命令的包围球。 scene Scene optional 对于高度参考属性的广告牌，必须传入此对象。 blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT optional 布告牌混合选项。默认值用于渲染不透明和半透明的布告牌。 但是，如果所有布告牌都完全不透明或全部完全透明，将技术设置为BlendOption.OPAQUE或BlendOption.TRANSLUCENT最多可以将性能提高2倍。

示例：

// 创建一个布告牌集合并添加两个布告牌。
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'
});

演示Demo：

• Cesium Sandcastle Billboard Demo

参考：

• BillboardCollection#add
• BillboardCollection#remove
• Billboard
• LabelCollection

成员变量

Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

Default Value: false

Default Value: false

Default Value: Matrix4.IDENTITY

示例：

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
});

参考：

• Transforms.eastNorthUpToFixedFrame

内置方法

• DeveloperError : 对象已销毁，即已经调用destroy（）。

示例：

// 例1：添加一个布告牌，指定所有默认值。
var 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
});

// 例2：只指定广告牌的地理位置。
var b = billboards.add({
  position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
});

参考：

• BillboardCollection#remove
• BillboardCollection#removeAll

参考：

• BillboardCollection#get

• DeveloperError : 对象已经被销毁。

示例：

billboards = billboards && billboards.destroy();

参考：

• BillboardCollection#isDestroyed

• DeveloperError : 对象已销毁，即已经调用destroy()。

示例：

// 切换集合中每个布告牌的show属性
var len = billboards.length;
for (var i = 0; i < len; ++i) {
  var b = billboards.get(i);
  b.show = !b.show;
}

参考：

• BillboardCollection#length

参考：

• BillboardCollection#destroy

如果您打算暂时隐藏布告牌，通常可以调用Billboard#show 而不是删除并重新添加布告牌。

• DeveloperError : 对象已销毁，即已经调用destroy（）。

示例：

var b = billboards.add(...);
billboards.remove(b);  // Returns true

参考：

• BillboardCollection#add
• BillboardCollection#removeAll
• Billboard#show

• DeveloperError : 对象已销毁，即已经调用destroy（）。

示例：

billboards.add(...);
billboards.add(...);
billboards.removeAll();

参考：

• BillboardCollection#add
• BillboardCollection#remove

• RuntimeError : 带有id的图像必须在图集中。