BoxOutlineGeometry and BoxGeometry Cleanup

CHANGES.md

@@ -6,13 +6,16 @@ Change Log
 * Breaking changes
   * Deleted old `<subfolder>/package.json` and `*.profile.js` files, not used since we moved away from a Dojo-based build years ago.  This should allow future compatibility with newer systems like Browserify and Webpack.
 * Deprecated
+  * Depreciated `BoxGeometry.minimumCorner` and `BoxGeometry.maximumCorner`, use `BoxGeometry.minimum` and `BoxGeometry.maximum` instead. These will be removed in 1.17.
+  * Depreciated `BoxOutlineGeometry.minimumCorner` and `BoxOutlineGeometry.maximumCorner`, use `BoxOutlineGeometry.minimum` and `BoxOutlineGeometry.maximum` instead. These will be removed in 1.17.
   * Made `EllipsoidPrimitive` private, use `EllipsoidGeometry` or `Entity.ellipsoid` instead.
   * Deprecated `RectanglePrimitive`, use `RectangleGeometry` or `Entity.rectangle` instead. It will be removed in 1.17.
   * Deprecated `EllipsoidPrimitive`, use `EllipsoidGeometry` or `Entity.ellipsoid` instead. It will be removed in 1.17.
 * Decreased GPU memory usage in `BillboardCollection` and `LabelCollection` by using the WebGL ANGLE_instanced_arrays extension.
 * Added CZML examples to Sandcastle.  See the new CZML tab.
 * Fixed token issue in `ArcGisMapServerImageryProvider`.
 * `ImageryLayerFeatureInfo` now has an `imageryLayer` property, indicating the layer that contains the feature.
+* Added `BoxOutlineGeometry.fromAxisAlignedBoundingBox` and `BoxGeometry.fromAxisAlignedBoundingBox` functions.
 
 ### 1.14 - 2015-10-01
 

Source/Core/BoxGeometry.js

