CesiumGS · pjcozzi · Dec 8, 2016 · Nov 18, 2016 · Nov 23, 2016 · Nov 23, 2016
diff --git a/Apps/Sandcastle/gallery/CZML Billboard and Label.html b/Apps/Sandcastle/gallery/CZML Billboard and Label.html
@@ -42,19 +42,19 @@
     },
     "label" : {
         "fillColor" : {
-            "rgba" : [0, 255, 255, 255]
+            "rgba" : [255, 255, 255, 255]
         },
-        "font" : "11pt Lucida Console",
+        "font" : "12pt Lucida Console",
         "horizontalOrigin" : "LEFT",
-        "outlineColor" : {
-            "rgba":[0, 0, 0, 255]
-        },
-        "outlineWidth" : 2,
         "pixelOffset" : {
-            "cartesian2" : [12, 0]
+            "cartesian2" : [8, 0]
         },
-        "style" : "FILL_AND_OUTLINE",
-        "text" : "AGI"
+        "style" : "FILL",
+        "text" : "AGI",
+        "showBackground" : true,
+        "backgroundColor" : {
+            "rgba" : [112, 89, 57, 200]
+        }
     },
     "position" : {
         "cartesian":[
@@ -65,7 +65,7 @@
 
 var viewer = new Cesium.Viewer('cesiumContainer');
 viewer.dataSources.add(Cesium.CzmlDataSource.load(czml));
-  //Sandcastle_End
+//Sandcastle_End
     Sandcastle.finishedLoading();
 }
 if (typeof Cesium !== "undefined") {

diff --git a/Apps/Sandcastle/gallery/Ground Clamping.html b/Apps/Sandcastle/gallery/Ground Clamping.html
@@ -10,10 +10,10 @@
     <script type="text/javascript" src="../Sandcastle-header.js"></script>
     <script type="text/javascript" src="../../../ThirdParty/requirejs-2.1.20/require.js"></script>
     <script type="text/javascript">
-        require.config({
-            baseUrl : '../../../Source',
-            waitSeconds : 60
-        });
+    require.config({
+        baseUrl : '../../../Source',
+        waitSeconds : 60
+    });
     </script>
 </head>
 <body class="sandcastle-loading" data-sandcastle-bucket="bucket-requirejs.html">
@@ -29,8 +29,8 @@
     <div id="sampleButtons"></div>
 </div>
 <script id="cesium_sandcastle_script">
-    function startup(Cesium) {
-        'use strict';
+function startup(Cesium) {
+    'use strict';
 //Sandcastle_Begin
 var viewer = new Cesium.Viewer('cesiumContainer');
 var cesiumTerrainProviderMeshes = new Cesium.CesiumTerrainProvider({
@@ -44,7 +44,7 @@
     //
     // To clamp points or billboards set the heightReference to CLAMP_TO_GROUND or RELATIVE_TO_GROUND
     //
-    text : 'Draw Points',
+    text : 'Draw Point with Label',
     onselect : function() {
         var e = viewer.entities.add({
             position : Cesium.Cartesian3.fromDegrees(-122.1958, 46.1915),
@@ -54,6 +54,17 @@
                 outlineColor : Cesium.Color.YELLOW,
                 outlineWidth : 3,
                 heightReference : Cesium.HeightReference.CLAMP_TO_GROUND
+            },
+            label : {
+                text : 'Clamped to ground',
+                font : '14pt sans-serif',
+                heightReference : Cesium.HeightReference.CLAMP_TO_GROUND,
+                horizontalOrigin : Cesium.HorizontalOrigin.LEFT,
+                verticalOrigin : Cesium.VerticalOrigin.BASELINE,
+                fillColor : Cesium.Color.BLACK,
+                showBackground : true,
+                backgroundColor : new Cesium.Color(1, 1, 1, 0.7),
+                backgroundPadding : new Cesium.Cartesian2(8, 4)
             }
         });
 
@@ -130,13 +141,13 @@
 };
 
 //Sandcastle_End
-        Sandcastle.finishedLoading();
-    }
-    if (typeof Cesium !== "undefined") {
-        startup(Cesium);
-    } else if (typeof require === "function") {
-        require(["Cesium"], startup);
-    }
+    Sandcastle.finishedLoading();
+}
+if (typeof Cesium !== "undefined") {
+    startup(Cesium);
+} else if (typeof require === "function") {
+    require(["Cesium"], startup);
+}
 </script>
 </body>
 </html>
diff --git a/Apps/Sandcastle/gallery/Labels.html b/Apps/Sandcastle/gallery/Labels.html
@@ -64,6 +64,7 @@
     });
 
     entity.label.scale = 2.0;
+    entity.label.showBackground = true;
 }
 
 function offsetByDistance() {
@@ -80,6 +81,7 @@
             label : {
                 text : 'Label on top of scaling billboard',
                 font : '20px sans-serif',
+                showBackground : true,
                 horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
                 pixelOffset : new Cesium.Cartesian2(0.0, -image.height),
                 pixelOffsetScaleByDistance : new Cesium.NearFarScalar(1.5e2, 3.0, 1.5e7, 0.5)

diff --git a/Apps/Sandcastle/gallery/Terrain.html b/Apps/Sandcastle/gallery/Terrain.html
@@ -148,11 +148,14 @@
             },
             label : {
                 text : position.height.toFixed(1),
+                font : '10pt monospace',
                 horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
-                scale : 0.3,
                 pixelOffset : new Cesium.Cartesian2(0, -14),
-                fillColor : Cesium.Color.RED,
-                outlineColor : Cesium.Color.WHITE
+                fillColor : Cesium.Color.BLACK,
+                outlineColor : Cesium.Color.BLACK,
+                showBackground : true,
+                backgroundColor : new Cesium.Color(0.9, 0.9, 0.9, 0.7),
+                backgroundPadding : new Cesium.Cartesian2(4, 3)
             }
         });
     }

