Label

Methods

computeScreenSpacePosition

Computes the screen-space position of the label's origin, taking into account eye and pixel offsets. The screen space origin is the bottom, left corner of the canvas; x increases from left to right, and y increases from bottom to top.

Parameters:

Name	Type	Description
context	Context	The context.
frameState	FrameState	The same state object passed to LabelCollection#update.

Throws:

• DeveloperError : context is required.
• DeveloperError : frameState is required.

Returns:

Cartesian2 The screen-space position of the label.

Example

console.log(l.computeScreenSpacePosition(scene.getContext(), scene.getFrameState()).toString());

See:

• Label#setEyeOffset
• Label#setPixelOffset

equals

Determines if this label equals another label. Labels are equal if all their properties are equal. Labels in different collections can be equal.

Parameters:

Name	Type	Description
other	Label	The label to compare for equality.

Returns:

Boolean true if the labels are equal; otherwise, false.

getEyeOffset

Returns the 3D Cartesian offset applied to this label in eye coordinates.

Returns:

Cartesian3 The 3D Cartesian offset applied to this label in eye coordinates.

See:

• Label#setEyeOffset

getFillColor

Gets the fill color of this label.

See:

• Label#setFillColor
• HTML canvas 2D context fill and stroke styles

getFont

Gets the font used to draw this label. Fonts are specified using the same syntax as the CSS 'font' property.

See:

• Label#setFont
• HTML canvas 2D context text styles

getHorizontalOrigin

Returns the horizontal origin of this label.

Returns:

HorizontalOrigin The horizontal origin of this label.

See:

• Label#setHorizontalOrigin

getId

Returns the user-defined object returned when the label is picked.

Returns:

Object The user-defined object returned when the label is picked.

getOutlineColor

Gets the outline color of this label.

See:

• Label#setOutlineColor
• HTML canvas 2D context fill and stroke styles

getOutlineWidth

Gets the outline width of this label.

See:

• Label#setOutlineWidth
• HTML canvas 2D context fill and stroke styles

getPixelOffset

Returns the pixel offset from the origin of this label.

Returns:

Cartesian2 The pixel offset of this label.

See:

• Label#setPixelOffset

getPixelOffsetScaleByDistance

Returns the near and far pixel offset scaling properties of a Label based on the label's distance from the camera.

Returns:

NearFarScalar The near/far pixel offset scale values based on camera distance to the label

See:

• Label#setPixelOffsetScaleByDistance
• Label#setPixelOffset
• Label#getPixelOffset

getPosition

Returns the Cartesian position of this label.

Returns:

Cartesian3 The Cartesian position of this label.

See:

• Label#setPosition

getScale

Returns the uniform scale that is multiplied with the label's size in pixels.

Returns:

Number The scale used to size the label.

See:

• Label#setScale

getShow

Returns true if this label will be shown. Call Label#setShow to hide or show a label, instead of removing it and re-adding it to the collection.

Returns:

Boolean true if this label will be shown; otherwise, false.

See:

• Label#setShow

getStyle

Gets the style of this label.

See:

• Label#setStyle

getText

Gets the text of this label.

See:

• Label#setText

getTranslucencyByDistance

Returns the near and far translucency properties of a Label based on the label's distance from the camera.

Returns:

NearFarScalar The near/far translucency values based on camera distance to the billboard

See:

• Label#setTranslucencyByDistance

getVerticalOrigin

Returns the vertical origin of this label.

Returns:

VerticalOrigin The vertical origin of this label.

See:

• Label#setVerticalOrigin

isDestroyed

Returns true if this object was destroyed; otherwise, false.

If this object was destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception.

Returns:

Boolean True if this object was destroyed; otherwise, false.

setEyeOffset

Sets the 3D Cartesian offset applied to this label 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.

An eye offset is commonly used to arrange multiple label or objects at the same position, e.g., to arrange a label above its corresponding 3D model.

