Make Camera.setView options consistent with Camera.flyTo

Apps/CesiumViewer/CesiumViewer.js

@@ -156,10 +156,12 @@ define([
             var roll = ((splitQuery.length > 5) && (!isNaN(+splitQuery[5]))) ? CesiumMath.toRadians(+splitQuery[5]) : undefined;
 
             viewer.camera.setView({
-                position: Cartesian3.fromDegrees(longitude, latitude, height),
-                heading: heading,
-                pitch: pitch,
-                roll: roll
+                destination: Cartesian3.fromDegrees(longitude, latitude, height),
+                orientation: {
+                    heading: heading,
+                    pitch: pitch,
+                    roll: roll
+                }
             });
         }
     }

Apps/Sandcastle/gallery/Camera.html

@@ -139,9 +139,11 @@
     var camera = viewer.camera;
     camera.setView({
         position : Cesium.Cartesian3.fromDegrees(-75.5847, 40.0397, 1000.0),
-        heading : -Cesium.Math.PI_OVER_TWO,
-        pitch : -Cesium.Math.PI_OVER_FOUR,
-        roll : 0.0
+        orientation: {
+            heading : -Cesium.Math.PI_OVER_TWO,
+            pitch : -Cesium.Math.PI_OVER_FOUR,
+            roll : 0.0
+        }
     });
 }
 

CHANGES.md

@@ -16,12 +16,18 @@ Change Log
   * Deprecated `PerspectiveOffCenterFrustum.getPixelSize`, use `PerspectiveOffCenterFrustum.getPixelDimensions` instead. It will be removed in 1.17.
   * Deprecated `Scene\HeadingPitchRange`, use `Core\HeadingPitchRange` instead. It will be removed in 1.17.
   * Deprecated `jsonp` use `loadJsonp` instead. It will be removed in 1.17.
+  * Deprecated `Camera.viewRectangle`, use `Camera.setView({destination: rectangle})` instead. It will be removed in 1.17.
+  * The following options to `Camera.setView` have been deprecated and will be removed in 1.17:
+    * `position`: use `destination` instead.
+    * `positionCartographic`: convert to a `Cartesian3` and use `destination` instead.
+    * `heading`, `pitch` and `roll`: use `orientation.heading/pitch/roll` instead.  
 * Decreased GPU memory usage in `BillboardCollection` and `LabelCollection` by using the WebGL ANGLE_instanced_arrays extension.
 * Added CZML examples to Sandcastle.  See the new CZML tab.
 * Fixed token issue in `ArcGisMapServerImageryProvider`.
 * `ImageryLayerFeatureInfo` now has an `imageryLayer` property, indicating the layer that contains the feature.
 * Added `BoxOutlineGeometry.fromAxisAlignedBoundingBox` and `BoxGeometry.fromAxisAlignedBoundingBox` functions.
 * The WebGL setting of `failIfMajorPerformanceCaveat` now defaults to `false`, which is the official WebGL default. This improves compatibility with out-of-date drivers and remote desktop sessions. Cesium will run slower in these cases instead of simply failing to load. 
+* Changed `Camera.setView` to take the same parameter options as `Camera.flyTo`.  `options.destination` takes a rectangle, `options.orientation` works with heading/pitch/roll or direction/up, and `options.endTransform` was added.
 
 ### 1.14 - 2015-10-01
 

Source/Scene/CameraFlightPath.js