@@ -5,6 +5,7 @@ define([
         './ComponentDatatype',
         './defaultValue',
         './defined',
+        './deprecationWarning',
         './DeveloperError',
         './Geometry',
         './GeometryAttribute',
@@ -17,6 +18,7 @@ define([
         ComponentDatatype,
         defaultValue,
         defined,
+        deprecationWarning,
         DeveloperError,
         Geometry,
         GeometryAttribute,
@@ -34,8 +36,8 @@ define([
      * @constructor
      *
      * @param {Object} options Object with the following properties:
-     * @param {Cartesian3} options.minimumCorner The minimum x, y, and z coordinates of the box.
-     * @param {Cartesian3} options.maximumCorner The maximum x, y, and z coordinates of the box.
+     * @param {Cartesian3} options.minimum The minimum x, y, and z coordinates of the box.
+     * @param {Cartesian3} options.maximum The maximum x, y, and z coordinates of the box.
      * @param {VertexFormat} [options.vertexFormat=VertexFormat.DEFAULT] The vertex attributes to be computed.
      *
      * @see BoxGeometry.fromDimensions
@@ -47,29 +49,42 @@ define([
      * @example
      * var box = new Cesium.BoxGeometry({
      *   vertexFormat : Cesium.VertexFormat.POSITION_ONLY,
-     *   maximumCorner : new Cesium.Cartesian3(250000.0, 250000.0, 250000.0),
-     *   minimumCorner : new Cesium.Cartesian3(-250000.0, -250000.0, -250000.0)
+     *   maximum : new Cesium.Cartesian3(250000.0, 250000.0, 250000.0),
+     *   minimum : new Cesium.Cartesian3(-250000.0, -250000.0, -250000.0)
      * });
      * var geometry = Cesium.BoxGeometry.createGeometry(box);
      */
     var BoxGeometry = function(options) {
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
-        var min = options.minimumCorner;
-        var max = options.maximumCorner;
+
+        var min = options.minimum;
+        var max = options.maximum;
 
         //>>includeStart('debug', pragmas.debug);
         if (!defined(min)) {
-            throw new DeveloperError('options.minimumCorner is required.');
+            if (defined(options.minimumCorner)) {
+                min = options.minimumCorner;
+                deprecationWarning('BoxGeometry', 'options.minimumCorner is deprecated. Use options.minimum instead.');
+            }
+            else {
+                throw new DeveloperError('options.minimum is required.');
+            }
         }
         if (!defined(max)) {
-            throw new DeveloperError('options.maximumCorner is required');
+            if (defined(options.maximumCorner)) {
+                max = options.maximumCorner;
+                deprecationWarning('BoxGeometry', 'options.maximumCorner is deprecated. Use options.maximum instead.');
+            }
+            else {
+                throw new DeveloperError('options.maximum is required');
+            }
         }
         //>>includeEnd('debug');
 
         var vertexFormat = defaultValue(options.vertexFormat, VertexFormat.DEFAULT);
 
-        this._minimumCorner = Cartesian3.clone(min);
-        this._maximumCorner = Cartesian3.clone(max);
+        this._minimum = Cartesian3.clone(min);
+        this._maximum = Cartesian3.clone(max);
         this._vertexFormat = vertexFormat;
         this._workerName = 'createBoxGeometry';
     };
@@ -107,15 +122,78 @@ define([
         //>>includeEnd('debug');
 
         var corner = Cartesian3.multiplyByScalar(dimensions, 0.5, new Cartesian3());
-        var min = Cartesian3.negate(corner, new Cartesian3());
-        var max = corner;
 
-        var newOptions = {
-            minimumCorner : min,
-            maximumCorner : max,
+        return new BoxGeometry({
+            minimum : Cartesian3.negate(corner, new Cartesian3()),
+            maximum : corner,
             vertexFormat : options.vertexFormat
-        };
-        return new BoxGeometry(newOptions);
+        });
+    };
+
+    /**
+     * Creates a cube from the dimensions of an AxisAlignedBoundingBox.
+     *
+     * @param {AxisAlignedBoundingBox} boundingBox A description of the AxisAlignedBoundingBox.
+     * @returns {BoxGeometry}
+     *
+     * @exception {DeveloperError} AxisAlignedBoundingBox must be defined.
+     *
+     * @see BoxGeometry.createGeometry
+     *
+     * @example
+     * var aabb = Cesium.AxisAlignedBoundingBox.fromPoints(Cesium.Cartesian3.fromDegreesArray([
+     *      -72.0, 40.0,
+     *      -70.0, 35.0,
+     *      -75.0, 30.0,
+     *      -70.0, 30.0,
+     *      -68.0, 40.0
+     * ]));
+     * var box = Cesium.BoxGeometry.fromAxisAlignedBoundingBox({
+     *      boundingBox: aabb
+     * });
+     */
+    BoxGeometry.fromAxisAlignedBoundingBox = function (boundingBox) {
+        if (!defined(boundingBox)) {
+            throw new DeveloperError('boundingBox is required.');
+        }
+
+        return new BoxGeometry({
+            minimum: boundingBox.minimum,
+            maximum: boundingBox.maximum
+        });
+    };
+
+    /**
+     * Creates a cube from the dimensions of an AxisAlignedBoundingBox.
+     *
+     * @param {AxisAlignedBoundingBox} boundingBox A description of the AxisAlignedBoundingBox.
+     * @returns {BoxGeometry}
+     *
+     * @exception {DeveloperError} AxisAlignedBoundingBox must be defined.
+     *
+     * @see BoxGeometry.createGeometry
+     *
+     * @example
+     * var aabb = Cesium.AxisAlignedBoundingBox.fromPoints(Cesium.Cartesian3.fromDegreesArray([
+     *      -72.0, 40.0,
+     *      -70.0, 35.0,
+     *      -75.0, 30.0,
+     *      -70.0, 30.0,
+     *      -68.0, 40.0
+     * ]));
+     * var box = Cesium.BoxGeometry.fromAxisAlignedBoundingBox({
+     *      boundingBox: aabb
+     * });
+     */
+    BoxGeometry.fromAxisAlignedBoundingBox = function (boundingBox) {
+        if (!defined(boundingBox)) {
+            throw new DeveloperError('boundingBox is required.');
+        }
+
+        return new BoxGeometry({
+            minimum : boundingBox.minimum,
+            maximum : boundingBox.maximum
+        });
     };
 
     /**
@@ -144,18 +222,18 @@ define([
 
         startingIndex = defaultValue(startingIndex, 0);
 
-        Cartesian3.pack(value._minimumCorner, array, startingIndex);
-        Cartesian3.pack(value._maximumCorner, array, startingIndex + Cartesian3.packedLength);
+        Cartesian3.pack(value._minimum, array, startingIndex);
+        Cartesian3.pack(value._maximum, array, startingIndex + Cartesian3.packedLength);
         VertexFormat.pack(value._vertexFormat, array, startingIndex + 2 * Cartesian3.packedLength);
     };
 
     var scratchMin = new Cartesian3();
     var scratchMax = new Cartesian3();
     var scratchVertexFormat = new VertexFormat();
     var scratchOptions = {
-        minimumCorner : scratchMin,
-        maximumCorner : scratchMax,
-        vertexFormat : scratchVertexFormat
+        minimum: scratchMin,
+        maximum: scratchMax,
+        vertexFormat: scratchVertexFormat
     };
 
     /**
@@ -183,8 +261,8 @@ define([
             return new BoxGeometry(scratchOptions);
         }
 
-        result._minimumCorner = Cartesian3.clone(min, result._minimumCorner);
-        result._maximumCorner = Cartesian3.clone(max, result._maximumCorner);
+        result._minimum = Cartesian3.clone(min, result._minimum);
+        result._maximum = Cartesian3.clone(max, result._maximum);
         result._vertexFormat = VertexFormat.clone(vertexFormat, result._vertexFormat);
 
         return result;
@@ -197,8 +275,8 @@ define([
      * @returns {Geometry} The computed vertices and indices.
      */
     BoxGeometry.createGeometry = function(boxGeometry) {
-        var min = boxGeometry._minimumCorner;
-        var max = boxGeometry._maximumCorner;
+        var min = boxGeometry._minimum;
+        var max = boxGeometry._maximum;
         var vertexFormat = boxGeometry._vertexFormat;
 
         var attributes = new GeometryAttributes();

Source/Core/BoxOutlineGeometry.js

@@ -5,6 +5,7 @@ define([
         './ComponentDatatype',
         './defaultValue',
         './defined',
+        './deprecationWarning',
         './DeveloperError',
         './Geometry',
         './GeometryAttribute',
@@ -16,6 +17,7 @@ define([
         ComponentDatatype,
         defaultValue,
         defined,
+        deprecationWarning,
         DeveloperError,
         Geometry,
         GeometryAttribute,
@@ -32,8 +34,8 @@ define([
      * @constructor
      *
      * @param {Object} options Object with the following properties:
-     * @param {Cartesian3} options.minimumCorner The minimum x, y, and z coordinates of the box.
-     * @param {Cartesian3} options.maximumCorner The maximum x, y, and z coordinates of the box.
+     * @param {Cartesian3} options.minimum The minimum x, y, and z coordinates of the box.
+     * @param {Cartesian3} options.maximum The maximum x, y, and z coordinates of the box.
      *
      * @see BoxOutlineGeometry.fromDimensions
      * @see BoxOutlineGeometry.createGeometry
@@ -43,23 +45,35 @@ define([
      *
      * @example
      * var box = new Cesium.BoxOutlineGeometry({
-     *   maximumCorner : new Cesium.Cartesian3(250000.0, 250000.0, 250000.0),
-     *   minimumCorner : new Cesium.Cartesian3(-250000.0, -250000.0, -250000.0)
+     *   maximum : new Cesium.Cartesian3(250000.0, 250000.0, 250000.0),
+     *   minimum : new Cesium.Cartesian3(-250000.0, -250000.0, -250000.0)
      * });
      * var geometry = Cesium.BoxOutlineGeometry.createGeometry(box);
      */
     var BoxOutlineGeometry = function(options) {
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
-        var min = options.minimumCorner;
-        var max = options.maximumCorner;
+        var min = options.minimum;
+        var max = options.maximum;
 
         //>>includeStart('debug', pragmas.debug);
         if (!defined(min)) {
-            throw new DeveloperError('options.minimumCorner is required.');
+            if (defined(options.minimumCorner)) {
+                min = options.minimumCorner;
+                deprecationWarning('BoxOutlineGeometry', 'options.minimumCorner is deprecated. Use options.minimum instead.');
+            }
+            else {
+                throw new DeveloperError('options.minimum is required.');
+            }
         }
         if (!defined(max)) {
-            throw new DeveloperError('options.maximumCorner is required');
+            if (defined(options.maximumCorner)) {
+                max = options.maximumCorner;
+                deprecationWarning('BoxOutlineGeometry', 'options.maximumCorner is deprecated. Use options.maximum instead.');
+            }
+            else {
+                throw new DeveloperError('options.maximum is required');
+            }
         }
         //>>includeEnd('debug');
 
@@ -99,14 +113,42 @@ define([
         //>>includeEnd('debug');
 
         var corner = Cartesian3.multiplyByScalar(dimensions, 0.5, new Cartesian3());
-        var min = Cartesian3.negate(corner, new Cartesian3());
-        var max = corner;
-
-        var newOptions = {
-            minimumCorner : min,
-            maximumCorner : max
-        };
-        return new BoxOutlineGeometry(newOptions);
+
+        return new BoxOutlineGeometry({
+            minimum : Cartesian3.negate(corner, new Cartesian3()),
+            maximum : corner
+        });
+    };
+
+    /**
+     * Creates an outline of a cube from the dimensions of an AxisAlignedBoundingBox.
+     *
+     * @param {AxisAlignedBoundingBox} boundingBox A description of the AxisAlignedBoundingBox.
+     * @returns {BoxOutlineGeometry}
+     *
+     * @exception {DeveloperError} AxisAlignedBoundingBox must be defined.
+     *
+     * @see BoxOutlineGeometry.createGeometry
+     *
+     * @example
+     * var aabb = Cesium.AxisAlignedBoundingBox.fromPoints(Cesium.Cartesian3.fromDegreesArray([
+     *      -72.0, 40.0,
+     *      -70.0, 35.0,
+     *      -75.0, 30.0,
+     *      -70.0, 30.0,
+     *      -68.0, 40.0
+     * ]));
+     * var box = Cesium.BoxOutlineGeometry.fromAxisAlignedBoundingBox(aabb);
+     */
+    BoxOutlineGeometry.fromAxisAlignedBoundingBox = function(boundingBox) {
+        if (!defined(boundingBox)) {
+            throw new DeveloperError('boundingBox is required.');
+        }
+
+        return new BoxOutlineGeometry({
+            minimum : boundingBox.minimum,
+            maximum : boundingBox.maximum
+        });
     };
 
     /**
@@ -142,8 +184,8 @@ define([
     var scratchMin = new Cartesian3();
     var scratchMax = new Cartesian3();
     var scratchOptions = {
-        minimumCorner : scratchMin,
-        maximumCorner : scratchMax
+        minimum : scratchMin,
+        maximum : scratchMax
     };
 
     /**

Specs/Core/BoxGeometrySpec.js

@@ -1,11 +1,13 @@
 /*global defineSuite*/
 defineSuite([
         'Core/BoxGeometry',
+        'Core/AxisAlignedBoundingBox',
         'Core/Cartesian3',
         'Core/VertexFormat',
         'Specs/createPackableSpecs'
     ], function(
         BoxGeometry,
+        AxisAlignedBoundingBox,
         Cartesian3,
         VertexFormat,
         createPackableSpecs) {
@@ -84,6 +86,20 @@ defineSuite([
         expect(m.indices.length).toEqual(12 * 3);
     });
 
+    it('fromAxisAlignedBoundingBox throws with no boundingBox', function() {
+        expect(function() {
+            return BoxGeometry.fromAxisAlignedBoundingBox(undefined);
+        }).toThrowDeveloperError();
+    });
+
+    it('fromAxisAlignedBoundingBox', function() {
+        var min = new Cartesian3(-1, -2, -3);
+        var max = new Cartesian3(1, 2, 3);
+        var m = BoxGeometry.fromAxisAlignedBoundingBox(new AxisAlignedBoundingBox(min, max));
+        expect(m._minimum).toEqual(min);
+        expect(m._maximum).toEqual(max);
+    });
+
     createPackableSpecs(BoxGeometry, new BoxGeometry({
         minimumCorner : new Cartesian3(1.0, 2.0, 3.0),
         maximumCorner : new Cartesian3(4.0, 5.0, 6.0),