value can be either a Cartesian3 or an object literal with x, y, and z properties. A copy of value is made, so changing it after calling setEyeOffset does not affect the label's eye offset; an explicit call to setEyeOffset is required.

Below, the label 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.

l.setEyeOffset({ x : 0.0, y : 8000000.0, z : 0.0 });

Parameters:

Name	Type	Description
value	Cartesian3	The 3D Cartesian offset in eye coordinates.

Throws:

DeveloperError : value is required.

See:

• Label#getEyeOffset

setFillColor

Sets the fill color of this label.

Parameters:

Name	Type	Description
value	Color	The fill color.

Throws:

DeveloperError : value is required.

See:

• Label#getFillColor
• Label#setOutlineColor
• Label#setFont
• HTML canvas 2D context fill and stroke styles

setFont

Sets the font used to draw this label. Fonts are specified using the same syntax as the CSS 'font' property.

Parameters:

Name	Type	Description
value	String	The font.

Throws:

DeveloperError : value is required.

See:

• Label#getFont
• Label#setFillColor
• Label#setOutlineColor
• HTML canvas 2D context text styles

setHorizontalOrigin

Sets the horizontal origin of this label, which determines if the label is drawn to the left, center, or right of its position.

Parameters:

Name	Type	Description
value	HorizontalOrigin	The horizontal origin.

Throws:

DeveloperError : value is required.

Example

// Use a top, right origin
l.setHorizontalOrigin(HorizontalOrigin.RIGHT);
l.setVerticalOrigin(VerticalOrigin.TOP);

See:

• Label#getHorizontalOrigin
• Label#setVerticalOrigin

setOutlineColor

Sets the outline color of this label.

Parameters:

Name	Type	Description
value	Color	The fill color.

Throws:

DeveloperError : value is required.

See:

• Label#getOutlineColor
• Label#setFillColor
• Label#setFont
• HTML canvas 2D context fill and stroke styles

setOutlineWidth

Sets the outline width of this label.

Parameters:

Name	Type	Description
value	Number	The outline width.

Throws:

DeveloperError : value is required.

See:

• Label#getOutlineWidth
• Label#setFillColor
• Label#setFont
• HTML canvas 2D context fill and stroke styles

setPixelOffset

Sets the pixel offset in screen space from the origin of this label. This is commonly used to align multiple labels and billboards at the same position, e.g., an image and text. The screen space origin is the bottom, left corner of the canvas; x increases from left to right, and y increases from bottom to top.

value can be either a Cartesian2 or an object literal with x and y properties. A copy of value is made, so changing it after calling setPixelOffset does not affect the label's pixel offset; an explicit call to setPixelOffset is required.

default

l.setPixelOffset({ x : 25, y : -75 });

The label's origin is indicated by the yellow point.

Parameters:

Name	Type	Description
value	Cartesian2	The 2D Cartesian pixel offset.

Throws:

DeveloperError : value is required.

See:

• Label#getPixelOffset
• Billboard#setPixelOffset

setPixelOffsetScaleByDistance

Sets near and far pixel offset scaling properties of a Label based on the Label's distance from the camera. A label's pixel offset will be scaled between the NearFarScalar#nearValue and NearFarScalar#farValue while the camera distance falls within the upper and lower bounds of the specified NearFarScalar#near and NearFarScalar#far. Outside of these ranges the label's pixel offset scaling remains clamped to the nearest bound. If undefined, pixelOffsetScaleByDistance will be disabled.

Parameters:

Name	Type	Description
pixelOffsetScale	NearFarScalar	The configuration of near and far distances and their respective scaling factor to be applied to the pixelOffset

Throws:

DeveloperError : far distance must be greater than near distance.

Example