@@ -125,9 +125,11 @@ define([
             var time = value.time / duration;
 
             camera.setView({
-                heading : CesiumMath.lerp(startHeading, heading, time),
-                pitch : CesiumMath.lerp(startPitch, pitch, time),
-                roll : CesiumMath.lerp(startRoll, roll, time)
+                orientation: {
+                    heading : CesiumMath.lerp(startHeading, heading, time),
+                    pitch : CesiumMath.lerp(startPitch, pitch, time),
+                    roll : CesiumMath.lerp(startRoll, roll, time)
+                }
             });
 
             Cartesian2.lerp(start, destination, time, camera.position);
@@ -139,7 +141,7 @@ define([
 
     var scratchStartCart = new Cartographic();
     var scratchEndCart = new Cartographic();
-    var scratchCurrentPositionCart = new Cartographic();
+    var scratchCurrentPositionCart = new Cartesian3();
 
     function createUpdate3D(scene, duration, destination, heading, pitch, roll, optionAltitude) {
         var camera = scene.camera;
@@ -171,16 +173,19 @@ define([
         var update = function(value) {
             var time = value.time / duration;
 
-            var position = scratchCurrentPositionCart;
-            position.longitude = CesiumMath.lerp(startCart.longitude, destCart.longitude, time);
-            position.latitude = CesiumMath.lerp(startCart.latitude, destCart.latitude, time);
-            position.height = heightFunction(time);
+            var position = Cartesian3.fromRadians(
+                CesiumMath.lerp(startCart.longitude, destCart.longitude, time),
+                CesiumMath.lerp(startCart.latitude, destCart.latitude, time),
+                heightFunction(time)
+            );
 
             camera.setView({
-                positionCartographic : position,
-                heading : CesiumMath.lerp(startHeading, heading, time),
-                pitch : CesiumMath.lerp(startPitch, pitch, time),
-                roll : CesiumMath.lerp(startRoll, roll, time)
+                destination : position,
+                orientation: {
+                    heading : CesiumMath.lerp(startHeading, heading, time),
+                    pitch : CesiumMath.lerp(startPitch, pitch, time),
+                    roll : CesiumMath.lerp(startRoll, roll, time)
+                }
             });
         };
 
@@ -191,9 +196,7 @@ define([
         var camera = scene.camera;
 
         var start = Cartesian3.clone(camera.position, scratchStart);
-        var startPitch = camera.pitch;
         var startHeading = adjustAngleForLERP(camera.heading, heading);
-        var startRoll = adjustAngleForLERP(camera.roll, roll);
 
         var startHeight = camera.frustum.right - camera.frustum.left;
         var heightFunction = createHeightFunction(camera, destination, startHeight, destination.z, optionAltitude);
@@ -202,9 +205,9 @@ define([
             var time = value.time / duration;
 
             camera.setView({
-                heading : CesiumMath.lerp(startHeading, heading, time),
-                pitch : CesiumMath.lerp(startPitch, pitch, time),
-                roll : CesiumMath.lerp(startRoll, roll, time)
+                orientation: {
+                    heading : CesiumMath.lerp(startHeading, heading, time)
+                }
             });
 
             Cartesian2.lerp(start, destination, time, camera.position);
@@ -263,20 +266,19 @@ define([
             throw new DeveloperError('destination is required.');
         }
         //>>includeEnd('debug');
+        var mode = scene.mode;
 
-        var projection = scene.mapProjection;
-        var ellipsoid = projection.ellipsoid;
-
-        var maximumHeight = options.maximumHeight;
-        var easingFunction = options.easingFunction;
-
-        if (scene.mode === SceneMode.MORPHING) {
+        if (mode === SceneMode.MORPHING) {
             return emptyFlight();
         }
 
         var convert = defaultValue(options.convert, true);
+        var projection = scene.mapProjection;
+        var ellipsoid = projection.ellipsoid;
+        var maximumHeight = options.maximumHeight;
+        var easingFunction = options.easingFunction;
 
-        if (convert && scene.mode !== SceneMode.SCENE3D) {
+        if (convert && mode !== SceneMode.SCENE3D) {
             ellipsoid.cartesianToCartographic(destination, scratchCartographic);
             destination = projection.project(scratchCartographic, scratchDestination);
         }
@@ -293,9 +295,8 @@ define([
             duration = Math.min(duration, 3.0);
         }
 
-        var mode = scene.mode;
         var heading = defaultValue(options.heading, 0.0);
-        var pitch = scene.mode !== SceneMode.SCENE2D ? defaultValue(options.pitch, -CesiumMath.PI_OVER_TWO) : -CesiumMath.PI_OVER_TWO;
+        var pitch = defaultValue(options.pitch, -CesiumMath.PI_OVER_TWO);
         var roll = defaultValue(options.roll, 0.0);
 
         var controller = scene.screenSpaceCameraController;
@@ -310,7 +311,11 @@ define([
         empty = empty && Cartesian2.equalsEpsilon(camera.position, destination, CesiumMath.EPSILON6);
         empty = empty && CesiumMath.equalsEpsilon(Math.max(frustum.right - frustum.left, frustum.top - frustum.bottom), destination.z, CesiumMath.EPSILON6);
 
-        empty = empty || (scene.mode !== SceneMode.SCENE2D && Cartesian3.equalsEpsilon(destination, camera.position, CesiumMath.EPSILON6));
+        empty = empty || (scene.mode !== SceneMode.SCENE2D &&
+                Cartesian3.equalsEpsilon(destination, camera.position, CesiumMath.EPSILON10) &&
+                CesiumMath.equalsEpsilon(CesiumMath.negativePiToPi(heading), CesiumMath.negativePiToPi(camera.heading), CesiumMath.EPSILON10) &&
+                CesiumMath.equalsEpsilon(CesiumMath.negativePiToPi(pitch), CesiumMath.negativePiToPi(camera.pitch), CesiumMath.EPSILON10) &&
+                CesiumMath.equalsEpsilon(CesiumMath.negativePiToPi(roll), CesiumMath.negativePiToPi(camera.roll), CesiumMath.EPSILON10));
 
         if (empty) {
             return emptyFlight(complete, cancel);

Source/Widgets/Geocoder/GeocoderViewModel.js

@@ -203,30 +203,16 @@ define([
         }
     });
 
-    var scratchPosition = new Cartesian3();
     function updateCamera(viewModel, destination) {
-        var scene = viewModel._scene;
-        if (viewModel._flightDuration === 0) {
-            var isRectangle = defined(destination.west);
-            if (isRectangle) {
-                if (scene.scene.mode !== SceneMode.SCENE3D && destination.west > destination.east) {
-                    destination = Rectangle.MAX_VALUE;
-                }
-                destination = scene.camera.getRectangleCameraCoordinates(destination, scratchPosition);
-            }
-            viewModel._scene.camera.setView({position: destination});
-            viewModel._complete.raiseEvent();
-        } else {
-            viewModel._scene.camera.flyTo({
-                destination : destination,
-                complete: function() {
-                    viewModel._complete.raiseEvent();
-                },
-                duration : viewModel._flightDuration,
-                endTransform : Matrix4.IDENTITY,
-                convert : false
-            });
-        }
+        viewModel._scene.camera.flyTo({
+            destination : destination,
+            complete: function() {
+                viewModel._complete.raiseEvent();
+            },
+            duration : viewModel._flightDuration,
+            endTransform : Matrix4.IDENTITY,
+            convert : false
+        });
     }
 
     function geocode(viewModel) {

Source/Widgets/HomeButton/HomeButtonViewModel.js

@@ -25,6 +25,7 @@ define([
         createCommand) {
     "use strict";
 
+    var pitchScratch = new Cartesian3();
     function viewHome(scene, duration) {
         var mode = scene.mode;
 
@@ -48,26 +49,19 @@ define([
 
             scene.camera.flyTo({
                 destination : destination,
-                orientation : {
-                    heading : 0.0,
-                    pitch : -Math.PI * 0.5,
-                    roll : 0.0
-                },
                 duration : duration,
                 endTransform : Matrix4.IDENTITY
             });
         } else if (mode === SceneMode.COLUMBUS_VIEW) {
             var maxRadii = scene.globe.ellipsoid.maximumRadius;
             var position = new Cartesian3(0.0, -1.0, 1.0);
             position = Cartesian3.multiplyByScalar(Cartesian3.normalize(position, position), 5.0 * maxRadii, position);
-            var pitch = -Math.acos(Cartesian3.normalize(position, new Cartesian3()).z);
-
             scene.camera.flyTo({
                 destination : position,
                 duration : duration,
                 orientation : {
                     heading : 0.0,
-                    pitch : pitch,
+                    pitch : -Math.acos(Cartesian3.normalize(position, pitchScratch).z),
                     roll : 0.0
                 },
                 endTransform : Matrix4.IDENTITY,

Specs/Scene/CameraFlightPathSpec.js

@@ -202,26 +202,26 @@ defineSuite([
     it('does not create a path to the same point', function() {
         var camera = scene.camera;
         camera.position = new Cartesian3(7000000.0, 0.0, 0.0);
-        camera.direction = Cartesian3.negate(Cartesian3.normalize(camera.position, new Cartesian3()), new Cartesian3());
-        camera.up = Cartesian3.clone(Cartesian3.UNIT_Z);
-        camera.right = Cartesian3.normalize(Cartesian3.cross(camera.direction, camera.up, new Cartesian3()), new Cartesian3());
 
         var startPosition = Cartesian3.clone(camera.position);
-        var startDirection = Cartesian3.clone(camera.direction);
-        var startUp = Cartesian3.clone(camera.up);
+        var startHeading= camera.heading;
+        var startPitch = camera.pitch;
+        var startRoll = camera.roll;
 
         var duration = 3.0;
         var flight = CameraFlightPath.createTween(scene, {
             destination : startPosition,
-            direction : startDirection,
-            up : startUp,
+            heading : startHeading,
+            pitch : startPitch,
+            roll: startRoll,
             duration : duration
         });
 
         expect(flight.duration).toEqual(0);
         expect(camera.position).toEqual(startPosition);
-        expect(camera.direction).toEqual(startDirection);
-        expect(camera.up).toEqual(startUp);
+        expect(camera.heading).toEqual(startHeading);
+        expect(camera.pitch).toEqual(startPitch);
+        expect(camera.roll).toEqual(startRoll);
     });
 
     it('creates an animation with 0 duration', function() {
@@ -273,9 +273,13 @@ defineSuite([
         var camera = scene.camera;
 
         camera.position = new Cartesian3(0.0, 0.0, 1000.0);
-        camera.direction = Cartesian3.negate(Cartesian3.UNIT_Z, new Cartesian3());
-        camera.up = Cartesian3.clone(Cartesian3.UNIT_Y);
-        camera.right = Cartesian3.cross(camera.direction, camera.up, new Cartesian3());
+        camera.setView({
+            orientation: {
+                heading: 0,
+                pitch: -CesiumMath.PI_OVER_TWO,
+                roll: 0
+            }
+        });
         camera.frustum = createOrthographicFrustum();
 
         var flight = CameraFlightPath.createTween(scene, {
@@ -290,9 +294,13 @@ defineSuite([
         var camera = scene.camera;
 
         camera.position = new Cartesian3(0.0, 0.0, 1000.0);
-        camera.direction = Cartesian3.negate(Cartesian3.UNIT_Z, new Cartesian3());
-        camera.up = Cartesian3.clone(Cartesian3.UNIT_Y);
-        camera.right = Cartesian3.cross(camera.direction, camera.up, new Cartesian3());
+        camera.setView({
+            orientation: {
+                heading: 0,
+                pitch: -CesiumMath.PI_OVER_TWO,
+                roll: 0
+            }
+        });
 
         var projection = scene.mapProjection;
         var endPosition = projection.ellipsoid.cartographicToCartesian(projection.unproject(camera.position));