diff --git a/Apps/Sandcastle/gallery/development/Labels.html b/Apps/Sandcastle/gallery/development/Labels.html
@@ -77,19 +77,27 @@
     labels.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
     labels.add({
         position : new Cesium.Cartesian3(0.0, 0.0, 0.0),
-        text     : 'Center'
+        text : 'Center',
+        font : '13pt sans-serif',
+        showBackground : true
     });
     labels.add({
         position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0),
-        text     : 'East'
+        text : 'East',
+        font : '13pt sans-serif',
+        showBackground : true
     });
     labels.add({
         position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0),
-        text     : 'North'
+        text : 'North',
+        font : '13pt sans-serif',
+        showBackground : true
     });
     labels.add({
         position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0),
-        text     : 'Up'
+        text : 'Up',
+        font : '13pt sans-serif',
+        showBackground : true
     });
 }
 
@@ -108,8 +116,9 @@
         var labels = scene.primitives.add(new Cesium.LabelCollection());
         labels.add({
             position : Cesium.Cartesian3.fromDegrees(-75.1641667, 39.9522222),
-            text     : 'Label on top of scaling billboard',
+            text : 'Label on top of scaling billboard',
             font : '20px sans-serif',
+            showBackground : true,
             horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
             pixelOffset : new Cesium.Cartesian2(0.0, -image.height),
             pixelOffsetScaleByDistance : new Cesium.NearFarScalar(1.5e2, 3.0, 1.5e7, 0.5)

diff --git a/CHANGES.md b/CHANGES.md
@@ -4,6 +4,8 @@ Change Log
 ### 1.29 - 2017-01-02
 
 * Added the ability to blend a `Model` with a color/translucency. Added `color`, `colorBlendMode`, and `colorBlendAmount` properties to `Model`, `ModelGraphics`, and CZML. Added `ColorBlendMode` enum. [#4547](https://github.com/AnalyticalGraphicsInc/cesium/pull/4547)
+* Added new `Label` properties `showBackground`, `backgroundColor`, and `backgroundPadding` to the primitive, Entity, and CZML layers.
+* Added new enum `VerticalOrigin.BASELINE`.  Previously, `VerticalOrigin.BOTTOM` would sometimes align to the baseline depending on the contents of a label.
 * Fixed tooltips for gallery thumbnails in Sandcastle [#4702](https://github.com/AnalyticalGraphicsInc/cesium/pull/4702)
 * Fixed `Rectangle.union` to correctly account for rectangles that cross the IDL [#4732](https://github.com/AnalyticalGraphicsInc/cesium/pull/4732).
 * Fixed texture rotation for `RectangleGeometry` [#2737](https://github.com/AnalyticalGraphicsInc/cesium/issues/2737)

diff --git a/Documentation/Images/Billboard.setVerticalOrigin.png b/Documentation/Images/Billboard.setVerticalOrigin.png
diff --git a/Source/DataSources/CzmlDataSource.js b/Source/DataSources/CzmlDataSource.js
@@ -1378,6 +1378,9 @@ define([
         processPacketData(String, label, 'font', labelData.font, interval, sourceUri, entityCollection);
         processPacketData(LabelStyle, label, 'style', labelData.style, interval, sourceUri, entityCollection);
         processPacketData(Number, label, 'scale', labelData.scale, interval, sourceUri, entityCollection);
+        processPacketData(Boolean, label, 'showBackground', labelData.showBackground, interval, sourceUri, entityCollection);
+        processPacketData(Color, label, 'backgroundColor', labelData.backgroundColor, interval, sourceUri, entityCollection);
+        processPacketData(Cartesian2, label, 'backgroundPadding', labelData.backgroundPadding, interval, sourceUri, entityCollection);
         processPacketData(Cartesian2, label, 'pixelOffset', labelData.pixelOffset, interval, sourceUri, entityCollection);
         processPacketData(Cartesian3, label, 'eyeOffset', labelData.eyeOffset, interval, sourceUri, entityCollection);
         processPacketData(HorizontalOrigin, label, 'horizontalOrigin', labelData.horizontalOrigin, interval, sourceUri, entityCollection);

diff --git a/Source/DataSources/EntityCluster.js b/Source/DataSources/EntityCluster.js
@@ -148,7 +148,7 @@ define([
         cluster.label.show = true;
         cluster.label.text = numPoints.toLocaleString();
         cluster.billboard.position = cluster.label.position = cluster.point.position = position;
-        
+
         entityCluster._clusterEvent.raiseEvent(ids, cluster);
     }
 

diff --git a/Source/DataSources/LabelGraphics.js b/Source/DataSources/LabelGraphics.js
@@ -35,6 +35,9 @@ define([
      * @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.show=true] A boolean Property specifying the visibility of the label.
+     * @param {Property} [options.showBackground=true] 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.scale=1.0] A numeric Property specifying the scale to apply to the text.
      * @param {Property} [options.horizontalOrigin=HorizontalOrigin.CENTER] A Property specifying the {@link HorizontalOrigin}.
      * @param {Property} [options.verticalOrigin=VerticalOrigin.CENTER] A Property specifying the {@link VerticalOrigin}.
@@ -74,6 +77,12 @@ define([
         this._scaleSubscription = undefined;
         this._show = undefined;
         this._showSubscription = undefined;
+        this._showBackground = undefined;
+        this._showBackgroundSubscription = undefined;
+        this._backgroundColor = undefined;
+        this._backgroundColorSubscription = undefined;
+        this._backgroundPadding = undefined;
+        this._backgroundPaddingSubscription = undefined;
         this._translucencyByDistance = undefined;
         this._translucencyByDistanceSubscription = undefined;
         this._pixelOffsetScaleByDistance = undefined;
@@ -232,6 +241,31 @@ define([
          */
         show : createPropertyDescriptor('show'),
 
+        /**
+         * 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 {@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
@@ -279,6 +313,9 @@ define([
         result.fillColor = this.fillColor;
         result.outlineColor = this.outlineColor;
         result.outlineWidth = this.outlineWidth;
+        result.showBackground = this.showBackground;
+        result.backgroundColor = this.backgroundColor;
+        result.backgroundPadding = this.backgroundPadding;
         result.scale = this.scale;
         result.horizontalOrigin = this.horizontalOrigin;
         result.verticalOrigin = this.verticalOrigin;
@@ -311,6 +348,9 @@ define([
         this.fillColor = defaultValue(this.fillColor, source.fillColor);
         this.outlineColor = defaultValue(this.outlineColor, source.outlineColor);
         this.outlineWidth = defaultValue(this.outlineWidth, source.outlineWidth);
+        this.showBackground = defaultValue(this.showBackground, source.showBackground);
+        this.backgroundColor = defaultValue(this.backgroundColor, source.backgroundColor);
+        this.backgroundPadding = defaultValue(this.backgroundPadding, source.backgroundPadding);
         this.scale = defaultValue(this.scale, source.scale);
         this.horizontalOrigin = defaultValue(this.horizontalOrigin, source.horizontalOrigin);
         this.verticalOrigin = defaultValue(this.verticalOrigin, source.verticalOrigin);

diff --git a/Source/DataSources/LabelVisualizer.js b/Source/DataSources/LabelVisualizer.js
@@ -41,6 +41,9 @@ define([
     var defaultFillColor = Color.WHITE;
     var defaultOutlineColor = Color.BLACK;
     var defaultOutlineWidth = 1.0;
+    var defaultShowBackground = false;
+    var defaultBackgroundColor = new Color(0.165, 0.165, 0.165, 0.8);
+    var defaultBackgroundPadding = new Cartesian2(7, 5);
     var defaultPixelOffset = Cartesian2.ZERO;
     var defaultEyeOffset = Cartesian3.ZERO;
     var defaultHeightReference = HeightReference.NONE;
@@ -50,6 +53,8 @@ define([
     var position = new Cartesian3();
     var fillColor = new Color();
     var outlineColor = new Color();
+    var backgroundColor = new Color();
+    var backgroundPadding = new Cartesian2();
     var eyeOffset = new Cartesian3();
     var pixelOffset = new Cartesian2();
     var translucencyByDistance = new NearFarScalar();
@@ -146,6 +151,9 @@ define([
             label.fillColor = Property.getValueOrDefault(labelGraphics._fillColor, time, defaultFillColor, fillColor);
             label.outlineColor = Property.getValueOrDefault(labelGraphics._outlineColor, time, defaultOutlineColor, outlineColor);
             label.outlineWidth = Property.getValueOrDefault(labelGraphics._outlineWidth, time, defaultOutlineWidth);
+            label.showBackground = Property.getValueOrDefault(labelGraphics._showBackground, time, defaultShowBackground);
+            label.backgroundColor = Property.getValueOrDefault(labelGraphics._backgroundColor, time, defaultBackgroundColor, backgroundColor);
+            label.backgroundPadding = Property.getValueOrDefault(labelGraphics._backgroundPadding, time, defaultBackgroundPadding, backgroundPadding);
             label.pixelOffset = Property.getValueOrDefault(labelGraphics._pixelOffset, time, defaultPixelOffset, pixelOffset);
             label.eyeOffset = Property.getValueOrDefault(labelGraphics._eyeOffset, time, defaultEyeOffset, eyeOffset);
             label.heightReference = Property.getValueOrDefault(labelGraphics._heightReference, time, defaultHeightReference);

diff --git a/Source/Scene/Billboard.js b/Source/Scene/Billboard.js
@@ -194,6 +194,7 @@ define([
          * of removing it and re-adding it to the collection.
          * @memberof Billboard.prototype
          * @type {Boolean}
+         * @default true
          */
         show : {
             get : function() {
@@ -468,7 +469,7 @@ define([
 
         /**
          * Gets or sets the horizontal origin of this billboard, which determines if the billboard is
-         * to the left, center, or right of its position.
+         * to the left, center, or right of its anchor position.
          * <br /><br />
          * <div align='center'>
          * <img src='images/Billboard.setHorizontalOrigin.png' width='400' height='300' /><br />
@@ -500,10 +501,10 @@ define([
 
         /**
          * Gets or sets the vertical origin of this billboard, which determines if the billboard is
-         * to the above, below, or at the center of its position.
+         * to the above, below, or at the center of its anchor position.
          * <br /><br />
          * <div align='center'>
-         * <img src='images/Billboard.setVerticalOrigin.png' width='400' height='300' /><br />
+         * <img src='images/Billboard.setVerticalOrigin.png' width='695' height='175' /><br />
          * </div>
          * @memberof Billboard.prototype
          * @type {VerticalOrigin}
@@ -1132,9 +1133,7 @@ define([
         return SceneTransforms.computeActualWgs84Position(frameState, tempCartesian3);
     };
 
-    var scratchCartesian2 = new Cartesian2();
     var scratchCartesian3 = new Cartesian3();
-    var scratchComputePixelOffset = new Cartesian2();
 
     // This function is basically a stripped-down JavaScript version of BillboardCollectionVS.glsl
     Billboard._computeScreenSpacePosition = function(modelMatrix, position, eyeOffset, pixelOffset, scene, result) {
@@ -1148,10 +1147,7 @@ define([
         }
 
         // Apply pixel offset
-        pixelOffset = Cartesian2.clone(pixelOffset, scratchComputePixelOffset);
-        var po = Cartesian2.multiplyByScalar(pixelOffset, scene.context.uniformState.resolutionScale, scratchCartesian2);
-        positionWC.x += po.x;
-        positionWC.y += po.y;
+        Cartesian2.add(positionWC, pixelOffset, positionWC);
 
         return positionWC;
     };
@@ -1227,7 +1223,7 @@ define([
         }
 
         var y = screenSpacePosition.y;
-        if (billboard.verticalOrigin === VerticalOrigin.TOP) {
+        if (billboard.verticalOrigin === VerticalOrigin.BOTTOM || billboard.verticalOrigin === VerticalOrigin.BASELINE) {
             y -= height;
         } else if (billboard.verticalOrigin === VerticalOrigin.CENTER) {
             y -= height * 0.5;