import defaultValue from '../Core/defaultValue.js'; import defined from '../Core/defined.js'; import defineProperties from '../Core/defineProperties.js'; import DeveloperError from '../Core/DeveloperError.js'; import Event from '../Core/Event.js'; import createPropertyDescriptor from './createPropertyDescriptor.js'; /** * Describes a two dimensional label located at the position of the containing {@link Entity}. *

*

*
* Example labels *
*

* * @alias LabelGraphics * @constructor * * @param {Object} [options] Object with the following properties: * @param {Property} [options.show=true] A boolean Property specifying the visibility of the label. * @param {Property} [options.text] A Property specifying the text. Explicit newlines '\n' are supported. * @param {Property} [options.font='30px sans-serif'] A Property specifying the CSS font. * @param {Property} [options.style=LabelStyle.FILL] A Property specifying the {@link LabelStyle}. * @param {Property} [options.scale=1.0] A numeric Property specifying the scale to apply to the text. * @param {Property} [options.showBackground=false] A boolean Property specifying the visibility of the background behind the label. * @param {Property} [options.backgroundColor=new Color(0.165, 0.165, 0.165, 0.8)] A Property specifying the background {@link Color}. * @param {Property} [options.backgroundPadding=new Cartesian2(7, 5)] A {@link Cartesian2} Property specifying the horizontal and vertical background padding in pixels. * @param {Property} [options.pixelOffset=Cartesian2.ZERO] A {@link Cartesian2} Property specifying the pixel offset. * @param {Property} [options.eyeOffset=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the eye offset. * @param {Property} [options.horizontalOrigin=HorizontalOrigin.CENTER] A Property specifying the {@link HorizontalOrigin}. * @param {Property} [options.verticalOrigin=VerticalOrigin.CENTER] A Property specifying the {@link VerticalOrigin}. * @param {Property} [options.heightReference=HeightReference.NONE] A Property specifying what the height is relative to. * @param {Property} [options.fillColor=Color.WHITE] A Property specifying the fill {@link Color}. * @param {Property} [options.outlineColor=Color.BLACK] A Property specifying the outline {@link Color}. * @param {Property} [options.outlineWidth=1.0] A numeric Property specifying the outline width. * @param {Property} [options.translucencyByDistance] A {@link NearFarScalar} Property used to set translucency based on distance from the camera. * @param {Property} [options.pixelOffsetScaleByDistance] A {@link NearFarScalar} Property used to set pixelOffset based on distance from the camera. * @param {Property} [options.scaleByDistance] A {@link NearFarScalar} Property used to set scale based on distance from the camera. * @param {Property} [options.distanceDisplayCondition] A Property specifying at what distance from the camera that this label will be displayed. * @param {Property} [options.disableDepthTestDistance] A Property specifying the distance from the camera at which to disable the depth test to. * * @demo {@link https://sandcastle.cesium.com/index.html?src=Labels.html|Cesium Sandcastle Labels Demo} */ function LabelGraphics(options) { this._definitionChanged = new Event(); this._show = undefined; this._showSubscription = undefined; this._text = undefined; this._textSubscription = undefined; this._font = undefined; this._fontSubscription = undefined; this._style = undefined; this._styleSubscription = undefined; this._scale = undefined; this._scaleSubscription = undefined; this._showBackground = undefined; this._showBackgroundSubscription = undefined; this._backgroundColor = undefined; this._backgroundColorSubscription = undefined; this._backgroundPadding = undefined; this._backgroundPaddingSubscription = undefined; this._pixelOffset = undefined; this._pixelOffsetSubscription = undefined; this._eyeOffset = undefined; this._eyeOffsetSubscription = undefined; this._horizontalOrigin = undefined; this._horizontalOriginSubscription = undefined; this._verticalOrigin = undefined; this._verticalOriginSubscription = undefined; this._heightReference = undefined; this._heightReferenceSubscription = undefined; this._fillColor = undefined; this._fillColorSubscription = undefined; this._outlineColor = undefined; this._outlineColorSubscription = undefined; this._outlineWidth = undefined; this._outlineWidthSubscription = undefined; this._translucencyByDistance = undefined; this._translucencyByDistanceSubscription = undefined; this._pixelOffsetScaleByDistance = undefined; this._pixelOffsetScaleByDistanceSubscription = undefined; this._scaleByDistance = undefined; this._scaleByDistanceSubscription = undefined; this._distanceDisplayCondition = undefined; this._distanceDisplayConditionSubscription = undefined; this._disableDepthTestDistance = undefined; this._disableDepthTestDistanceSubscription = undefined; this.merge(defaultValue(options, defaultValue.EMPTY_OBJECT)); } defineProperties(LabelGraphics.prototype, { /** * Gets the event that is raised whenever a property or sub-property is changed or modified. * @memberof LabelGraphics.prototype * * @type {Event} * @readonly */ definitionChanged : { get : function() { return this._definitionChanged; } }, /** * Gets or sets the boolean Property specifying the visibility of the label. * @memberof LabelGraphics.prototype * @type {Property} */ show : createPropertyDescriptor('show'), /** * Gets or sets the string Property specifying the text of the label. * Explicit newlines '\n' are supported. * @memberof LabelGraphics.prototype * @type {Property} */ text : createPropertyDescriptor('text'), /** * Gets or sets the string Property specifying the font in CSS syntax. * @memberof LabelGraphics.prototype * @type {Property} * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font|CSS font on MDN} */ font : createPropertyDescriptor('font'), /** * Gets or sets the Property specifying the {@link LabelStyle}. * @memberof LabelGraphics.prototype * @type {Property} */ style : createPropertyDescriptor('style'), /** * Gets or sets the numeric Property specifying the uniform scale to apply to the image. * A scale greater than 1.0 enlarges the label while a scale less than 1.0 shrinks it. *

*

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

* @memberof LabelGraphics.prototype * @type {Property} * @default 1.0 */ scale : createPropertyDescriptor('scale'), /** * Gets or sets the boolean Property specifying the visibility of the background behind the label. * @memberof LabelGraphics.prototype * @type {Property} * @default false */ showBackground : createPropertyDescriptor('showBackground'), /** * Gets or sets the Property specifying the background {@link Color}. * @memberof LabelGraphics.prototype * @type {Property} * @default new Color(0.165, 0.165, 0.165, 0.8) */ backgroundColor : createPropertyDescriptor('backgroundColor'), /** * Gets or sets the {@link Cartesian2} Property specifying the label's horizontal and vertical * background padding in pixels. * @memberof LabelGraphics.prototype * @type {Property} * @default new Cartesian2(7, 5) */ backgroundPadding : createPropertyDescriptor('backgroundPadding'), /** * Gets or sets the {@link Cartesian2} Property specifying the label's pixel offset in screen space * from the origin of this label. This is commonly used to align multiple labels and labels at * the same position, e.g., an image and text. The screen space origin is the top, left corner of the * canvas; x increases from left to right, and y increases from top to bottom. *

*

* * * *
default
l.pixeloffset = new Cartesian2(25, 75);
* The label's origin is indicated by the yellow point. *
*

* @memberof LabelGraphics.prototype * @type {Property} * @default Cartesian2.ZERO */ pixelOffset : createPropertyDescriptor('pixelOffset'), /** * Gets or sets the {@link Cartesian3} Property specifying the label's offset 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. *

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

* 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.eyeOffset = new Cartesian3(0.0, 8000000.0, 0.0);

*
*

* @memberof LabelGraphics.prototype * @type {Property} * @default Cartesian3.ZERO */ eyeOffset : createPropertyDescriptor('eyeOffset'), /** * Gets or sets the Property specifying the {@link HorizontalOrigin}. * @memberof LabelGraphics.prototype * @type {Property} */ horizontalOrigin : createPropertyDescriptor('horizontalOrigin'), /** * Gets or sets the Property specifying the {@link VerticalOrigin}. * @memberof LabelGraphics.prototype * @type {Property} */ verticalOrigin : createPropertyDescriptor('verticalOrigin'), /** * Gets or sets the Property specifying the {@link HeightReference}. * @memberof LabelGraphics.prototype * @type {Property} * @default HeightReference.NONE */ heightReference : createPropertyDescriptor('heightReference'), /** * Gets or sets the Property specifying the fill {@link Color}. * @memberof LabelGraphics.prototype * @type {Property} */ fillColor : createPropertyDescriptor('fillColor'), /** * Gets or sets the Property specifying the outline {@link Color}. * @memberof LabelGraphics.prototype * @type {Property} */ outlineColor : createPropertyDescriptor('outlineColor'), /** * Gets or sets the numeric Property specifying the outline width. * @memberof LabelGraphics.prototype * @type {Property} */ outlineWidth : createPropertyDescriptor('outlineWidth'), /** * Gets or sets {@link NearFarScalar} Property specifying the translucency of the label based on the distance from the camera. * A label's translucency will interpolate between the {@link NearFarScalar#nearValue} and * {@link NearFarScalar#farValue} while the camera distance falls within the upper and lower bounds * of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}. * Outside of these ranges the label's translucency remains clamped to the nearest bound. * @memberof LabelGraphics.prototype * @type {Property} */ translucencyByDistance : createPropertyDescriptor('translucencyByDistance'), /** * Gets or sets {@link NearFarScalar} Property specifying the pixel offset of the label based on the distance from the camera. * A label's pixel offset will interpolate between the {@link NearFarScalar#nearValue} and * {@link NearFarScalar#farValue} while the camera distance falls within the upper and lower bounds * of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}. * Outside of these ranges the label's pixel offset remains clamped to the nearest bound. * @memberof LabelGraphics.prototype * @type {Property} */ pixelOffsetScaleByDistance : createPropertyDescriptor('pixelOffsetScaleByDistance'), /** * Gets or sets near and far scaling properties of a Label based on the label's distance from the camera. * A label's scale will interpolate between the {@link NearFarScalar#nearValue} and * {@link NearFarScalar#farValue} while the camera distance falls within the upper and lower bounds * of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}. * Outside of these ranges the label's scale remains clamped to the nearest bound. If undefined, * scaleByDistance will be disabled. * @memberof LabelGraphics.prototype * @type {Property} */ scaleByDistance : createPropertyDescriptor('scaleByDistance'), /** * Gets or sets the {@link DistanceDisplayCondition} Property specifying at what distance from the camera that this label will be displayed. * @memberof LabelGraphics.prototype * @type {Property} */ distanceDisplayCondition : createPropertyDescriptor('distanceDisplayCondition'), /** * Gets or sets the distance from the camera at which to disable the depth test to, for example, prevent clipping against terrain. * When set to zero, the depth test is always applied. When set to Number.POSITIVE_INFINITY, the depth test is never applied. * @memberof LabelGraphics.prototype * @type {Property} */ disableDepthTestDistance : createPropertyDescriptor('disableDepthTestDistance') }); /** * Duplicates this instance. * * @param {LabelGraphics} [result] The object onto which to store the result. * @returns {LabelGraphics} The modified result parameter or a new instance if one was not provided. */ LabelGraphics.prototype.clone = function(result) { if (!defined(result)) { return new LabelGraphics(this); } result.show = this.show; result.text = this.text; result.font = this.font; result.style = this.style; result.scale = this.scale; result.showBackground = this.showBackground; result.backgroundColor = this.backgroundColor; result.backgroundPadding = this.backgroundPadding; result.pixelOffset = this.pixelOffset; result.eyeOffset = this.eyeOffset; result.horizontalOrigin = this.horizontalOrigin; result.verticalOrigin = this.verticalOrigin; result.heightReference = this.heightReference; result.fillColor = this.fillColor; result.outlineColor = this.outlineColor; result.outlineWidth = this.outlineWidth; result.translucencyByDistance = this.translucencyByDistance; result.pixelOffsetScaleByDistance = this.pixelOffsetScaleByDistance; result.scaleByDistance = this.scaleByDistance; result.distanceDisplayCondition = this.distanceDisplayCondition; result.disableDepthTestDistance = this.disableDepthTestDistance; return result; }; /** * Assigns each unassigned property on this object to the value * of the same property on the provided source object. * * @param {LabelGraphics} source The object to be merged into this object. */ LabelGraphics.prototype.merge = function(source) { //>>includeStart('debug', pragmas.debug); if (!defined(source)) { throw new DeveloperError('source is required.'); } //>>includeEnd('debug'); this.show = defaultValue(this.show, source.show); this.text = defaultValue(this.text, source.text); this.font = defaultValue(this.font, source.font); this.style = defaultValue(this.style, source.style); this.scale = defaultValue(this.scale, source.scale); this.showBackground = defaultValue(this.showBackground, source.showBackground); this.backgroundColor = defaultValue(this.backgroundColor, source.backgroundColor); this.backgroundPadding = defaultValue(this.backgroundPadding, source.backgroundPadding); this.pixelOffset = defaultValue(this.pixelOffset, source.pixelOffset); this.eyeOffset = defaultValue(this.eyeOffset, source.eyeOffset); this.horizontalOrigin = defaultValue(this.horizontalOrigin, source.horizontalOrigin); this.verticalOrigin = defaultValue(this.verticalOrigin, source.verticalOrigin); this.heightReference = defaultValue(this.heightReference, source.heightReference); this.fillColor = defaultValue(this.fillColor, source.fillColor); this.outlineColor = defaultValue(this.outlineColor, source.outlineColor); this.outlineWidth = defaultValue(this.outlineWidth, source.outlineWidth); this.translucencyByDistance = defaultValue(this.translucencyByDistance, source.translucencyByDistance); this.pixelOffsetScaleByDistance = defaultValue(this.pixelOffsetScaleByDistance, source.pixelOffsetScaleByDistance); this.scaleByDistance = defaultValue(this.scaleByDistance, source.scaleByDistance); this.distanceDisplayCondition = defaultValue(this.distanceDisplayCondition, source.distanceDisplayCondition); this.disableDepthTestDistance = defaultValue(this.disableDepthTestDistance, source.disableDepthTestDistance); }; export default LabelGraphics;