CesiumGS · pjcozzi · Aug 21, 2015 · Feb 21, 2015 · Feb 24, 2015 · Mar 3, 2015
diff --git a/Apps/Sandcastle/gallery/development/Ground Primitive.html b/Apps/Sandcastle/gallery/development/Ground Primitive.html
@@ -0,0 +1,179 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">  <!-- Use Chrome Frame in IE -->
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no">
+    <meta name="description" content="Draw a polygon or extruded polygon on the globe surface.">
+    <meta name="cesium-sandcastle-labels" content="Development">
+    <title>Cesium Demo</title>
+    <script type="text/javascript" src="../Sandcastle-header.js"></script>
+    <script type="text/javascript" src="../../../ThirdParty/requirejs-2.1.9/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>
+<script id="cesium_sandcastle_script">
+function startup(Cesium) {
+    "use strict";
+//Sandcastle_Begin
+
+//Create the viewer.
+var viewer = new Cesium.Viewer('cesiumContainer');
+var scene = viewer.scene;
+scene.terrainProvider = new Cesium.CesiumTerrainProvider({
+    url: '//cesiumjs.org/stk-terrain/tilesets/world/tiles',
+    requestVertexNormals : true
+});
+
+// Circle geometry
+scene.primitives.add(new Cesium.GroundPrimitive({
+    geometryInstance: new Cesium.GeometryInstance({
+        geometry : new Cesium.CircleGeometry({
+            center : Cesium.Cartesian3.fromDegrees(-95.0, 45.0),
+            radius : 250000.0
+        }),
+        attributes : {
+            color : Cesium.ColorGeometryInstanceAttribute.fromColor(new Cesium.Color(1.0, 0.0, 0.0, 0.5))
+        },
+        id : 'circle'
+    })
+}));
+
+// Ellipse Geometry
+scene.primitives.add(new Cesium.GroundPrimitive({
+    geometryInstance: new Cesium.GeometryInstance({
+        geometry : new Cesium.EllipseGeometry({
+            center : Cesium.Cartesian3.fromDegrees(-105.0, 40.0),
+            semiMinorAxis : 300000.0,
+            semiMajorAxis : 400000.0
+        }),
+        attributes : {
+            color : Cesium.ColorGeometryInstanceAttribute.fromColor(new Cesium.Color(0.0, 1.0, 1.0, 0.5))
+        },
+        id : 'ellipse'
+    })
+}));
+
+// Corridor Geometry
+scene.primitives.add(new Cesium.GroundPrimitive({
+    geometryInstance : new Cesium.GeometryInstance({
+        geometry: new Cesium.CorridorGeometry({
+            positions : Cesium.Cartesian3.fromDegreesArray([
+                    -112.0, 40.0,
+                    -117.0, 40.0,
+                    -117.0, 35.0
+                ]),
+                width : 200000.0
+            }),
+        attributes : {
+            color : Cesium.ColorGeometryInstanceAttribute.fromColor(new Cesium.Color(0.0, 0.0, 1.0, 0.5))
+        },
+        id : 'corridor'
+    })
+}));
+
+// Rectangle geometry
+scene.primitives.add(new Cesium.GroundPrimitive({
+    geometryInstance : new Cesium.GeometryInstance({
+        geometry : new Cesium.RectangleGeometry({
+            rectangle : Cesium.Rectangle.fromDegrees(-100.0, 30.0, -90.0, 40.0),
+            rotation : Cesium.Math.toRadians(45)
+        }),
+        attributes: {
+            color: Cesium.ColorGeometryInstanceAttribute.fromColor(new Cesium.Color(0.0, 1.0, 0.0, 0.5))
+        },
+        id : 'rectangle'
+    })
+}));
+
+// Polygon on Mount Saint Helens
+var 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)];
+var polygonHierarchy = { positions : positions };
+
+var primitive = scene.primitives.add(new Cesium.GroundPrimitive({
+    geometryInstance : new Cesium.GeometryInstance({
+        geometry : new Cesium.PolygonGeometry({
+            polygonHierarchy : polygonHierarchy
+        }),
+        attributes: {
+            color: Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.RED.withAlpha(0.5))
+        },
+        id : 'polygon 1'
+    })
+}));
+
+// Same polygon slightly offset and overlapping.
+positions = scene.globe.ellipsoid.cartesianArrayToCartographicArray(positions);
+var delta = Cesium.Math.toRadians(0.01);
+for (var i = 0; i < positions.length; ++i) {
+    var position = positions[i];
+    position.latitude += delta;
+    position.longitude += delta;
+}
+positions = scene.globe.ellipsoid.cartographicArrayToCartesianArray(positions);
+polygonHierarchy = { positions : positions };
+
+scene.primitives.add(new Cesium.GroundPrimitive({
+    geometryInstance : new Cesium.GeometryInstance({
+        geometry : new Cesium.PolygonGeometry({
+            polygonHierarchy : polygonHierarchy
+        }),
+        attributes: {
+            color: Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.BLUE.withAlpha(0.5))
+        },
+        id : 'polygon 2'
+    })
+}));
+
+Sandcastle.addToolbarButton('View Mount Saint Helens', function() {
+    viewer.camera.lookAt(new Cesium.Cartesian3(-2354331.3069306486, -3742016.2427205616, 4581875.591571755), new Cesium.HeadingPitchRange(Cesium.Math.toRadians(20.0), Cesium.Math.toRadians(-35.0), 10000.0));
+    viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+});
+
+var currentObject = undefined;
+var lastColor = undefined;
+
+var handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
+handler.setInputAction(function(movement) {
+    var pickedObject = scene.pick(movement.endPosition);
+    if (Cesium.defined(pickedObject) && pickedObject !== currentObject) {
+        if (Cesium.defined(currentObject)) {
+            currentObject.primitive.getGeometryInstanceAttributes(currentObject.id).color = lastColor;
+        }
+
+        currentObject = pickedObject;
+
+        var attributes = currentObject.primitive.getGeometryInstanceAttributes(currentObject.id);
+        lastColor = attributes.color;
+        attributes.color = [255, 255, 0, 128];
+    } else if (!Cesium.defined(pickedObject) && Cesium.defined(currentObject)) {
+        currentObject.primitive.getGeometryInstanceAttributes(currentObject.id).color = lastColor;
+        currentObject = undefined;
+    }
+}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
+
+//Sandcastle_End
+    Sandcastle.finishedLoading();
+}
+if (typeof Cesium !== "undefined") {
+    startup(Cesium);
+} else if (typeof require === "function") {
+    require(["Cesium"], startup);
+}
+</script>
+</body>
+</html>
diff --git a/CHANGES.md b/CHANGES.md
@@ -11,6 +11,7 @@ Change Log
 * Fix an issue where non-feature nodes prevented KML documents from loading. [#2945](https://github.com/AnalyticalGraphicsInc/cesium/pull/2945).
 * Removed [es5-shim](https://github.com/kriskowal/es5-shim), which is no longer required by the unit tests. [#2933](https://github.com/AnalyticalGraphicsInc/cesium/pull/2945)
 * Fix issue where `JulianDate` would not parse certain dates properly. [#405](https://github.com/AnalyticalGraphicsInc/cesium/issues/405)
+* Added support for `GroundPrimitive` which works much like `Primitive` but it drapes the geometry over terrain. Valid geometries that can be draped on terrain are `CircleGeometry`, `CorridorGeometry`, `EllipseGeometry`, `PolygonGeometry`, and `RectangleGeometry`.
 
 ### 1.12 - 2015-08-03
 

diff --git a/Source/Core/BoundingSphere.js b/Source/Core/BoundingSphere.js
@@ -902,7 +902,7 @@ define([
      * @param {BoundingSphere} sphere The bounding sphere to calculate the distance to.
      * @param {Cartesian3} position The position to calculate the distance from.
      * @param {Cartesian3} direction The direction from position.
-     * @param {Cartesian2} [result] A Cartesian2 to store the nearest and farthest distances.
+     * @param {Interval} [result] A Interval to store the nearest and farthest distances.
      * @returns {Interval} The nearest and farthest distances on the bounding sphere from position in direction.
      */
     BoundingSphere.computePlaneDistances = function(sphere, position, direction, result) {
@@ -925,8 +925,7 @@ define([
         }
 
         var toCenter = Cartesian3.subtract(sphere.center, position, scratchCartesian3);
-        var proj = Cartesian3.multiplyByScalar(direction, Cartesian3.dot(direction, toCenter), scratchCartesian3);
-        var mag = Cartesian3.magnitude(proj);
+        var mag = Cartesian3.dot(direction, toCenter);
 
         result.start = mag - sphere.radius;
         result.stop = mag + sphere.radius;
@@ -1044,6 +1043,25 @@ define([
         return result;
     };
 
+    /**
+     * Determines whether or not a sphere is hidden from view by the occluder.
+     *
+     * @param {BoundingSphere} sphere The bounding sphere surrounding the occludee object.
+     * @param {Occluder} occluder The occluder.
+     * @returns {Boolean} <code>true</code> if the sphere is not visible; otherwise <code>false</code>.
+     */
+    BoundingSphere.isOccluded = function(sphere, occluder) {
+        //>>includeStart('debug', pragmas.debug);
+        if (!defined(sphere)) {
+            throw new DeveloperError('sphere is required.');
+        }
+        if (!defined(occluder)) {
+            throw new DeveloperError('occluder is required.');
+        }
+        //>>includeEnd('debug');
+        return !occluder.isBoundingSphereVisible(sphere);
+    };
+
     /**
      * Compares the provided BoundingSphere componentwise and returns
      * <code>true</code> if they are equal, <code>false</code> otherwise.
@@ -1073,6 +1091,48 @@ define([
         return BoundingSphere.intersectPlane(this, plane);
     };
 
+    /**
+     * Computes the estimated distance squared from the closest point on a bounding sphere to a point.
+     *
+     * @param {Cartesian3} cartesian The point
+     * @returns {Number} The estimated distance squared from the bounding sphere to the point.
+     *
+     * @example
+     * // Sort bounding spheres from back to front
+     * spheres.sort(function(a, b) {
+     *     return b.distanceSquaredTo(camera.positionWC) - a.distanceSquaredTo(camera.positionWC);
+     * });
+     */
+    BoundingSphere.prototype.distanceSquaredTo = function(cartesian) {
+        return BoundingSphere.distanceSquaredTo(this, cartesian);
+    };
+
+    /**
+     * The distances calculated by the vector from the center of the bounding sphere to position projected onto direction
+     * plus/minus the radius of the bounding sphere.
+     * <br>
+     * If you imagine the infinite number of planes with normal direction, this computes the smallest distance to the
+     * closest and farthest planes from position that intersect the bounding sphere.
+     *
+     * @param {Cartesian3} position The position to calculate the distance from.
+     * @param {Cartesian3} direction The direction from position.
+     * @param {Interval} [result] A Interval to store the nearest and farthest distances.
+     * @returns {Interval} The nearest and farthest distances on the bounding sphere from position in direction.
+     */
+    BoundingSphere.prototype.computePlaneDistances = function(position, direction, result) {
+        return BoundingSphere.computePlaneDistances(this, position, direction, result);
+    };
+
+    /**
+     * Determines whether or not a sphere is hidden from view by the occluder.
+     *
+     * @param {Occluder} occluder The occluder.
+     * @returns {Boolean} <code>true</code> if the sphere is not visible; otherwise <code>false</code>.
+     */
+    BoundingSphere.prototype.isOccluded = function(occluder) {
+        return BoundingSphere.isOccluded(this, occluder);
+    };
+
     /**
      * Compares this BoundingSphere against the provided BoundingSphere componentwise and returns
      * <code>true</code> if they are equal, <code>false</code> otherwise.

diff --git a/Source/Core/CircleGeometry.js b/Source/Core/CircleGeometry.js
@@ -6,6 +6,7 @@ define([
         './DeveloperError',
         './EllipseGeometry',
         './Ellipsoid',
+        './Math',
         './VertexFormat'
     ], function(
         Cartesian3,
@@ -14,11 +15,12 @@ define([
         DeveloperError,
         EllipseGeometry,
         Ellipsoid,
+        CesiumMath,
         VertexFormat) {
     "use strict";
 
     /**
-     * A description of a circle on the ellipsoid.
+     * A description of a circle on the ellipsoid. Circle geometry can be rendered with both {@link Primitive} and {@link GroundPrimitive}.
      *
      * @alias CircleGeometry
      * @constructor
@@ -157,5 +159,27 @@ define([
         return EllipseGeometry.createGeometry(circleGeometry._ellipseGeometry);
     };
 
+    /**
+     * @private
+     */
+    CircleGeometry.createShadowVolume = function(circleGeometry, minHeightFunc, maxHeightFunc) {
+        var granularity = circleGeometry._ellipseGeometry._granularity;
+        var ellipsoid = circleGeometry._ellipseGeometry._ellipsoid;
+
+        var minHeight = minHeightFunc(granularity, ellipsoid);
+        var maxHeight = maxHeightFunc(granularity, ellipsoid);
+
+        return new CircleGeometry({
+            center : circleGeometry._ellipseGeometry._center,
+            radius : circleGeometry._ellipseGeometry._semiMajorAxis,
+            ellipsoid : ellipsoid,
+            stRotation : circleGeometry._ellipseGeometry._stRotation,
+            granularity : granularity,
+            extrudedHeight : minHeight,
+            height : maxHeight,
+            vertexFormat : VertexFormat.POSITION_ONLY
+        });
+    };
+
     return CircleGeometry;
 });
diff --git a/Source/Core/CorridorGeometry.js b/Source/Core/CorridorGeometry.js
@@ -621,7 +621,7 @@ define([
     }
 
     /**
-     * A description of a corridor.
+     * A description of a corridor. Corridor geometry can be rendered with both {@link Primitive} and {@link GroundPrimitive}.
      *
      * @alias CorridorGeometry
      * @constructor
@@ -846,5 +846,27 @@ define([
         });
     };
 
+    /**
+     * @private
+     */
+    CorridorGeometry.createShadowVolume = function(corridorGeometry, minHeightFunc, maxHeightFunc) {
+        var granularity = corridorGeometry._granularity;
+        var ellipsoid = corridorGeometry._ellipsoid;
+
+        var minHeight = minHeightFunc(granularity, ellipsoid);
+        var maxHeight = maxHeightFunc(granularity, ellipsoid);
+
+        return new CorridorGeometry({
+            positions : corridorGeometry._positions,
+            width : corridorGeometry._width,
+            cornerType : corridorGeometry._cornerType,
+            ellipsoid : ellipsoid,
+            granularity : granularity,
+            extrudedHeight : minHeight,
+            height : maxHeight,
+            vertexFormat : VertexFormat.POSITION_ONLY
+        });
+    };
+
     return CorridorGeometry;
 });