// Example 1.
// Set a label's pixel offset scale to 0.0 when the
// camera is 1500 meters from the label and scale pixel offset to 10.0 pixels
// in the y direction the camera distance approaches 8.0e6 meters.
text.setPixelOffset(new Cartesian2(0.0, 1.0);
text.setPixelOffsetScaleByDistance(new NearFarScalar(1.5e2, 0.0, 8.0e6, 10.0));

// Example 2.
// disable pixel offset by distance
text.setPixelOffsetScaleByDistance(undefined);

See:

• Label#getPixelOffsetScaleByDistance
• Label#setPixelOffset
• Label#getPixelOffset

setPosition

Sets the Cartesian position of this label.

As shown in the examples, value can be either a Cartesian3 or an object literal with x, y, and z properties. A copy of value is made, so changing it after calling setPosition does not affect the label's position; an explicit call to setPosition is required.

Parameters:

Name	Type	Description
value	Cartesian3	The Cartesian position.

Throws:

DeveloperError : value is required.

Example

// Example 1. Set a label's position using a Cartesian3.
l.setPosition(new Cartesian3(1.0, 2.0, 3.0));

//////////////////////////////////////////////////////////////////

// Example 2. Set a label's position using an object literal.
l.setPosition({
  x : 1.0,
  y : 2.0,
  z : 3.0
});

See:

• Label#getPosition

setScale

Sets the uniform scale that is multiplied with the label's size in pixels. A scale of 1.0 does not change the size of the label; a scale greater than 1.0 enlarges the label; a positive scale less than 1.0 shrinks the label.

Applying a large scale value may pixelate the label. To make text larger without pixelation, use a larger font size when calling Label#setFont instead.

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

Parameters:

Name	Type	Description
value	Number	The scale used to size the label.

Throws:

DeveloperError : value is required.

See:

• Label#getScale
• Label#setFont

setShow

Determines if this label will be shown. Call this to hide or show a label, instead of removing it and re-adding it to the collection.

Parameters:

Name	Type	Description
value	Boolean	Indicates if this label will be shown.

Throws:

DeveloperError : value is required.

See:

• Label#getShow

setStyle

Sets the style of this label.

Parameters:

Name	Type	Description
value	LabelStyle	The style.

Throws:

DeveloperError : value is required.

See:

• Label#getStyle
• Label#setOutlineColor
• Label#setFillColor

setText

Sets the text of this label.

Parameters:

Name	Type	Description
value	String	The text.

Throws:

DeveloperError : value is required.

See:

• Label#getText

setTranslucencyByDistance

Sets near and far translucency properties of a Label based on the Label's distance from the camera. A label's translucency will interpolate between the NearFarScalar#nearValue and NearFarScalar#farValue while the camera distance falls within the upper and lower bounds of the specified NearFarScalar#near and NearFarScalar#far. Outside of these ranges the label's translucency remains clamped to the nearest bound. If undefined, translucencyByDistance will be disabled.

Parameters:

Name	Type	Description
translucency	NearFarScalar	The configuration of near and far distances and their respective translucency values

Throws:

DeveloperError : far distance must be greater than near distance.

Example

// Example 1.
// Set a label's translucencyByDistance to 1.0 when the
// camera is 1500 meters from the label and disappear as
// the camera distance approaches 8.0e6 meters.
text.setTranslucencyByDistance(new NearFarScalar(1.5e2, 1.0, 8.0e6, 0.0));

// Example 2.
// disable translucency by distance
text.setTranslucencyByDistance(undefined);

See:

• Label#getTranslucencyByDistance

setVerticalOrigin

Sets the vertical origin of this label, which determines if the label is to the above, below, or at the center of its position.

Parameters:

Name	Type	Description
value	VerticalOrigin	The vertical origin.

Throws:

DeveloperError : value is required.

Example

// Use a top, right origin
l.setHorizontalOrigin(HorizontalOrigin.RIGHT);
l.setVerticalOrigin(VerticalOrigin.TOP);

See:

• Label#getVerticalOrigin
• Label#setHorizontalOrigin