PolygonGraphics.hierarchy

CHANGES.md

@@ -7,11 +7,16 @@ Change Log
   * `Rectangle.intersectWith` was deprecated in Cesium 1.5. Use `Rectangle.intersection`, which is the same but returns `undefined` when two rectangles do not intersect.
   * `Rectangle.isEmpty` was deprecated in Cesium 1.5.
   * The `sourceUri` parameter to `GeoJsonDatasource.load` was deprecated in Cesium 1.4 and has been removed. Use options.sourceUri instead.
+  * `PolygonGraphics.positions` created by `GeoJSONDataSource` now evaluate to a `PolygonHierarchy` object instead of an array of positions.
 * Deprecated
-  *
+  * `PolygonGraphics.positions` was deprecated and replaced with `PolygonGraphics.hierarchy`, whose value is a `PolygonHierarchy` instead of an array of positions.  `PolygonGraphics.positions` will be removed in Cesium 1.8.
 * Improved performance of asynchronous geometry creation (as much as 20% faster in some use cases). [#2342](https://github.com/AnalyticalGraphicsInc/cesium/issues/2342)
 * Added `PolylineVolumeGraphics` and `Entity.polylineVolume`
 * Added `BillboardGraphics.imageSubRegion`, to enable custom texture atlas use for `Entity` instances.
+* Added `PolygonHierarchy` to make defining polygons with holes clearer.
+* Added `PolygonGraphics.hierarchy` for supporting polygons with holes via data sources.
+* `GeoJsonDataSource` now supports polygons with holes.
+* `ConstantProperty` can now hold any value; previously it was limited to values that implemented `equals` and `clones` functions, as well as a few special cases.
 
 ### 1.5 - 2015-01-05
 

Source/Core/PolygonGeometry.js

@@ -522,7 +522,7 @@ define([
      * @constructor
      *
      * @param {Object} options Object with the following properties:
-     * @param {Object} options.polygonHierarchy A polygon hierarchy that can include holes.
+     * @param {PolygonHierarchy} options.polygonHierarchy A polygon hierarchy that can include holes.
      * @param {Number} [options.height=0.0] The height of the polygon.
      * @param {Number} [options.extrudedHeight] The height of the polygon.
      * @param {VertexFormat} [options.vertexFormat=VertexFormat.DEFAULT] The vertex attributes to be computed.

Source/Core/PolygonHierarchy.js

@@ -0,0 +1,29 @@
+/*global define*/
+define(['./defined'], function(defined) {
+    "use strict";
+
+    /**
+     * An hierarchy of linear rings which define a polygon and its holes.
+     * The holes themselves may also have holes which nest inner polygons.
+     * @alias PolygonHierarchy
+     * @constructor
+     *
+     * @param {Cartesian3[]} [positions] A linear ring defining the outer boundary of the polygon or hole.
+     * @param {PolygonHierarchy[]} [holes] An array of polygon hierarchies defining holes in the polygon.
+     */
+    var PolygonHierarchy = function(positions, holes) {
+        /**
+         * A linear ring defining the outer boundary of the polygon or hole.
+         * @type {Cartesian3[]}
+         */
+        this.positions = defined(positions) ? positions : [];
+
+        /**
+         * An array of polygon hierarchies defining holes in the polygon.
+         * @type {PolygonHierarchy[]}
+         */
+        this.holes = defined(holes) ? holes : [];
+    };
+
+    return PolygonHierarchy;
+});

Source/DataSources/ConstantProperty.js

@@ -1,21 +1,20 @@
 /*global define*/
 define([
         '../Core/defaultValue',
+        '../Core/defined',
         '../Core/defineProperties',
         '../Core/DeveloperError',
-        '../Core/Event',
-        '../Core/isArray'
+        '../Core/Event'
     ], function(
         defaultValue,
+        defined,
         defineProperties,
         DeveloperError,
-        Event,
-        isArray) {
+        Event) {
     "use strict";
 
     /**
      * A {@link Property} whose value does not change with respect to simulation time.
-     * If the value is not a number, string, array, or HTMLElement then it must provide clone and equals functions.
      *
      * @alias ConstantProperty
      * @constructor
@@ -29,7 +28,8 @@ define([
      */
     var ConstantProperty = function(value) {
         this._value = undefined;
-        this._simple = true;
+        this._hasClone = false;
+        this._hasEquals = false;
         this._definitionChanged = new Event();
         this.setValue(value);
     };
@@ -70,12 +70,11 @@ define([
      * @returns {Object} The modified result parameter or a new instance if the result parameter was not supplied.
      */
     ConstantProperty.prototype.getValue = function(time, result) {
-        return this._simple ? this._value : this._value.clone(result);
+        return this._hasClone ? this._value.clone(result) : this._value;
     };
 
     /**
      * Sets the value of the property.
-     * If the value is not a number, string, array, or HTMLElement then it must provide clone and equals functions.
      *
      * @param {Object} value The property value.
      *
@@ -84,24 +83,19 @@ define([
      */
     ConstantProperty.prototype.setValue = function(value) {
         var oldValue = this._value;
-        var simple = this._simple;
-        if ((simple && oldValue !== value) || (!simple && !oldValue.equals(value))) {
-            simple = typeof value !== 'object' || value instanceof HTMLElement || isArray(value);
+        if (oldValue !== value) {
+            var isDefined = defined(value);
+            var hasClone = isDefined && typeof value.clone === 'function';
+            var hasEquals = isDefined && typeof value.equals === 'function';
 
-            //>>includeStart('debug', pragmas.debug);
-            if (!simple) {
-                if (typeof value.clone !== 'function') {
-                    throw new DeveloperError('clone is a required function.');
-                }
-                if (typeof value.equals !== 'function') {
-                    throw new DeveloperError('equals is a required function.');
-                }
-            }
-            //>>includeEnd('debug');
+            this._hasClone = hasClone;
+            this._hasEquals = hasEquals;
 
-            this._value = simple ? value : value.clone();
-            this._simple = simple;
-            this._definitionChanged.raiseEvent(this);
+            var changed = !hasEquals || !value.equals(oldValue);
+            if (changed) {
+                this._value = !hasClone ? value : value.clone();
+                this._definitionChanged.raiseEvent(this);
+            }
         }
     };
 
@@ -115,8 +109,8 @@ define([
     ConstantProperty.prototype.equals = function(other) {
         return this === other || //
                (other instanceof ConstantProperty && //
-                ((this._simple && (this._value === other._value)) || //
-                (!this._simple && this._value.equals(other._value))));
+                ((!this._hasEquals && (this._value === other._value)) || //
+                (this._hasEquals && this._value.equals(other._value))));
     };
 
     return ConstantProperty;

Source/DataSources/CzmlDataSource.js

@@ -850,7 +850,7 @@ define([
         }
     }
 
-    function processVertexData(object, positionsData, entityCollection) {
+    function processVertexData(object, propertyName, positionsData, entityCollection) {
         var i;
         var len;
         var references = positionsData.references;
@@ -863,13 +863,14 @@ define([
             var iso8601Interval = positionsData.interval;
             if (defined(iso8601Interval)) {
                 iso8601Interval = TimeInterval.fromIso8601(iso8601Interval);
-                if (!(object.positions instanceof CompositePositionProperty)) {
-                    object.positions = new CompositePositionProperty();
+                if (!(object[propertyName] instanceof CompositePositionProperty)) {
                     iso8601Interval.data = new PositionPropertyArray(properties);
-                    object.positions.intervals.addInterval(iso8601Interval);
+                    var property = new CompositePositionProperty();
+                    property.intervals.addInterval(iso8601Interval);
+                    object[propertyName] = property;
                 }
             } else {
-                object.positions = new PositionPropertyArray(properties);
+                object[propertyName] = new PositionPropertyArray(properties);
             }
         } else {
             var values = [];
@@ -900,23 +901,23 @@ define([
                 }
             }
             if (defined(positionsData.array)) {
-                processPacketData(Array, object, 'positions', positionsData, undefined, undefined, entityCollection);
+                processPacketData(Array, object, propertyName, positionsData, undefined, undefined, entityCollection);
             }
         }
     }
 
-    function processPositions(object, positionsData, entityCollection) {
+    function processPositions(object, propertyName, positionsData, entityCollection) {
         if (!defined(positionsData)) {
             return;
         }
 
         if (isArray(positionsData)) {
             var length = positionsData.length;
             for (var i = 0; i < length; i++) {
-                processVertexData(object, positionsData[i], entityCollection);
+                processVertexData(object, propertyName, positionsData[i], entityCollection);
             }
         } else {
-            processVertexData(object, positionsData, entityCollection);
+            processVertexData(object, propertyName, positionsData, entityCollection);
         }
     }
 
@@ -1223,7 +1224,7 @@ define([
         processPacketData(Color, polygon, 'outlineColor', polygonData.outlineColor, interval, sourceUri, entityCollection);
         processPacketData(Number, polygon, 'outlineWidth', polygonData.outlineWidth, interval, sourceUri, entityCollection);
         processPacketData(Boolean, polygon, 'perPositionHeight', polygonData.perPositionHeight, interval, sourceUri, entityCollection);
-        processPositions(polygon, polygonData.positions, entityCollection);
+        processPositions(polygon, 'hierarchy', polygonData.positions, entityCollection);
     }
 
     function processRectangle(entity, packet, entityCollection, sourceUri) {
@@ -1287,7 +1288,7 @@ define([
         processPacketData(Boolean, wall, 'outline', wallData.outline, interval, sourceUri, entityCollection);
         processPacketData(Color, wall, 'outlineColor', wallData.outlineColor, interval, sourceUri, entityCollection);
         processPacketData(Number, wall, 'outlineWidth', wallData.outlineWidth, interval, sourceUri, entityCollection);
-        processPositions(wall, wallData.positions, entityCollection);
+        processPositions(wall, 'positions', wallData.positions, entityCollection);
     }
 
     function processPolyline(entity, packet, entityCollection, sourceUri) {
@@ -1313,7 +1314,7 @@ define([
         processMaterialPacketData(polyline, 'material', polylineData.material, interval, sourceUri, entityCollection);
         processPacketData(Boolean, polyline, 'followSurface', polylineData.followSurface, interval, sourceUri, entityCollection);
         processPacketData(Number, polyline, 'granularity', polylineData.granularity, interval, sourceUri, entityCollection);
-        processPositions(polyline, polylineData.positions, entityCollection);
+        processPositions(polyline, 'positions', polylineData.positions, entityCollection);
     }
 
     function processCzmlPacket(packet, entityCollection, updaterFunctions, sourceUri, dataSource) {

Source/DataSources/GeoJsonDataSource.js

@@ -11,6 +11,7 @@ define([
         '../Core/getFilenameFromUri',
         '../Core/loadJson',
         '../Core/PinBuilder',
+        '../Core/PolygonHierarchy',
         '../Core/RuntimeError',
         '../Scene/VerticalOrigin',
         '../ThirdParty/topojson',
@@ -36,6 +37,7 @@ define([
         getFilenameFromUri,
         loadJson,
         PinBuilder,
+        PolygonHierarchy,
         RuntimeError,
         VerticalOrigin,
         topojson,
@@ -346,6 +348,10 @@ define([
     }
 
     function createPolygon(dataSource, geoJson, crsFunction, coordinates, options) {
+        if (coordinates.length === 0 || coordinates[0].length === 0) {
+            return;
+        }
+
         var outlineColorProperty = options.strokeMaterialProperty.color;
         var material = options.fillMaterialProperty;
         var widthProperty = options.strokeWidthProperty;
@@ -397,8 +403,15 @@ define([
         polygon.outlineColor = outlineColorProperty;
         polygon.outlineWidth = widthProperty;
         polygon.material = material;
-        polygon.positions = new ConstantProperty(coordinatesArrayToCartesianArray(coordinates, crsFunction));
-        if (coordinates.length > 0 && coordinates[0].length > 2) {
+
+        var holes = [];
+        for (var i = 1, len = coordinates.length; i < len; i++) {
+            holes.push(new PolygonHierarchy(coordinatesArrayToCartesianArray(coordinates[i], crsFunction)));
+        }
+
+        var positions = coordinates[0];
+        polygon.hierarchy = new ConstantProperty(new PolygonHierarchy(coordinatesArrayToCartesianArray(positions, crsFunction), holes));
+        if (positions[0].length > 2) {
             polygon.perPositionHeight = new ConstantProperty(true);
         }
 
@@ -407,13 +420,13 @@ define([
     }
 
     function processPolygon(dataSource, geoJson, geometry, crsFunction, options) {
-        createPolygon(dataSource, geoJson, crsFunction, geometry.coordinates[0], options);
+        createPolygon(dataSource, geoJson, crsFunction, geometry.coordinates, options);
     }
 
     function processMultiPolygon(dataSource, geoJson, geometry, crsFunction, options) {
         var polygons = geometry.coordinates;
         for (var i = 0; i < polygons.length; i++) {
-            createPolygon(dataSource, geoJson, crsFunction, polygons[i][0], options);
+            createPolygon(dataSource, geoJson, crsFunction, polygons[i], options);
         }
     }
 

Source/DataSources/PolygonGeometryUpdater.js

@@ -8,9 +8,11 @@ define([
         '../Core/destroyObject',
         '../Core/DeveloperError',
         '../Core/Event',
+        '../Core/isArray',
         '../Core/GeometryInstance',
         '../Core/Iso8601',
         '../Core/PolygonGeometry',
+        '../Core/PolygonHierarchy',
         '../Core/PolygonOutlineGeometry',
         '../Core/ShowGeometryInstanceAttribute',
         '../Scene/MaterialAppearance',
@@ -29,9 +31,11 @@ define([
         destroyObject,
         DeveloperError,
         Event,
+        isArray,
         GeometryInstance,
         Iso8601,
         PolygonGeometry,
+        PolygonHierarchy,
         PolygonOutlineGeometry,
         ShowGeometryInstanceAttribute,
         MaterialAppearance,
@@ -53,9 +57,7 @@ define([
     var GeometryOptions = function(entity) {
         this.id = entity;
         this.vertexFormat = undefined;
-        this.polygonHierarchy = {
-            positions : undefined
-        };
+        this.polygonHierarchy = undefined;
         this.perPositionHeight = undefined;
         this.height = undefined;
         this.extrudedHeight = undefined;
@@ -422,11 +424,11 @@ define([
             return;
         }
 
-        var positions = polygon.positions;
+        var hierarchy = polygon.hierarchy;
 
         var show = polygon.show;
         if ((defined(show) && show.isConstant && !show.getValue(Iso8601.MINIMUM_VALUE)) || //
-            (!defined(positions))) {
+            (!defined(hierarchy))) {
             if (this._fillEnabled || this._outlineEnabled) {
                 this._fillEnabled = false;
                 this._outlineEnabled = false;
@@ -454,7 +456,7 @@ define([
         this._fillEnabled = fillEnabled;
         this._outlineEnabled = outlineEnabled;
 
-        if (!positions.isConstant || //
+        if (!hierarchy.isConstant || //
             !Property.isConstant(height) || //
             !Property.isConstant(extrudedHeight) || //
             !Property.isConstant(granularity) || //
@@ -468,7 +470,12 @@ define([
         } else {
             var options = this._options;
             options.vertexFormat = isColorMaterial ? PerInstanceColorAppearance.VERTEX_FORMAT : MaterialAppearance.MaterialSupport.TEXTURED.vertexFormat;
-            options.polygonHierarchy.positions = positions.getValue(Iso8601.MINIMUM_VALUE, options.polygonHierarchy.positions);
+            var hierarchyValue = hierarchy.getValue(Iso8601.MINIMUM_VALUE);
+            if (isArray(hierarchyValue)) {
+                options.polygonHierarchy = new PolygonHierarchy(hierarchyValue);
+            } else {
+                options.polygonHierarchy = hierarchyValue;
+            }
             options.height = defined(height) ? height.getValue(Iso8601.MINIMUM_VALUE) : undefined;
             options.extrudedHeight = defined(extrudedHeight) ? extrudedHeight.getValue(Iso8601.MINIMUM_VALUE) : undefined;
             options.granularity = defined(granularity) ? granularity.getValue(Iso8601.MINIMUM_VALUE) : undefined;
@@ -511,6 +518,7 @@ define([
         this._outlinePrimitive = undefined;
         this._geometryUpdater = geometryUpdater;
         this._options = new GeometryOptions(geometryUpdater._entity);
+        this._scrach = undefined;
     };
 
     DynamicGeometryUpdater.prototype.update = function(time) {
@@ -532,12 +540,17 @@ define([
         }
 
         var options = this._options;
-        var positions = Property.getValueOrUndefined(polygon.positions, time, options.polygonHierarchy.positions);
-        if (!defined(positions)) {
+        var hierarchy = Property.getValueOrUndefined(polygon.hierarchy, time, this._scrach);
+        if (!defined(hierarchy)) {
             return;
         }
 
-        options.polygonHierarchy.positions = positions;
+        if (isArray(hierarchy)) {
+            options.polygonHierarchy = new PolygonHierarchy(hierarchy);
+        } else {
+            options.polygonHierarchy = hierarchy;
+        }
+
         options.height = Property.getValueOrUndefined(polygon.height, time);
         options.extrudedHeight = Property.getValueOrUndefined(polygon.extrudedHeight, time);
         options.granularity = Property.getValueOrUndefined(polygon.granularity, time);