LabelCollection

查阅Mars3D API

new Cesium.LabelCollection(options)

engine/Source/Scene/LabelCollection.js 623

A renderable collection of labels. Labels are viewport-aligned text positioned in the 3D scene. Each label can have a different font, color, scale, etc.

Example labels

Labels are added and removed from the collection using LabelCollection#add and LabelCollection#remove.

Performance:

For best performance, prefer a few collections, each with many labels, to many collections with only a few labels each. Avoid having collections where some labels change every frame and others do not; instead, create one or more collections for static labels, and one or more collections for dynamic labels.

参数名称	类型	描述信息
options	object	可选 Object with the following properties: 参数名称 类型 默认值 描述信息 modelMatrix Matrix4 Matrix4.IDENTITY 可选 The 4x4 transformation matrix that transforms each label from model to world coordinates. debugShowBoundingVolume boolean false 可选 For debugging only. Determines if this primitive's commands' bounding spheres are shown. scene Scene 可选 Must be passed in for labels that use the height reference property or will be depth tested against the globe. blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT 可选 The label blending option. The default is used for rendering both opaque and translucent labels. However, if either all of the labels 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 可选 Determines if the labels in the collection will be shown. coarseDepthTestDistance number 可选 The distance from the camera, beyond which, labels are depth-tested against an approximation of the globe ellipsoid rather than against the full globe depth buffer. If unspecified, the default value is determined relative to the value of Ellipsoid.default. threePointDepthTestDistance number 可选 The distance from the camera, within which, lables with a Label#heightReference value of HeightReference.CLAMP_TO_GROUND or HeightReference.CLAMP_TO_TERRAIN are depth tested against three key points. This ensures that if any key point of the label is visible, the whole label will be visible. If unspecified, the default value is determined relative to the value of Ellipsoid.default.

使用示例:

// Create a label collection with two labels
const labels = scene.primitives.add(new Cesium.LabelCollection());
labels.add({
  position : new Cesium.Cartesian3(1.0, 2.0, 3.0),
  text : 'A label'
});
labels.add({
  position : new Cesium.Cartesian3(4.0, 5.0, 6.0),
  text : 'Another label'
});

Demo:

• Cesium Sandcastle Labels Demo

参考:

• LabelCollection#add
• LabelCollection#remove
• Label
• BillboardCollection

成员(属性)

默认值: BlendOption.OPAQUE_AND_TRANSLUCENT

默认值: false

默认值: Matrix4.IDENTITY

使用示例:

const center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
labels.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
labels.add({
  position : new Cesium.Cartesian3(0.0, 0.0, 0.0),
  text     : 'Center'
});
labels.add({
  position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0),
  text     : 'East'
});
labels.add({
  position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0),
  text     : 'North'
});
labels.add({
  position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0),
  text     : 'Up'
});

默认值: true

参考:

• Billboards and Labels on Terrain Improvements

方法

Performance:

Calling add is expected constant time. However, the collection's vertex buffer is rewritten; this operations is O(n) and also incurs CPU to GPU overhead. For best performance, add as many billboards as possible before calling update.

返回值:

Throws:

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

使用示例s:

// Example 1:  Add a label, specifying all the default values.
const l = labels.add({
  show : true,
  position : Cesium.Cartesian3.ZERO,
  text : '',
  font : '30px sans-serif',
  fillColor : Cesium.Color.WHITE,
  outlineColor : Cesium.Color.BLACK,
  outlineWidth : 1.0,
  showBackground : false,
  backgroundColor : new Cesium.Color(0.165, 0.165, 0.165, 0.8),
  backgroundPadding : new Cesium.Cartesian2(7, 5),
  style : Cesium.LabelStyle.FILL,
  pixelOffset : Cesium.Cartesian2.ZERO,
  eyeOffset : Cesium.Cartesian3.ZERO,
  horizontalOrigin : Cesium.HorizontalOrigin.LEFT,
  verticalOrigin : Cesium.VerticalOrigin.BASELINE,
  scale : 1.0,
  translucencyByDistance : undefined,
  pixelOffsetScaleByDistance : undefined,
  heightReference : HeightReference.NONE,
  distanceDisplayCondition : undefined
});

// Example 2:  Specify only the label's cartographic position,
// text, and font.
const l = labels.add({
  position : Cesium.Cartesian3.fromRadians(longitude, latitude, height),
  text : 'Hello World',
  font : '24px Helvetica',
});

参考:

• LabelCollection#remove
• LabelCollection#removeAll

返回值:

参考:

• LabelCollection#get

Throws:

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

使用示例:

labels = labels && labels.destroy();

参考:

• LabelCollection#isDestroyed

Performance:

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

返回值:

Throws:

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

使用示例:

// Toggle the show property of every label in the collection
const len = labels.length;
for (let i = 0; i < len; ++i) {
  const l = billboards.get(i);
  l.show = !l.show;
}

参考:

• LabelCollection#length

返回值:

参考:

• LabelCollection#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 labels as possible before calling update. If you intend to temporarily hide a label, it is usually more efficient to call Label#show instead of removing and re-adding the label.

返回值:

Throws:

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

使用示例:

const l = labels.add(...);
labels.remove(l);  // Returns true

参考:

• LabelCollection#add
• LabelCollection#removeAll
• Label#show

Performance:

O(n). It is more efficient to remove all the labels 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.

使用示例:

labels.add(...);
labels.add(...);
labels.removeAll();

参考:

• LabelCollection#add
• LabelCollection#remove