CesiumGS · mramato · Jun 29, 2016 · Apr 24, 2015 · Apr 24, 2015 · Apr 29, 2015
diff --git a/Apps/Sandcastle/gallery/Ground Clamping.html b/Apps/Sandcastle/gallery/Ground Clamping.html
@@ -0,0 +1,142 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no">
+    <meta name="description" content="Clamp primitives to the terrain.">
+    <meta name="cesium-sandcastle-labels" content="Tutorials, Showcases">
+    <title>Cesium Demo</title>
+    <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
+        });
+    </script>
+</head>
+<body class="sandcastle-loading" data-sandcastle-bucket="bucket-requirejs.html">
+<style>
+    @import url(../templates/bucket.css);
+</style>
+<div id="cesiumContainer" class="fullSize"></div>
+<div id="loadingOverlay"><h1>Loading...</h1></div>
+<div id="toolbar">
+    <div id="terrainMenu"></div>
+    <div id="zoomButtons"></div>
+    <div id="toggleLighting"></div>
+    <div id="sampleButtons"></div>
+</div>
+<script id="cesium_sandcastle_script">
+    function startup(Cesium) {
+        'use strict';
+//Sandcastle_Begin
+var viewer = new Cesium.Viewer('cesiumContainer');
+var cesiumTerrainProviderMeshes = new Cesium.CesiumTerrainProvider({
+    url : 'https://assets.agi.com/stk-terrain/world',
+    requestWaterMask : true,
+    requestVertexNormals : true
+});
+viewer.terrainProvider = cesiumTerrainProviderMeshes;
+
+Sandcastle.addDefaultToolbarMenu([{
+    //
+    // To clamp points or billboards set the heightReference to CLAMP_TO_GROUND or RELATIVE_TO_GROUND
+    //
+    text : 'Draw Points',
+    onselect : function() {
+        var e = viewer.entities.add({
+            position : Cesium.Cartesian3.fromDegrees(-122.1958, 46.1915),
+            point : {
+                color : Cesium.Color.SKYBLUE,
+                pixelSize : 10,
+                outlineColor : Cesium.Color.YELLOW,
+                outlineWidth : 3,
+                heightReference : Cesium.HeightReference.CLAMP_TO_GROUND
+            }
+        });
+
+        viewer.trackedEntity = e;
+    }
+}, {
+    text : 'Draw Billboard',
+    onselect : function() {
+        var e = viewer.entities.add({
+            position : Cesium.Cartesian3.fromDegrees(-122.1958, 46.1915),
+            billboard : {
+                image : '../images/facility.gif',
+                heightReference : Cesium.HeightReference.CLAMP_TO_GROUND
+            }
+        });
+
+        viewer.trackedEntity = e;
+    }
+}, {
+    //
+    // Corridors, polygons and rectangles will be clamped automatically if they are filled with a constant color and
+    // has no height or extruded height.
+    // NOTE: Setting height to 0 will disable clamping.
+    //
+    text : 'Draw Corridor',
+    onselect : function() {
+        var e = viewer.entities.add({
+            corridor : {
+                positions : Cesium.Cartesian3.fromDegreesArray([
+                    -122.19, 46.1914,
+                    -122.21, 46.21,
+                    -122.23, 46.21
+                ]),
+                width : 2000.0,
+                material : Cesium.Color.GREEN.withAlpha(0.5)
+            }
+        });
+
+        viewer.trackedEntity = e;
+    }
+}, {
+    text : 'Draw Polygon',
+    onselect : function() {
+        var e = viewer.entities.add({
+            polygon : {
+                hierarchy : {
+                    positions : [new Cesium.Cartesian3(-2358138.847340281, -3744072.459541374, 4581158.5714175375),
+                                 new Cesium.Cartesian3(-2357231.4925370603, -3745103.7886602185, 4580702.9757762635),
+                                 new Cesium.Cartesian3(-2355912.902205431, -3744249.029778454, 4582402.154378103),
+                                 new Cesium.Cartesian3(-2357208.0209552636, -3743553.4420488174, 4581961.863286629)]
+                },
+                material : Cesium.Color.BLUE.withAlpha(0.5)
+            }
+        });
+
+        viewer.trackedEntity = e;
+    }
+}, {
+    text : 'Draw Rectangle',
+    onselect : function() {
+        var e = viewer.entities.add({
+            rectangle : {
+                coordinates : Cesium.Rectangle.fromDegrees(-122.3, 46.0, -122.0, 46.3),
+                material : Cesium.Color.RED.withAlpha(0.5)
+            }
+        });
+
+        viewer.trackedEntity = e;
+    }
+}], 'zoomButtons');
+
+Sandcastle.reset = function () {
+    viewer.entities.removeAll();
+};
+
+//Sandcastle_End
+        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/Ground Clamping.jpg b/Apps/Sandcastle/gallery/Ground Clamping.jpg
diff --git a/CHANGES.md b/CHANGES.md
@@ -3,17 +3,30 @@ Change Log
 
 ### 1.23 - 2016-07-01
 
+* Breaking changes
+    * `GroundPrimitive.initializeTerrainHeights()` must be called and have the returned promise resolve before a `GroundPrimitive` can be added syncronously.
+* Added entities on terrain
+    * Added `heightReference` property to point, billboard and model entities that would allow them to be rendered relative to terrain.
+    * Changed corridor, ellipse, polygon and rectangle entities to conform to terrain by using a `GroundPrimitive` if it's material is a `ColorMaterialProperty` and it doesn't have a `height` or `extrudedHeight`. Geometry that has any other type of material won't be drawn on terrain.
+    * `KMLDataSource`
+      * Point and model features will always respect `altitudeMode`.
+      * Adds an option `clampToGround` that when set to true will clamp `Polygon`, `LineString` and `LinearRing` features to the ground if their `altitudeMode` is `clampToGround`. For this case, lines use a corridor instead of a polyline.
+    * `GeoJsonDataSource`
+      * Points with a height will be drawn at that height, otherwise they will be clamped to the ground.
+      * Adds an option `clampToGround` that when set to true will clamp `Polygon` and `LineString` features to the ground. For this case, lines use a corridor instead of a polyline.
+    * Added `Ground Clamping` example to Sandcastle [here](https://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=Ground%20Clamping.html&label=Showcases).
+* Improved performance in `GroundPrimitive`.
 * Add a `rotatable2D` option to to `Scene`, `CesiumWidget` and `Viewer` to enable a rotatable map in 2D. [#3897](https://github.com/AnalyticalGraphicsInc/cesium/issues/3897)
 * `Camera.setView` and `Camera.flyTo` will now use the `orientation.heading` parameter in 2D if the map is rotatable.
 * Made changes to KML processing that allows for some incorrect KML (specifically KML that reuses IDs) to still be parsed correctly
 * Added `packArray` and `unpackArray` functions to `Cartesian2`, `Cartesian3`, and `Cartesian4`.
 * Fix some large polygon triangulations. [#2788](https://github.com/AnalyticalGraphicsInc/cesium/issues/2788)
 * Improved performance and accuracy of polygon triangulation by using the [earcut](https://github.com/mapbox/earcut) library. Loading a GeoJSON with polygons for each country was 2x faster.
 * Added CZML support for `Box`, `Corridor` and `Cylinder`.  Added new CZML properties: 
-    * `Billboard`: `width`, `height`, `scaleByDistance`, `translucencyByDistance`, `pixelOffsetScaleByDistance`, `imageSubRegion`
-    * `Label`: `translucencyByDistance`, `pixelOffsetScaleByDistance`
-    * `Model`: `maximumScale`
-    * `Point`: `scaleByDistance`, `translucencyByDistance`
+    * `Billboard`: `width`, `height`, `heightReference`, `scaleByDistance`, `translucencyByDistance`, `pixelOffsetScaleByDistance`, `imageSubRegion`
+    * `Label`: `heightReference`, `translucencyByDistance`, `pixelOffsetScaleByDistance`
+    * `Model`: `heightReference`, `maximumScale`
+    * `Point`: `heightReference`, `scaleByDistance`, `translucencyByDistance`
     * `Ellipsoid`: `subdivisions`, `stackPartitions`, `slicePartitions`
 * `Clock` now keeps its configuration settings self-consistent. Previously, this was done by `AnimationViewModel` and could become inconsistent in certain cases. [#4007](https://github.com/AnalyticalGraphicsInc/cesium/pull/4007)
 * Updated Cardboard Sandcastle example.

diff --git a/Source/Assets/approximateTerrainHeights.json b/Source/Assets/approximateTerrainHeights.json
diff --git a/Source/Core/CircleGeometry.js b/Source/Core/CircleGeometry.js
@@ -3,6 +3,7 @@ define([
         './Cartesian3',
         './defaultValue',
         './defined',
+        './defineProperties',
         './DeveloperError',
         './EllipseGeometry',
         './Ellipsoid',
@@ -12,6 +13,7 @@ define([
         Cartesian3,
         defaultValue,
         defined,
+        defineProperties,
         DeveloperError,
         EllipseGeometry,
         Ellipsoid,
@@ -174,6 +176,17 @@ define([
             vertexFormat : VertexFormat.POSITION_ONLY
         });
     };
+
+    defineProperties(CircleGeometry.prototype, {
+        /**
+         * @private
+         */
+        rectangle : {
+            get : function() {
+                return this._ellipseGeometry.rectangle;
+            }
+        }
+    });
 
     return CircleGeometry;
 });