Merge pull request #6743 from AnalyticalGraphicsInc/entityView

Clarify Entity.viewFrom documentation.

Source/Core/Math.js

@@ -161,7 +161,8 @@ define([
     CesiumMath.EPSILON20 = 0.00000000000000000001;
 
     /**
-     * 3.986004418e14
+     * The gravitational parameter of the Earth in meters cubed
+     * per second squared as defined by the WGS84 model: 3.986004418e14
      * @type {Number}
      * @constant
      */

Source/DataSources/Entity.js

@@ -456,8 +456,9 @@ define([
          */
         rectangle : createPropertyTypeDescriptor('rectangle', RectangleGraphics),
         /**
-         * Gets or sets the suggested initial offset for viewing this object
-         * with the camera.  The offset is defined in the east-north-up reference frame.
+         * Gets or sets the suggested initial offset when tracking this object.
+         * The offset is typically defined in the east-north-up reference frame,
+         * but may be another frame depending on the object's velocity.
          * @memberof Entity.prototype
          * @type {Property}
          */

Source/DataSources/EntityView.js

@@ -1,9 +1,9 @@
 define([
         '../Core/Cartesian3',
+        '../Core/Check',
         '../Core/defaultValue',
         '../Core/defined',
         '../Core/defineProperties',
-        '../Core/DeveloperError',
         '../Core/Ellipsoid',
         '../Core/HeadingPitchRange',
         '../Core/JulianDate',
@@ -14,10 +14,10 @@ define([
         '../Scene/SceneMode'
     ], function(
         Cartesian3,
+        Check,
         defaultValue,
         defined,
         defineProperties,
-        DeveloperError,
         Ellipsoid,
         HeadingPitchRange,
         JulianDate,
@@ -84,10 +84,7 @@ define([
                     Cartesian3.subtract(inertialCartesian, inertialDeltaCartesian, updateTransformCartesian3Scratch4);
                     var inertialVelocity = Cartesian3.magnitude(updateTransformCartesian3Scratch4) * 1000.0; // meters/sec
 
-                    // http://en.wikipedia.org/wiki/Standard_gravitational_parameter
-                    // Consider adding this to Cesium.Ellipsoid?
-                    var mu = 3.986004418e14; // m^3 / sec^2
-
+                    var mu = CesiumMath.GRAVITATIONALPARAMETER; // m^3 / sec^2
                     var semiMajorAxis = -mu / (inertialVelocity * inertialVelocity - (2 * mu / Cartesian3.magnitude(inertialCartesian)));
 
                     if (semiMajorAxis < 0 || semiMajorAxis > northUpAxisFactor * ellipsoid.maximumRadius) {
@@ -208,6 +205,10 @@ define([
      * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid to use for orienting the camera.
      */
     function EntityView(entity, scene, ellipsoid) {
+        //>>includeStart('debug', pragmas.debug);
+        Check.defined('entity', entity);
+        Check.defined('scene', scene);
+        //>>includeEnd('debug');
 
         /**
          * The entity to track with the camera.
@@ -233,7 +234,7 @@ define([
          */
         this.boundingSphere = undefined;
 
-        //Shadow copies of the objects so we can detect changes.
+        // Shadow copies of the objects so we can detect changes.
         this._lastEntity = undefined;
         this._mode = undefined;
 
@@ -268,45 +269,31 @@ define([
     var scratchCartesian = new Cartesian3();
 
     /**
-    * Should be called each animation frame to update the camera
-    * to the latest settings.
-    * @param {JulianDate} time The current animation time.
-    * @param {BoundingSphere} boundingSphere bounding sphere of the object.
-    *
-    */
+     * Should be called each animation frame to update the camera
+     * to the latest settings.
+     * @param {JulianDate} time The current animation time.
+     * @param {BoundingSphere} [boundingSphere] bounding sphere of the object.
+     */
     EntityView.prototype.update = function(time, boundingSphere) {
-        var scene = this.scene;
-        var entity = this.entity;
-        var ellipsoid = this.ellipsoid;
-
         //>>includeStart('debug', pragmas.debug);
-        if (!defined(time)) {
-            throw new DeveloperError('time is required.');
-        }
-        if (!defined(scene)) {
-            throw new DeveloperError('EntityView.scene is required.');
-        }
-        if (!defined(entity)) {
-            throw new DeveloperError('EntityView.entity is required.');
-        }
-        if (!defined(ellipsoid)) {
-            throw new DeveloperError('EntityView.ellipsoid is required.');
-        }
-        if (!defined(entity.position)) {
-            throw new DeveloperError('entity.position is required.');
-        }
+        Check.defined('time', time);
         //>>includeEnd('debug');
 
+        var scene = this.scene;
+        var ellipsoid = this.ellipsoid;
         var sceneMode = scene.mode;
         if (sceneMode === SceneMode.MORPHING) {
             return;
         }
 
+        var entity = this.entity;
         var positionProperty = entity.position;
+        if (!defined(positionProperty)) {
+            return;
+        }
         var objectChanged = entity !== this._lastEntity;
         var sceneModeChanged = sceneMode !== this._mode;
 
-        var offset3D = this._offset3D;
         var camera = scene.camera;
 
         var updateLookAt = objectChanged || sceneModeChanged;
@@ -317,9 +304,9 @@ define([
             var hasViewFrom = defined(viewFromProperty);
 
             if (!hasViewFrom && defined(boundingSphere)) {
-                //The default HPR is not ideal for high altitude objects so
-                //we scale the pitch as we get further from the earth for a more
-                //downward view.
+                // The default HPR is not ideal for high altitude objects so
+                // we scale the pitch as we get further from the earth for a more
+                // downward view.
                 scratchHeadingPitchRange.pitch = -CesiumMath.PI_OVER_FOUR;
                 scratchHeadingPitchRange.range = 0;
                 var position = positionProperty.getValue(time, scratchCartesian);
@@ -332,19 +319,17 @@ define([
                 this.boundingSphere = boundingSphere;
                 updateLookAt = false;
                 saveCamera = false;
-            } else if (!hasViewFrom || !defined(viewFromProperty.getValue(time, offset3D))) {
-                Cartesian3.clone(EntityView._defaultOffset3D, offset3D);
+            } else if (!hasViewFrom || !defined(viewFromProperty.getValue(time, this._offset3D))) {
+                Cartesian3.clone(EntityView._defaultOffset3D, this._offset3D);
             }
-        } else if (!sceneModeChanged && scene.mode !== SceneMode.MORPHING && this._mode !== SceneMode.SCENE2D) {
-            Cartesian3.clone(camera.position, offset3D);
+        } else if (!sceneModeChanged && this._mode !== SceneMode.SCENE2D) {
+            Cartesian3.clone(camera.position, this._offset3D);
         }
 
         this._lastEntity = entity;
-        this._mode = scene.mode !== SceneMode.MORPHING ? scene.mode : this._mode;
+        this._mode = sceneMode;
 
-        if (scene.mode !== SceneMode.MORPHING) {
-            updateTransform(this, camera, updateLookAt, saveCamera, positionProperty, time, ellipsoid);
-        }
+        updateTransform(this, camera, updateLookAt, saveCamera, positionProperty, time, ellipsoid);
     };
 
     return EntityView;

Specs/DataSources/EntityViewSpec.js

@@ -33,11 +33,18 @@ defineSuite([
         scene.destroyForSpecs();
     });
 
-    it('default constructor sets expected values', function() {
-        var view = new EntityView();
+    it('throws when constructed without required values', function() {
+        var entity = new Entity();
+        var view;
+        expect(function() {
+            view = new EntityView(undefined, scene);
+        }).toThrowDeveloperError();
+        expect(function() {
+            view = new EntityView(entity, undefined);
+        }).toThrowDeveloperError();
+
+        view = new EntityView(entity, scene);
         expect(view.ellipsoid).toBe(Ellipsoid.WGS84);
-        expect(view.entity).toBeUndefined();
-        expect(view.scene).toBeUndefined();
     });
 
     it('constructor sets expected values', function() {
@@ -98,38 +105,9 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
-    it('update throws without entity property', function() {
-        var view = new EntityView(undefined, scene);
-        expect(function() {
-            view.update(JulianDate.now());
-        }).toThrowDeveloperError();
-
-    });
-
-    it('update throws without scene property', function() {
+    it('update returns without entity.position property.', function() {
         var entity = new Entity();
-        entity.position = new ConstantPositionProperty(Cartesian3.ZERO);
-        var view = new EntityView(entity, undefined);
-        expect(function() {
-            view.update(JulianDate.now());
-        }).toThrowDeveloperError();
-    });
-
-    it('update throws without ellipsoid property', function() {
-        var entity = new Entity();
-        entity.position = new ConstantPositionProperty(Cartesian3.ZERO);
         var view = new EntityView(entity, scene);
-        view.ellipsoid = undefined;
-        expect(function() {
-            view.update(JulianDate.now());
-        }).toThrowDeveloperError();
-    });
-
-    it('update throws without entity.position property.', function() {
-        var entity = new Entity();
-        var view = new EntityView(entity, scene);
-        expect(function() {
-            view.update(JulianDate.now());
-        }).toThrowDeveloperError();
+        view.update(JulianDate.now());
     });
 }, 'WebGL');