KBE3D / KBCore / Cesium / LabelCollection

类: LabelCollection

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. <br /><br /> <div align='center'> <img src='/Images/Label.png' width='400' height='300' /><br /> Example labels </div> <br /><br /> Labels are added and removed from the collection using LabelCollection#add and LabelCollection#remove.

示例

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

参数

Object with the following properties:

参数

The 4x4 transformation matrix that transforms each label from model to world coordinates.

参数

For debugging only. Determines if this primitive's commands' bounding spheres are shown.

参数

Must be passed in for labels that use the height reference property or will be depth tested against the globe.

参数

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.

参数

Determines if the labels in the collection will be shown.

参数

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.

参数

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.

属性

show

show: boolean

Determines if labels in this collection will be shown.

---

modelMatrix

modelMatrix: Matrix4

The 4x4 transformation matrix that transforms each label in this collection from model to world coordinates. When this is the identity matrix, the labels are drawn in world coordinates, i.e., Earth's WGS84 coordinates. Local reference frames can be used by providing a different transformation matrix, like that returned by Transforms.eastNorthUpToFixedFrame.

示例

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

---

debugShowBoundingVolume

debugShowBoundingVolume: boolean

This property is for debugging only; it is not for production use nor is it optimized. <p> Draws the bounding sphere for each draw command in the primitive. </p>

---

blendOption

blendOption: BlendOption

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.

---

length

readonly length: number

Returns the number of labels in this collection. This is commonly used with LabelCollection#get to iterate over all the labels in the collection.

---

coarseDepthTestDistance

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. When set to <code>0</code>, the approximate depth test is always applied. When set to <code>Number.POSITIVE_INFINITY</code>, the approximate depth test is never applied. <br/><br/> This setting only applies when a label's Label#disableDepthTestDistance value would otherwise allow depth testing—i.e., distance from the camera to the label is less than the label's Label#disableDepthTestDistance value.

---

threePointDepthTestDistance

threePointDepthTestDistance: number

The distance from the camera, within which, labels 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. When set to <code>0</code>, this feature is disabled and portions of a label behind terrain be clipped. <br/><br/> This setting only applies when a labels's Label#disableDepthTestDistance value would otherwise allow depth testing—i.e., distance from the camera to the label is less than the labels's Label#disableDepthTestDistance value.

方法

add()

add(options?: ConstructorOptions): Label

Creates and adds a label with the specified initial properties to the collection. The added label is returned so it can be modified or removed from the collection later.

参数

options?

ConstructorOptions

A template describing the label's properties as shown in Example 1.

返回

Label

The label that was added to the collection.

Examples

// 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',
});

---

remove()

remove(label: Label): boolean

Removes a label from the collection. Once removed, a label is no longer usable.

参数

label

Label

The label to remove.

返回

boolean

true if the label was removed; false if the label was not found in the collection.

示例

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

---

removeAll()

removeAll(): void

Removes all labels from the collection.

返回

void

示例

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

---

contains()

contains(label: Label): boolean

Check whether this collection contains a given label.

参数

label

Label

The label to check for.

返回

boolean

true if this collection contains the label, false otherwise.

---

get()

get(index: number): Label

Returns the label in the collection at the specified index. Indices are zero-based and increase as labels are added. Removing a label shifts all labels after it to the left, changing their indices. This function is commonly used with LabelCollection#length to iterate over all the labels in the collection.

参数

index

number

The zero-based index of the billboard.

返回

Label

The label at the specified index.

示例

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

---

isDestroyed()

isDestroyed(): boolean

Returns true if this object was destroyed; otherwise, false. <br /><br /> If this object was destroyed, it should not be used; calling any function other than <code>isDestroyed</code> will result in a DeveloperError exception.

返回

boolean

True if this object was destroyed; otherwise, false.

---

destroy()

destroy(): void

Destroys the WebGL resources held by this object. Destroying an object allows for deterministic release of WebGL resources, instead of relying on the garbage collector to destroy this object. <br /><br /> Once an object is destroyed, it should not be used; calling any function other than <code>isDestroyed</code> will result in a DeveloperError exception. Therefore, assign the return value (<code>undefined</code>) to the object as done in the example.

返回

void

示例

labels = labels && labels.destroy();

构造函数

构造函数

new LabelCollection(options?: { modelMatrix?: Matrix4; debugShowBoundingVolume?: boolean; scene?: Scene; blendOption?: BlendOption; show?: boolean; coarseDepthTestDistance?: number; threePointDepthTestDistance?: number; }): LabelCollection

参数

options?

modelMatrix?

Matrix4

debugShowBoundingVolume?

boolean

scene?

Scene

blendOption?

BlendOption

show?

boolean

coarseDepthTestDistance?

number

threePointDepthTestDistance?

number

返回

LabelCollection