Improve Camera Flights

Apps/Sandcastle/gallery/Camera.html

@@ -189,8 +189,35 @@
     });
 }
 
+function flyInACity() {
+    Sandcastle.declare(flyInACity);
+
+    var camera = scene.camera;
+    camera.flyTo({
+        destination : Cesium.Cartesian3.fromDegrees(-73.98580932617188, 40.74843406689482, 363.34038727246224),
+        complete : function() {
+            setTimeout(function() {
+                camera.flyTo({
+                    destination : Cesium.Cartesian3.fromDegrees(-73.98585975679403, 40.75759944127251, 186.50838555841779),
+                    orientation : {
+                        heading : Cesium.Math.toRadians(200.0),
+                        pitch : Cesium.Math.toRadians(-50.0)
+                    },
+                    easingFunction : Cesium.EasingFunction.LINEAR_NONE
+                });
+            }, 3000);
+        }
+    });
+}
+
 Sandcastle.addToolbarMenu([{
     text : 'Camera Options'
+}, {
+    text : 'Fly in a city',
+    onselect : function() {
+        flyInACity();
+        Sandcastle.highlight(flyInACity);
+    }
 }, {
     text : 'Fly to San Diego',
     onselect : function() {

CHANGES.md

@@ -2,6 +2,9 @@ Change Log
 ==========
 
 ### 1.11 - 2015-07-01
+
+* Breaking changes
+  * Removed `Camera.clone` that was deprecated in 1.10.
 * Deprecated
   * The STK World Terrain url `cesiumjs.org/stk-terrain/world` has been deprecated, use `assets.agi.com/stk-terrain/world` instead.  A redirect will be in place until 1.14.
 * Improved the algorithm that `Camera.viewRectangle` uses to select the position of the camera, so that the specified rectangle is now better centered on the screen [#2764](https://github.com/AnalyticalGraphicsInc/cesium/issues/2764).
@@ -14,6 +17,13 @@ Change Log
 * The camera now zooms to the point under the mouse cursor.
 * Fixed a bug in `ImageryLayer` that could cause an exception and the render loop to stop when the base layer did not cover the entire globe.
 * Fixed flash/streak rendering artifacts when picking [#2790](https://github.com/AnalyticalGraphicsInc/cesium/issues/2790), [#2811](https://github.com/AnalyticalGraphicsInc/cesium/issues/2811).
+* Improved camera flights. [#2825](https://github.com/AnalyticalGraphicsInc/cesium/pull/2825)
+* Fixed camera flights that ended up at the wrong position in Columbus view. [#802](https://github.com/AnalyticalGraphicsInc/cesium/issues/802)
+* Fixed camera flights through the map in 2D. [#804](https://github.com/AnalyticalGraphicsInc/cesium/issues/804)
+* Fixed strange camera flights from opposite sides of the globe. [#1158](https://github.com/AnalyticalGraphicsInc/cesium/issues/1158)
+* Fixed camera flights that wouldn't fly to the home view after zooming out past it. [#1400](https://github.com/AnalyticalGraphicsInc/cesium/issues/1400)
+* Fixed flying to rectangles that cross the IDL in Columbus view and 2D. [#2093](https://github.com/AnalyticalGraphicsInc/cesium/issues/2093)
+* Fixed flights with a pitch of -90 degrees. [#2468](https://github.com/AnalyticalGraphicsInc/cesium/issues/2468)
 
 ### 1.10 - 2015-06-01
 

Source/Core/CatmullRomSpline.js

@@ -5,6 +5,7 @@ define([
         './defaultValue',
         './defined',
         './defineProperties',
+        './deprecationWarning',
         './DeveloperError',
         './HermiteSpline',
         './Matrix4',
@@ -15,6 +16,7 @@ define([
         defaultValue,
         defined,
         defineProperties,
+        deprecationWarning,
         DeveloperError,
         HermiteSpline,
         Matrix4,
@@ -110,6 +112,8 @@ define([
      * @alias CatmullRomSpline
      * @constructor
      *
+     * @deprecated
+     *
      * @param {Object} options Object with the following properties:
      * @param {Number[]} options.times An array of strictly increasing, unit-less, floating-point times at each point.
      *                The values are in no way connected to the clock time. They are the parameterization for the curve.
@@ -143,6 +147,8 @@ define([
      * var p1 = spline.evaluate(times[i] + delta); // interpolated value when delta < times[i + 1] - times[i]
      */
     var CatmullRomSpline = function(options) {
+        deprecationWarning('CatmullRomSpline', 'CatmullRomSpline has been deprecated and will be removed in Cesium 1.12.');
+
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
         var points = options.points;

Source/Core/EasingFunction.js

@@ -14,8 +14,6 @@ define([
      *
      * @namespace
      * @alias EasingFunction
-     *
-     * @private
      */
     var EasingFunction = {
         /**

Source/Core/HermiteSpline.js

@@ -5,6 +5,7 @@ define([
         './defaultValue',
         './defined',
         './defineProperties',
+        './deprecationWarning',
         './DeveloperError',
         './LinearSpline',
         './Matrix4',
@@ -16,6 +17,7 @@ define([
         defaultValue,
         defined,
         defineProperties,
+        deprecationWarning,
         DeveloperError,
         LinearSpline,
         Matrix4,
@@ -134,6 +136,8 @@ define([
      * @alias HermiteSpline
      * @constructor
      *
+     * @deprecated
+     *
      * @param {Object} options Object with the following properties:
      * @param {Number[]} options.times An array of strictly increasing, unit-less, floating-point times at each point.
      *                The values are in no way connected to the clock time. They are the parameterization for the curve.
@@ -178,6 +182,8 @@ define([
      * var p1 = spline.evaluate(times[i] + delta); // interpolated value when delta < times[i + 1] - times[i]
      */
     var HermiteSpline = function(options) {
+        deprecationWarning('HermiteSpline', 'HermiteSpline has been deprecated and will be removed in Cesium 1.12.');
+
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
         var points = options.points;

Source/Scene/Camera.js

@@ -508,6 +508,31 @@ define([
         }
     }
 
+    function getHeading(direction, up) {
+        var heading;
+        if (!CesiumMath.equalsEpsilon(Math.abs(direction.z), 1.0, CesiumMath.EPSILON3)) {
+            heading = Math.atan2(direction.y, direction.x) - CesiumMath.PI_OVER_TWO;
+        } else {
+            heading = Math.atan2(up.y, up.x) - CesiumMath.PI_OVER_TWO;
+        }
+
+        return CesiumMath.TWO_PI - CesiumMath.zeroToTwoPi(heading);
+    }
+
+    function getPitch(direction) {
+        return CesiumMath.PI_OVER_TWO - CesiumMath.acosClamped(direction.z);
+    }
+
+    function getRoll(direction, up, right) {
+        var roll = 0.0;
+        if (!CesiumMath.equalsEpsilon(Math.abs(direction.z), 1.0, CesiumMath.EPSILON3)) {
+            roll = Math.atan2(-right.z, up.z);
+            roll = CesiumMath.zeroToTwoPi(roll + CesiumMath.TWO_PI);
+        }
+
+        return roll;
+    }
+
     var scratchHPRMatrix1 = new Matrix4();
     var scratchHPRMatrix2 = new Matrix4();
 
@@ -663,19 +688,11 @@ define([
                     var transform = Transforms.eastNorthUpToFixedFrame(this.positionWC, ellipsoid, scratchHPRMatrix2);
                     this._setTransform(transform);
 
-                    var direction = this.direction;
-                    var up = this.up;
-
-                    var heading;
-                    if (!CesiumMath.equalsEpsilon(Math.abs(direction.z), 1.0, CesiumMath.EPSILON3)) {
-                        heading = Math.atan2(direction.y, direction.x) - CesiumMath.PI_OVER_TWO;
-                    } else {
-                        heading = Math.atan2(up.y, up.x) - CesiumMath.PI_OVER_TWO;
-                    }
+                    var heading = getHeading(this.direction, this.up);
 
                     this._setTransform(oldTransform);
 
-                    return CesiumMath.TWO_PI - CesiumMath.zeroToTwoPi(heading);
+                    return heading;
                 }
 
                 return undefined;
@@ -698,7 +715,7 @@ define([
                     var transform = Transforms.eastNorthUpToFixedFrame(this.positionWC, ellipsoid, scratchHPRMatrix2);
                     this._setTransform(transform);
 
-                    var pitch = CesiumMath.PI_OVER_TWO - CesiumMath.acosClamped(this.direction.z);
+                    var pitch = getPitch(this.direction);
 
                     this._setTransform(oldTransform);
 
@@ -725,15 +742,7 @@ define([
                     var transform = Transforms.eastNorthUpToFixedFrame(this.positionWC, ellipsoid, scratchHPRMatrix2);
                     this._setTransform(transform);
 
-                    var up = this.up;
-                    var right = this.right;
-                    var direction = this.direction;
-
-                    var roll = 0.0;
-                    if (!CesiumMath.equalsEpsilon(Math.abs(direction.z), 1.0, CesiumMath.EPSILON3)) {
-                        roll = Math.atan2(-right.z, up.z);
-                        roll = CesiumMath.zeroToTwoPi(roll + CesiumMath.TWO_PI);
-                    }
+                    var roll = getRoll(this.direction, this.up, this.right);
 
                     this._setTransform(oldTransform);
 
@@ -2277,14 +2286,21 @@ define([
     var scratchFlyToMatrix4 = new Matrix4();
     var newOptions = {
         destination : undefined,
-        direction : undefined,
-        up : undefined,
+        heading : undefined,
+        pitch : undefined,
+        roll : undefined,
         duration : undefined,
         complete : undefined,
         cancel : undefined,
-        endTransform : undefined
+        endTransform : undefined,
+        maximumHeight : undefined,
+        easingFunction : undefined
     };
 
+    var scratchFlyDirection = new Cartesian3();
+    var scratchFlyUp = new Cartesian3();
+    var scratchFlyRight = new Cartesian3();
+
     /**
      * Flies the camera from its current position to a new position.
      *
@@ -2299,6 +2315,8 @@ define([
      * @param {Matrix4} [options.endTransform] Transform matrix representing the reference frame the camera will be in when the flight is completed.
      * @param {Boolean} [options.convert=true] When <code>true</code>, the destination is converted to the correct coordinate system for each scene mode. When <code>false</code>, the destination is expected
      *                  to be in the correct coordinate system.
+     * @param {Number} [options.maximumHeight] The maximum height at the peak of the flight.
+     * @param {EasingFunction|EasingFunction~Callback} [options.easingFunction] Controls how the time is interpolated over the duration of the flight.
      *
      * @exception {DeveloperError} If either direction or up is given, then both are required.
      *
@@ -2346,42 +2364,52 @@ define([
 
         var isRectangle = defined(destination.west);
         if (isRectangle) {
+            if (scene.mode !== SceneMode.SCENE3D && destination.west > destination.east) {
+                destination = Rectangle.MAX_VALUE;
+            }
             destination = scene.camera.getRectangleCameraCoordinates(destination, scratchFlyToDestination);
         }
 
-        var direction;
-        var up;
+        var heading;
+        var pitch;
+        var roll;
 
         var orientation = defaultValue(options.orientation, defaultValue.EMPTY_OBJECT);
         if (defined(orientation.heading)) {
-            var heading = defaultValue(orientation.heading, 0.0);
-            var pitch = defaultValue(orientation.pitch, -CesiumMath.PI_OVER_TWO);
-            var roll = defaultValue(orientation.roll, 0.0);
+            heading = orientation.heading;
+            pitch = orientation.pitch;
+            roll = orientation.roll;
+        } else if (defined(orientation.direction)) {
+            var direction = Cartesian3.clone(orientation.direction, scratchFlyDirection);
+            var up = Cartesian3.clone(orientation.up, scratchFlyUp);
 
-            var rotQuat = Quaternion.fromHeadingPitchRoll(heading - CesiumMath.PI_OVER_TWO, pitch, roll, scratchFlyToQuaternion);
-            var rotMat = Matrix3.fromQuaternion(rotQuat, scratchFlyToMatrix3);
+            if (scene.mode === SceneMode.SCENE3D) {
+                var ellipsoid = this._projection.ellipsoid;
+                var transform = Transforms.eastNorthUpToFixedFrame(destination, ellipsoid, scratchHPRMatrix1);
+                var invTransform = Matrix4.inverseTransformation(transform, scratchHPRMatrix2);
 
-            direction = Matrix3.getColumn(rotMat, 0, scratchFlyToDirection);
-            up = Matrix3.getColumn(rotMat, 2, scratchFlyToUp);
+                Matrix4.multiplyByPointAsVector(invTransform, direction, direction);
+                Matrix4.multiplyByPointAsVector(invTransform, up, up);
+            }
 
-            var ellipsoid = this._projection.ellipsoid;
-            var transform = Transforms.eastNorthUpToFixedFrame(destination, ellipsoid, scratchFlyToMatrix4);
+            var right = Cartesian3.cross(direction, up, scratchFlyRight);
 
-            Matrix4.multiplyByPointAsVector(transform, direction, direction);
-            Matrix4.multiplyByPointAsVector(transform, up, up);
-        } else if (defined(orientation.direction)) {
-            direction = orientation.direction;
-            up = orientation.up;
+            heading = getHeading(direction, up);
+            pitch = getPitch(direction);
+            roll = getRoll(direction, up, right);
         }
 
         newOptions.destination = destination;
-        newOptions.direction = direction;
-        newOptions.up = up;
+        newOptions.heading = heading;
+        newOptions.pitch = pitch;
+        newOptions.roll = roll;
         newOptions.duration = options.duration;
         newOptions.complete = options.complete;
         newOptions.cancel = options.cancel;
         newOptions.endTransform = options.endTransform;
         newOptions.convert = isRectangle ? false : options.convert;
+        newOptions.maximumHeight = options.maximumHeight;
+        newOptions.easingFunction = options.easingFunction;
 
         scene.tweens.add(CameraFlightPath.createTween(scene, newOptions));
     };
@@ -2489,6 +2517,8 @@ define([
      * @param {Camera~FlightCompleteCallback} [options.complete] The function to execute when the flight is complete.
      * @param {Camera~FlightCancelledCallback} [options.cancel] The function to execute if the flight is cancelled.
      * @param {Matrix4} [options.endTransform] Transform matrix representing the reference frame the camera will be in when the flight is completed.
+     * @param {Number} [options.maximumHeight] The maximum height at the peak of the flight.
+     * @param {EasingFunction|EasingFunction~Callback} [options.easingFunction] Controls how the time is interpolated over the duration of the flight.
      */
     Camera.prototype.flyToBoundingSphere = function(boundingSphere, options) {
         //>>includeStart('debug', pragmas.debug);
@@ -2513,49 +2543,22 @@ define([
         var transform = Transforms.eastNorthUpToFixedFrame(boundingSphere.center, Ellipsoid.WGS84, scratchflyToBoundingSphereTransform);
         Matrix4.multiplyByPoint(transform, position, position);
 
-        var direction;
-        var up;
-
-        if (!scene2D) {
-            direction = Cartesian3.subtract(boundingSphere.center, position, scratchflyToBoundingSphereDirection);
-            Cartesian3.normalize(direction, direction);
-
-            up = Matrix4.multiplyByPointAsVector(transform, Cartesian3.UNIT_Z, scratchflyToBoundingSphereUp);
-            var right = Cartesian3.cross(direction, up, scratchflyToBoundingSphereRight);
-            Cartesian3.cross(right, direction, up);
-            Cartesian3.normalize(up, up);
-        }
-
         this.flyTo({
             destination : position,
             orientation : {
-                direction : direction,
-                up : up
+                heading : offset.heading,
+                pitch : offset.pitch,
+                roll : 0.0
             },
             duration : options.duration,
             complete : options.complete,
             cancel : options.cancel,
-            endTransform : options.endTransform
+            endTransform : options.endTransform,
+            maximumHeight : options.maximumHeight,
+            easingFunction : options.easingFunction
         });
     };
 
-    /**
-     * Returns a duplicate of a Camera instance.
-     * @deprecated
-     * @returns {Camera} The provided result parameter or a new copy of the Camera instance.
-     */
-    Camera.prototype.clone = function() {
-        var camera = new Camera(this._scene);
-        camera.position = Cartesian3.clone(this.position);
-        camera.direction = Cartesian3.clone(this.direction);
-        camera.up = Cartesian3.clone(this.up);
-        camera.right = Cartesian3.clone(this.right);
-        camera._transform = Matrix4.clone(this.transform);
-        camera._transformChanged = true;
-        camera.frustum = this.frustum.clone();
-        return camera;
-    };
-
     /**
      * @private
      */