Add support for using a velocity vector as the aligned axis of a billboard in CZML

CHANGES.md

@@ -7,6 +7,8 @@ Change Log
 * Add the `urlSchemeZeroPadding` property to `UrlTemplateImageryProvider` to allow the numeric parts of the URL, such as `{x}`, to be padded with zeros to make them a fixed width.
 * Updated the online [model converter](http://cesiumjs.org/convertmodel.html) to convert OBJ model to glTF with [obj2gltf](https://github.com/AnalyticalGraphicsInc/OBJ2GLTF), as well as optimize existing glTF models with the [gltf-pipeline](https://github.com/AnalyticalGraphicsInc/gltf-pipeline).
 * Fixed an issue causing entities to disappear when updating multiple entities simultaneously. [#4096](https://github.com/AnalyticalGraphicsInc/cesium/issues/4096)
+* Added support in CZML for expressing `BillboardGraphics.alignedAxis` as the velocity vector of an entity, using `velocityReference` syntax.
+* Normalizing the velocity vector produced by `VelocityVectorProperty` is now optional.
 
 ### 1.23 - 2016-07-01
 

Source/DataSources/BillboardGraphics.js

@@ -36,7 +36,7 @@ define([
      * @param {Property} [options.eyeOffset=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the eye offset.
      * @param {Property} [options.pixelOffset=Cartesian2.ZERO] A {@link Cartesian2} Property specifying the pixel offset.
      * @param {Property} [options.rotation=0] A numeric Property specifying the rotation about the alignedAxis.
-     * @param {Property} [options.alignedAxis=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the axis of rotation.
+     * @param {Property} [options.alignedAxis=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the unit vector axis of rotation.
      * @param {Property} [options.width] A numeric Property specifying the width of the billboard in pixels, overriding the native size.
      * @param {Property} [options.height] A numeric Property specifying the height of the billboard in pixels, overriding the native size.
      * @param {Property} [options.color=Color.WHITE] A Property specifying the tint {@link Color} of the image.
@@ -146,7 +146,7 @@ define([
         rotation : createPropertyDescriptor('rotation'),
 
         /**
-         * Gets or sets the {@link Cartesian3} Property specifying the axis of rotation
+         * Gets or sets the {@link Cartesian3} Property specifying the unit vector axis of rotation
          * in the fixed frame. When set to Cartesian3.ZERO the rotation is from the top of the screen.
          * @memberof BillboardGraphics.prototype
          * @type {Property}

Source/DataSources/CzmlDataSource.js

@@ -79,6 +79,7 @@ define([
         './StripeOrientation',
         './TimeIntervalCollectionPositionProperty',
         './TimeIntervalCollectionProperty',
+        './VelocityVectorProperty',
         './WallGraphics'
     ], function(
         BoundingRectangle,
@@ -160,6 +161,7 @@ define([
         StripeOrientation,
         TimeIntervalCollectionPositionProperty,
         TimeIntervalCollectionProperty,
+        VelocityVectorProperty,
         WallGraphics) {
     'use strict';
 
@@ -1089,6 +1091,18 @@ define([
         iso8601 : undefined
     };
 
+    function processAlignedAxis(billboard, packetData, interval, sourceUri, entityCollection) {
+        if (!defined(packetData)) {
+            return;
+        }
+
+        if (defined(packetData.velocityReference)) {
+            billboard.alignedAxis = new VelocityVectorProperty(makeReference(entityCollection, packetData.velocityReference), true);
+        } else {
+            processPacketData(Cartesian3, billboard, 'alignedAxis', packetData, interval, sourceUri, entityCollection);
+        }
+    }
+
     function processBillboard(entity, packet, entityCollection, sourceUri) {
         var billboardData = packet.billboard;
         if (!defined(billboardData)) {
@@ -1117,7 +1131,7 @@ define([
         processPacketData(HeightReference, billboard, 'heightReference', billboardData.heightReference, interval, sourceUri, entityCollection);
         processPacketData(Color, billboard, 'color', billboardData.color, interval, sourceUri, entityCollection);
         processPacketData(Rotation, billboard, 'rotation', billboardData.rotation, interval, sourceUri, entityCollection);
-        processPacketData(Cartesian3, billboard, 'alignedAxis', billboardData.alignedAxis, interval, sourceUri, entityCollection);
+        processAlignedAxis(billboard, billboardData.alignedAxis, interval, sourceUri, entityCollection);
         processPacketData(Boolean, billboard, 'sizeInMeters', billboardData.sizeInMeters, interval, sourceUri, entityCollection);
         processPacketData(Number, billboard, 'width', billboardData.width, interval, sourceUri, entityCollection);
         processPacketData(Number, billboard, 'height', billboardData.height, interval, sourceUri, entityCollection);
@@ -1343,7 +1357,7 @@ define([
         if (!defined(label)) {
             entity.label = label = new LabelGraphics();
         }
-        
+
         processPacketData(Boolean, label, 'show', labelData.show, interval, sourceUri, entityCollection);
         processPacketData(String, label, 'text', labelData.text, interval, sourceUri, entityCollection);
         processPacketData(String, label, 'font', labelData.font, interval, sourceUri, entityCollection);
@@ -1495,12 +1509,12 @@ define([
 
         processPacketData(Boolean, point, 'show', pointData.show, interval, sourceUri, entityCollection);
         processPacketData(Number, point, 'pixelSize', pointData.pixelSize, interval, sourceUri, entityCollection);
+        processPacketData(HeightReference, point, 'heightReference', pointData.heightReference, interval, sourceUri, entityCollection);
         processPacketData(Color, point, 'color', pointData.color, interval, sourceUri, entityCollection);
         processPacketData(Color, point, 'outlineColor', pointData.outlineColor, interval, sourceUri, entityCollection);
         processPacketData(Number, point, 'outlineWidth', pointData.outlineWidth, interval, sourceUri, entityCollection);
         processPacketData(NearFarScalar, point, 'scaleByDistance', pointData.scaleByDistance, interval, sourceUri, entityCollection);
         processPacketData(NearFarScalar, point, 'translucencyByDistance', pointData.translucencyByDistance, interval, sourceUri, entityCollection);
-        processPacketData(HeightReference, point, 'heightReference', pointData.heightReference, interval, sourceUri, entityCollection);
     }
 
     function processPolygon(entity, packet, entityCollection, sourceUri) {

Source/DataSources/VelocityOrientationProperty.js

@@ -49,7 +49,7 @@ define([
      * }));
      */
     function VelocityOrientationProperty(position, ellipsoid) {
-        this._velocityVectorProperty = new VelocityVectorProperty(position);
+        this._velocityVectorProperty = new VelocityVectorProperty(position, true);
         this._subscription = undefined;
         this._ellipsoid = undefined;
         this._definitionChanged = new Event();

Source/DataSources/VelocityVectorProperty.js

@@ -27,6 +27,7 @@ define([
      * @constructor
      *
      * @param {Property} [position] The position property used to compute the velocity.
+     * @param {Boolean} [normalize=true] Whether to normalize the computed velocity vector.
      *
      * @example
      * //Create an entity with a billboard rotated to match its velocity.
@@ -36,14 +37,15 @@ define([
      *   position : position,
      *   billboard : {
      *     image : 'image.png',
-     *     alignedAxis : new Cesium.VelocityVectorProperty(position)
+     *     alignedAxis : new Cesium.VelocityVectorProperty(position, true) // alignedAxis must be a unit vector
      *   }
      * }));
      */
-    function VelocityVectorProperty(position) {
+    function VelocityVectorProperty(position, normalize) {
         this._position = undefined;
         this._subscription = undefined;
         this._definitionChanged = new Event();
+        this._normalize = defaultValue(normalize, true);
 
         this.position = position;
     }
@@ -74,7 +76,7 @@ define([
             }
         },
         /**
-         * Gets or sets the position property used to compute orientation.
+         * Gets or sets the position property used to compute the velocity vector.
          * @memberof VelocityVectorProperty.prototype
          *
          * @type {Property}
@@ -101,12 +103,31 @@ define([
                     this._definitionChanged.raiseEvent(this);
                 }
             }
+        },
+        /**
+         * Gets or sets whether the vector produced by this property
+         * will be normalized or not.
+         * @memberof VelocityVectorProperty.prototype
+         *
+         * @type {Boolean}
+         */
+        normalize : {
+            get : function() {
+                return this._normalize;
+            },
+            set : function(value) {
+                if (this._normalize === value) {
+                    return;
+                }
+
+                this._normalize = value;
+                this._definitionChanged.raiseEvent(this);
+            }
         }
     });
 
     var position1Scratch = new Cartesian3();
     var position2Scratch = new Cartesian3();
-    var velocityScratch = new Cartesian3();
     var timeScratch = new JulianDate();
     var step = 1.0 / 60.0;
 
@@ -137,7 +158,7 @@ define([
 
         var property = this._position;
         if (Property.isConstant(property)) {
-            return undefined;
+            return this._normalize ? undefined : Cartesian3.clone(Cartesian3.ZERO, velocityResult);
         }
 
         var position1 = property.getValue(time, position1Scratch);
@@ -159,15 +180,19 @@ define([
         }
 
         if (Cartesian3.equals(position1, position2)) {
-            return undefined;
+            return this._normalize ? undefined : Cartesian3.clone(Cartesian3.ZERO, velocityResult);
         }
 
         if (defined(positionResult)) {
             position1.clone(positionResult);
         }
 
-        var velocity = Cartesian3.subtract(position2, position1, velocityScratch);
-        return Cartesian3.normalize(velocity, velocityResult);
+        var velocity = Cartesian3.subtract(position2, position1, velocityResult);
+        if (this._normalize) {
+            return Cartesian3.normalize(velocity, velocityResult);
+        } else {
+            return Cartesian3.divideByScalar(velocity, step, velocityResult);
+        }
     };
 
     /**