Refactor DyanmicScene Properties

CHANGES.md

@@ -4,6 +4,30 @@ Change Log
 Beta Releases
 -------------
 
+### b21 - 2013-10-01
+* Breaking changes:
+    * Removed `processCzml`, use `CzmlDataSource` instead.
+    * Completely refactored the `DynamicScene` property system to vastly improve the API. See [#1080](https://github.com/AnalyticalGraphicsInc/cesium/pull/1080) for complete details.
+       * Removed `CzmlBoolean`, `CzmlCartesian2`, `CzmlCartesian3`, `CzmlColor`, `CzmlDefaults`, `CzmlDirection`, `CzmlHorizontalOrigin`, `CzmlImage`, `CzmlLabelStyle`, `CzmlNumber`, `CzmlPosition`, `CzmlString`, `CzmlUnitCartesian3`, `CzmlUnitQuaternion`, `CzmlUnitSpherical`, and `CzmlVerticalOrigin` since they are no longer needed.
+       * Removed `DynamicProperty`, `DynamicMaterialProperty`, `DynamicDirectionsProperty`, and `DynamicVertexPositionsProperty`; replacing them with an all new system of properties.
+          * `Property` - base interface for all properties. 
+          * `CompositeProperty` - a property composed of other properties.
+          * `ConstantProperty` - a property whose value never changes.
+          * `SampledProperty` - a property whose value is interpolated from a set of samples.
+          * `TimeIntervalCollectionProperty` - a property whose value changes based on time interval.
+          * `MaterialProperty` - base interface for all material properties.
+          * `CompositeMaterialProperty` - a `CompositeProperty` for materials.
+          * `ColorMaterialProperty` - a property that maps to a color material. (replaces `DynamicColorMaterial`)
+          * `GridMaterialProperty` - a property that maps to a grid material. (replaces `DynamicGridMaterial`)
+          * `ImageMaterialProperty` - a property that maps to an image material. (replaces `DynamicImageMaterial`)
+          * `PositionProperty`- base interface for all position properties.
+          * `CompositePositionProperty` - a `CompositeProperty` for positions.
+          * `ConstantPositionProperty` - a `PositionProperty` whose value does not change in respect to the `ReferenceFrame` in which is it defined.
+          * `SampledPositionProperty` - a `SampledProperty` for positions.
+          * `TimeIntervalCollectionPositionProperty` - A `TimeIntervalCollectionProperty` for positions.
+* Added `Packable` and `PackableForInterpolation` interfaces to aid interpolation and in-memory data storage.  Also made most core Cesium types implement them. 
+* Added `InterpolationAlgorithm` interface to codify the base interface already being used by `LagrangePolynomialApproximation`, `LinearApproximation`, and `HermitePolynomialApproximation`.
+
 ### b20 - 2013-09-03
 
 _This releases fixes 2D and other issues with Chrome 29.0.1547.57 ([#1002](https://github.com/AnalyticalGraphicsInc/cesium/issues/1002) and [#1047](https://github.com/AnalyticalGraphicsInc/cesium/issues/1047))._

Source/Core/Cartesian2.js

@@ -19,6 +19,7 @@ define([
      * @param {Number} [x=0.0] The X component.
      * @param {Number} [y=0.0] The Y component.
      *
+     * @see Packable
      * @see Cartesian3
      * @see Cartesian4
      */
@@ -148,6 +149,63 @@ define([
      */
     Cartesian2.fromCartesian4 = Cartesian2.clone;
 
+    /**
+     * The number of elements used to pack the object into an array.
+     * @Type {Number}
+     */
+    Cartesian2.packedLength = 2;
+
+    /**
+     * Stores the provided instance into the provided array.
+     * @memberof Cartesian2
+     *
+     * @param {Cartesian2} value The value to pack.
+     * @param {Array} array The array to pack into.
+     * @param {Number} [startingIndex=0] The index into the array at which to start packing the elements.
+     *
+     * @exception {DeveloperError} value is required.
+     * @exception {DeveloperError} array is required.
+     */
+    Cartesian2.pack = function(value, array, startingIndex) {
+        if (!defined(value)) {
+            throw new DeveloperError('value is required');
+        }
+
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        array[startingIndex++] = value.x;
+        array[startingIndex] = value.y;
+    };
+
+    /**
+     * Retrieves an instance from a packed array.
+     * @memberof Cartesian2
+     *
+     * @param {Array} array The packed array.
+     * @param {Number} [startingIndex=0] The starting index of the element to be unpacked.
+     * @param {Cartesian2} [result] The object into which to store the result.
+     *
+     * @exception {DeveloperError} array is required.
+     */
+    Cartesian2.unpack = function(array, startingIndex, result) {
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        if (!defined(result)) {
+            result = new Cartesian2();
+        }
+        result.x = array[startingIndex++];
+        result.y = array[startingIndex];
+        return result;
+    };
+
     /**
      * Computes the value of the maximum component for the supplied Cartesian.
      * @memberof Cartesian2

Source/Core/Cartesian3.js

@@ -22,6 +22,7 @@ define([
      *
      * @see Cartesian2
      * @see Cartesian4
+     * @see Packable
      */
     var Cartesian3 = function(x, y, z) {
         /**
@@ -173,6 +174,65 @@ define([
      */
     Cartesian3.fromCartesian4 = Cartesian3.clone;
 
+    /**
+     * The number of elements used to pack the object into an array.
+     * @Type {Number}
+     */
+    Cartesian3.packedLength = 3;
+
+    /**
+     * Stores the provided instance into the provided array.
+     * @memberof Cartesian3
+     *
+     * @param {Cartesian3} value The value to pack.
+     * @param {Array} array The array to pack into.
+     * @param {Number} [startingIndex=0] The index into the array at which to start packing the elements.
+     *
+     * @exception {DeveloperError} value is required.
+     * @exception {DeveloperError} array is required.
+     */
+    Cartesian3.pack = function(value, array, startingIndex) {
+        if (!defined(value)) {
+            throw new DeveloperError('value is required');
+        }
+
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        array[startingIndex++] = value.x;
+        array[startingIndex++] = value.y;
+        array[startingIndex] = value.z;
+    };
+
+    /**
+     * Retrieves an instance from a packed array.
+     * @memberof Cartesian3
+     *
+     * @param {Array} array The packed array.
+     * @param {Number} [startingIndex=0] The starting index of the element to be unpacked.
+     * @param {Cartesian3} [result] The object into which to store the result.
+     *
+     * @exception {DeveloperError} array is required.
+     */
+    Cartesian3.unpack = function(array, startingIndex, result) {
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        if (!defined(result)) {
+            result = new Cartesian3();
+        }
+        result.x = array[startingIndex++];
+        result.y = array[startingIndex++];
+        result.z = array[startingIndex];
+        return result;
+    };
+
     /**
      * Computes the value of the maximum component for the supplied Cartesian.
      * @memberof Cartesian3

Source/Core/Cartesian4.js

@@ -23,6 +23,7 @@ define([
      *
      * @see Cartesian2
      * @see Cartesian3
+     * @see Packable
      */
     var Cartesian4 = function(x, y, z, w) {
         /**
@@ -145,6 +146,68 @@ define([
         return result;
     };
 
+
+    /**
+     * The number of elements used to pack the object into an array.
+     * @Type {Number}
+     */
+    Cartesian4.packedLength = 4;
+
+    /**
+     * Stores the provided instance into the provided array.
+     * @memberof Cartesian4
+     *
+     * @param {Cartesian4} value The value to pack.
+     * @param {Array} array The array to pack into.
+     * @param {Number} [startingIndex=0] The index into the array at which to start packing the elements.
+     *
+     * @exception {DeveloperError} value is required.
+     * @exception {DeveloperError} array is required.
+     */
+    Cartesian4.pack = function(value, array, startingIndex) {
+        if (!defined(value)) {
+            throw new DeveloperError('value is required');
+        }
+
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        array[startingIndex++] = value.x;
+        array[startingIndex++] = value.y;
+        array[startingIndex++] = value.z;
+        array[startingIndex] = value.w;
+    };
+
+    /**
+     * Retrieves an instance from a packed array.
+     * @memberof Cartesian4
+     *
+     * @param {Array} array The packed array.
+     * @param {Number} [startingIndex=0] The starting index of the element to be unpacked.
+     * @param {Cartesian4} [result] The object into which to store the result.
+     *
+     * @exception {DeveloperError} array is required.
+     */
+    Cartesian4.unpack = function(array, startingIndex, result) {
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        if (!defined(result)) {
+            result = new Cartesian4();
+        }
+        result.x = array[startingIndex++];
+        result.y = array[startingIndex++];
+        result.z = array[startingIndex++];
+        result.w = array[startingIndex];
+        return result;
+    };
+
     /**
      * Computes the value of the maximum component for the supplied Cartesian.
      * @memberof Cartesian4

Source/Core/Color.js

@@ -44,6 +44,8 @@ define([
      *
      * @constructor
      * @alias Color
+     *
+     * @see Packable
      */
     var Color = function(red, green, blue, alpha) {
         /**
@@ -330,6 +332,67 @@ define([
         return undefined;
     };
 
+    /**
+     * The number of elements used to pack the object into an array.
+     * @Type {Number}
+     */
+    Color.packedLength = 4;
+
+    /**
+     * Stores the provided instance into the provided array.
+     * @memberof Color
+     *
+     * @param {Color} value The value to pack.
+     * @param {Array} array The array to pack into.
+     * @param {Number} [startingIndex=0] The index into the array at which to start packing the elements.
+     *
+     * @exception {DeveloperError} value is required.
+     * @exception {DeveloperError} array is required.
+     */
+    Color.pack = function(value, array, startingIndex) {
+        if (!defined(value)) {
+            throw new DeveloperError('value is required');
+        }
+
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        array[startingIndex++] = value.red;
+        array[startingIndex++] = value.green;
+        array[startingIndex++] = value.blue;
+        array[startingIndex] = value.alpha;
+    };
+
+    /**
+     * Retrieves an instance from a packed array.
+     * @memberof Color
+     *
+     * @param {Array} array The packed array.
+     * @param {Number} [startingIndex=0] The starting index of the element to be unpacked.
+     * @param {Color} [result] The object into which to store the result.
+     *
+     * @exception {DeveloperError} array is required.
+     */
+    Color.unpack = function(array, startingIndex, result) {
+        if (!defined(array)) {
+            throw new DeveloperError('array is required');
+        }
+
+        startingIndex = defaultValue(startingIndex, 0);
+
+        if (!defined(result)) {
+            result = new Color();
+        }
+        result.red = array[startingIndex++];
+        result.green = array[startingIndex++];
+        result.blue = array[startingIndex++];
+        result.alpha = array[startingIndex];
+        return result;
+    };
+
     /**
      * Converts a 'byte' color component in the range of 0 to 255 into
      * a 'float' color component in the range of 0 to 1.0.

Source/Core/InterpolationAlgorithm.js

@@ -0,0 +1,57 @@
+/*global define*/
+define(['./DeveloperError'], function(DeveloperError) {
+    "use strict";
+
+    /**
+     * The interface for interpolation algorithms.
+     * @exports InterpolationAlgorithm
+     *
+     * @see LagrangePolynomialApproximation
+     * @see LinearApproximation
+     * @see HermitePolynomialApproximation
+     */
+    var InterpolationAlgorithm = {};
+
+    /**
+     * Gets the name of this interpolation algorithm.
+     * @type {String}
+     */
+    InterpolationAlgorithm.type = undefined;
+
+    /**
+     * Given the desired degree, returns the number of data points required for interpolation.
+     * @memberof InterpolationAlgorithm
+     *
+     * @param degree The desired degree of interpolation.
+     *
+     * @returns The number of required data points needed for the desired degree of interpolation.
+     */
+    InterpolationAlgorithm.getRequiredDataPoints = function(degree) {
+        throw new DeveloperError('This function defines an interface and should not be called directly.');
+    };
+
+    /**
+     * Interpolates values.
+     * @memberof InterpolationAlgorithm
+     *
+     * @param {Number} x The independent variable for which the dependent variables will be interpolated.
+     *
+     * @param {Array} xTable The array of independent variables to use to interpolate.  The values
+     * in this array must be in increasing order and the same value must not occur twice in the array.
+     *
+     * @param {Array} yTable The array of dependent variables to use to interpolate.  For a set of three
+     * dependent values (p,q,w) at time 1 and time 2 this should be as follows: {p1, q1, w1, p2, q2, w2}.
+     *
+     * @param {Number} yStride The number of dependent variable values in yTable corresponding to
+     * each independent variable value in xTable.
+     *
+     * @param {Array} [result] An existing array into which to store the result.
+     *
+     * @returns The array of interpolated values, or the result parameter if one was provided.
+     */
+    InterpolationAlgorithm.interpolateOrderZero = function(x, xTable, yTable, yStride, result) {
+        throw new DeveloperError('This function defines an interface and should not be called directly.');
+    };
+
+    return InterpolationAlgorithm;
+});