Tidy up HeadingPitchRoll API

Apps/Sandcastle/gallery/development/3D Models Node Explorer.html

@@ -181,11 +181,9 @@
 var scene = viewer.scene;
 
 var height = 250000.0;
-var heading = 0.0;
-var pitch = 0.0;
-var roll = 0.0;
+var hpr = new HeadingPitchRoll(0.0, 0.0, 0.0);
 var origin = Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, height);
-var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, heading, pitch, roll);
+var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, hpr);
 
 var model = scene.primitives.add(Cesium.Model.fromGltf({
     url : modelUrl,

Apps/Sandcastle/gallery/development/3D Models.html

@@ -35,9 +35,10 @@
     heading = Cesium.defaultValue(heading, 0.0);
     pitch = Cesium.defaultValue(pitch, 0.0);
     roll = Cesium.defaultValue(roll, 0.0);
+    var hpr = new HeadingPitchRoll(heading, pitch, roll);
 
     var origin = Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, height);
-    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, heading, pitch, roll);
+    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, hpr);
 
     scene.primitives.removeAll(); // Remove previous model
     var model = scene.primitives.add(Cesium.Model.fromGltf({

Apps/Sandcastle/gallery/development/HeadingPitchRoll.html

@@ -107,7 +107,7 @@ <h1>Loading...</h1>
 
 var planePrimitive = scene.primitives.add(Cesium.Model.fromGltf({
     url : '../../SampleData/models/CesiumAir/Cesium_Air.glb',
-    modelMatrix : Cesium.Transforms.aircraftHeadingPitchRollToFixedFrame(position, hpRoll),
+    modelMatrix : Cesium.Transforms.headingPitchRollToFixedFrame(position, hpRoll),
     minimumPixelSize : 128
 }));
 
@@ -208,7 +208,7 @@ <h1>Loading...</h1>
     speedVector = Cesium.Cartesian3.multiplyByScalar(Cesium.Cartesian3.UNIT_X, speed / 10, speedVector);
     position = Cesium.Matrix4.multiplyByPoint(planePrimitive.modelMatrix, speedVector, position);
     pathPosition.addSample(Cesium.JulianDate.now(), position);
-    Cesium.Transforms.aircraftHeadingPitchRollToFixedFrame(position, hpRoll, undefined, planePrimitive.modelMatrix);
+    Cesium.Transforms.headingPitchRollToFixedFrame(position, hpRoll, undefined, planePrimitive.modelMatrix);
 
     if (fromBehind.checked) {
         // Zoom to model

Apps/Sandcastle/gallery/development/Multiple Shadows.html

@@ -74,7 +74,7 @@
 
             var model = scene.primitives.add(Cesium.Model.fromGltf({
                 url : '../../SampleData/models/ShadowTester/Shadow_Tester_Point.gltf',
-                modelMatrix : Cesium.Transforms.headingPitchRollToFixedFrame(center, heading, 0.0, 0.0)
+                modelMatrix : Cesium.Transforms.headingPitchRollToFixedFrame(center, new HeadingPitchRoll(heading, 0.0, 0.0))
             }));
 
             model.readyPromise.then(function(model) {

Apps/Sandcastle/gallery/development/Shadows.html

@@ -585,7 +585,8 @@
 }
 
 function createModel(url, origin) {
-    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, 0.0, 0.0, 0.0);
+    var hpr = new HeadingPitchRoll(0.0, 0.0, 0.0);
+    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, hpr);
 
     var model = scene.primitives.add(Cesium.Model.fromGltf({
         url : url,
@@ -606,7 +607,8 @@
 }
 
 function createBoxRTC(origin) {
-    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, 0.0, 0.0, 0.0);
+    var hpr = new HeadingPitchRoll(0.0, 0.0, 0.0);
+    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, hpr);
 
     var boxGeometry = Cesium.BoxGeometry.createGeometry(Cesium.BoxGeometry.fromDimensions({
         vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT,
@@ -645,7 +647,8 @@
 }
 
 function createBox(origin) {
-    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, 0.0, 0.0, 0.0);
+    var hpr = new HeadingPitchRoll(0.0, 0.0, 0.0);
+    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, hpr);
 
     var box = new Cesium.Primitive({
         geometryInstances : new Cesium.GeometryInstance({
@@ -670,7 +673,8 @@
 }
 
 function createSphere(origin) {
-    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, 0.0, 0.0, 0.0);
+    var hpr = new HeadingPitchRoll(0.0, 0.0, 0.0);
+    var modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(origin, hpr);
 
     var sphere = new Cesium.Primitive({
         geometryInstances : new Cesium.GeometryInstance({

CHANGES.md

@@ -24,7 +24,6 @@ Change Log
 * Removed an unnecessary reprojection of Web Mercator imagery tiles to the Geographic projection on load.  This should improve both visual quality and load performance slightly.
 * Fix a issue where a billboard entity would not render after toggling the show propery. [#4408](https://github.com/AnalyticalGraphicsInc/cesium/issues/4408)
 * Added `Transforms.northUpEastToFixedFrame` to compute a 4x4 local transformation matrix from a reference frame with an north-west-up axes.
-* Added `Transforms.aircraftHeadingPitchRollToFixedFrame` to create a local frame from a position and heading/pitch/roll angles. The local frame is north-west-up axed.
 * Added `Transforms.aircraftHeadingPitchRollQuaternion` which is the quaternion rotation from `Transforms.aircraftHeadingPitchRollToFixedFrame`.
 * Added `HeadingPitchRoll` :
     * `HeadingPitchRoll.fromQuaternion` function for retrieving heading-pitch-roll angles from a quaternion.

Source/Core/Transforms.js

@@ -7,6 +7,7 @@ define([
         './Cartographic',
         './defaultValue',
         './defined',
+        './deprecationWarning',
         './DeveloperError',
         './EarthOrientationParameters',
         './EarthOrientationParametersSample',
@@ -28,6 +29,7 @@ define([
         Cartographic,
         defaultValue,
         defined,
+        deprecationWarning,
         DeveloperError,
         EarthOrientationParameters,
         EarthOrientationParametersSample,
@@ -456,10 +458,12 @@ define([
      * direction where a positive angle is increasing eastward. Pitch is the rotation from the local east-north plane. Positive pitch angles
      * are above the plane. Negative pitch angles are below the plane. Roll is the first rotation applied about the local east axis.
      *
+     * You should pass a HeadingPitchRoll object.  Passing separate heading, pitch, and roll values is deprecated.
+     *
      * @param {Cartesian3} origin The center point of the local reference frame.
-     * @param {Number} heading The heading angle in radians.
-     * @param {Number} pitch The pitch angle in radians.
-     * @param {Number} roll The roll angle in radians.
+     * @param {HeadingPitchRoll|Number} hprOrHeading A HeadingPitchRoll or the heading angle in radians.
+     * @param {Number?} pitch The pitch angle in radians if a HeadingPitchRoll object was not passed.
+     * @param {Number?} roll The roll angle in radians if a HeadingPitchRoll object was not passed.
      * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid whose fixed frame is used in the transformation.
      * @param {Matrix4} [result] The object onto which to store the result.
      * @returns {Matrix4} The modified result parameter or a new Matrix4 instance if none was provided.
@@ -472,51 +476,26 @@ define([
      * var roll = 0.0;
      * var transform = Cesium.Transforms.headingPitchRollToFixedFrame(center, heading, pitch, roll);
      */
-    Transforms.headingPitchRollToFixedFrame = function(origin, heading, pitch, roll, ellipsoid, result) {
+    Transforms.headingPitchRollToFixedFrame = function(origin, hprOrHeading, pitch, roll, ellipsoid, result) {
+        var heading;
+        if (typeof hprOrHeading === 'object') {
+            // Shift arguments using assignments to encourage JIT optimization.
+            ellipsoid = pitch;
+            result = roll;
+            heading = hprOrHeading.heading;
+            pitch = hprOrHeading.pitch;
+            roll = hprOrHeading.roll;
+        } else {
+            deprecationWarning('headingPitchRollToFixedFrame', 'headingPitchRollToFixedFrame with separate heading, pitch, and roll arguments was deprecated in 1.27.  It will be removed in 1.30.  Use a HeadingPitchRoll object.');
+            heading = hprOrHeading;
+        }
         // checks for required parameters happen in the called functions
         var hprQuaternion = Quaternion.fromHeadingPitchRoll(heading, pitch, roll, scratchHPRQuaternion);
         var hprMatrix = Matrix4.fromTranslationQuaternionRotationScale(Cartesian3.ZERO, hprQuaternion, scratchScale, scratchHPRMatrix4);
         result = Transforms.eastNorthUpToFixedFrame(origin, ellipsoid, result);
         return Matrix4.multiply(result, hprMatrix, result);
     };
 
-    /**
-     * Computes a 4x4 transformation matrix from a reference frame with axes computed from the heading-pitch-roll angles
-     * centered at the provided origin to the provided ellipsoid's fixed reference frame. Heading is the rotation from the local north
-     * direction where a positive angle is increasing eastward. Pitch is the rotation from the local east-north plane. Positive pitch angles
-     * are above the plane. Negative pitch angles are below the plane. Roll is the first rotation applied about the local east axis.
-     *
-     * @param {Cartesian3} origin The center point of the local reference frame.
-     * @param {HeadingPitchRoll} headingPitchRoll The heading, pitch, roll angles to apply.
-     * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid whose fixed frame is used in the transformation.
-     * @param {Matrix4} [result] The object onto which to store the result.
-     * @returns {Matrix4} The modified result parameter or a new Matrix4 instance if none was provided.
-     *
-     * @example
-     * // Get the transform from local heading-pitch-roll at cartographic (0.0, 0.0) to Earth's fixed frame.
-     * var center = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
-     * var hpr = new HeadingPitchRoll(0.0, 0.0, 0.0);
-     * var hpr.heading = -Cesium.Math.PI_OVER_TWO;
-     * var hpr.pitch = Cesium.Math.PI_OVER_FOUR;
-     * var hpr.roll = 0.0;
-     * var transform = Cesium.Transforms.aircraftHeadingPitchRollToFixedFrame(center, hpr);
-     */
-    Transforms.aircraftHeadingPitchRollToFixedFrame = function(origin, headingPitchRoll, ellipsoid, result) {
-        // checks for required parameters happen in the called functions
-        //>>includeStart('debug', pragmas.debug);
-        if (!defined(origin)) {
-            throw new DeveloperError('origin is required.');
-        }
-        if (!defined(headingPitchRoll)) {
-            throw new DeveloperError('headingPitchRoll is required.');
-        }
-        //>>includeEnd('debug');
-        var hprQuaternion = Quaternion.fromHeadingPitchRoll(headingPitchRoll.heading, headingPitchRoll.pitch, headingPitchRoll.roll, scratchHPRQuaternion);
-        var hprMatrix = Matrix4.fromTranslationQuaternionRotationScale(Cartesian3.ZERO, hprQuaternion, scratchScale, scratchHPRMatrix4);
-        result = Transforms.northWestUpToFixedFrame(origin, ellipsoid, result);
-        return Matrix4.multiply(result, hprMatrix, result);
-    };
-
     var scratchENUMatrix4 = new Matrix4();
     var scratchHPRMatrix3 = new Matrix3();
 
@@ -574,7 +553,7 @@ define([
      */
     Transforms.aircraftHeadingPitchRollQuaternion = function(origin, headingPitchRoll, ellipsoid, result) {
         // checks for required parameters happen in the called functions
-        var transform = Transforms.aircraftHeadingPitchRollToFixedFrame(origin, headingPitchRoll, ellipsoid, scratchENUMatrix4);
+        var transform = Transforms.headingPitchRollToFixedFrame(origin, headingPitchRoll, ellipsoid, scratchENUMatrix4);
         var rotation = Matrix4.getRotation(transform, scratchHPRMatrix3);
         return Quaternion.fromRotationMatrix(rotation, result);
     };

Specs/Core/TransformsSpec.js

@@ -267,11 +267,12 @@ defineSuite([
         expect(actualTranslation).toEqual(origin);
     });
 
-    it('headingPitchRollToFixedFrame works with a result parameter', function() {
+    it('headingPitchRollToFixedFrame works with a HeadingPitchRoll object and without a result parameter', function() {
         var origin = new Cartesian3(1.0, 0.0, 0.0);
         var heading = CesiumMath.toRadians(20.0);
         var pitch = CesiumMath.toRadians(30.0);
         var roll = CesiumMath.toRadians(40.0);
+        var hpr = new HeadingPitchRoll(heading, pitch, roll);
 
         var expectedRotation = Matrix3.fromQuaternion(Quaternion.fromHeadingPitchRoll(heading, pitch, roll));
         var expectedX = Matrix3.getColumn(expectedRotation, 0, new Cartesian3());
@@ -282,21 +283,19 @@ defineSuite([
         Cartesian3.fromElements(expectedY.z, expectedY.x, expectedY.y, expectedY);
         Cartesian3.fromElements(expectedZ.z, expectedZ.x, expectedZ.y, expectedZ);
 
-        var result = new Matrix4();
-        var returnedResult = Transforms.headingPitchRollToFixedFrame(origin, heading, pitch, roll, Ellipsoid.UNIT_SPHERE, result);
+        var returnedResult = Transforms.headingPitchRollToFixedFrame(origin, hpr, Ellipsoid.UNIT_SPHERE);
         var actualX = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 0, new Cartesian4()));
         var actualY = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 1, new Cartesian4()));
         var actualZ = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 2, new Cartesian4()));
         var actualTranslation = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 3, new Cartesian4()));
 
-        expect(returnedResult).toBe(result);
         expect(actualX).toEqual(expectedX);
         expect(actualY).toEqual(expectedY);
         expect(actualZ).toEqual(expectedZ);
         expect(actualTranslation).toEqual(origin);
     });
 
-    it('aircraftHeadingPitchRollToFixedFrame works without a result parameter', function() {
+    it('headingPitchRollToFixedFrame works with a result parameter', function() {
         var origin = new Cartesian3(1.0, 0.0, 0.0);
         var heading = CesiumMath.toRadians(20.0);
         var pitch = CesiumMath.toRadians(30.0);
@@ -307,47 +306,42 @@ defineSuite([
         var expectedY = Matrix3.getColumn(expectedRotation, 1, new Cartesian3());
         var expectedZ = Matrix3.getColumn(expectedRotation, 2, new Cartesian3());
 
-        Cartesian3.fromElements(expectedX.z, -expectedX.y, expectedX.x, expectedX);
-        Cartesian3.fromElements(expectedY.z, -expectedY.y, expectedY.x, expectedY);
-        Cartesian3.fromElements(expectedZ.z, -expectedZ.y, expectedZ.x, expectedZ);
-
-        scratchHeadingPitchRoll.heading = heading;
-        scratchHeadingPitchRoll.pitch = pitch;
-        scratchHeadingPitchRoll.roll = roll;
+        Cartesian3.fromElements(expectedX.z, expectedX.x, expectedX.y, expectedX);
+        Cartesian3.fromElements(expectedY.z, expectedY.x, expectedY.y, expectedY);
+        Cartesian3.fromElements(expectedZ.z, expectedZ.x, expectedZ.y, expectedZ);
 
-        var returnedResult = Transforms.aircraftHeadingPitchRollToFixedFrame(origin, scratchHeadingPitchRoll, Ellipsoid.UNIT_SPHERE);
+        var result = new Matrix4();
+        var returnedResult = Transforms.headingPitchRollToFixedFrame(origin, heading, pitch, roll, Ellipsoid.UNIT_SPHERE, result);
         var actualX = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 0, new Cartesian4()));
         var actualY = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 1, new Cartesian4()));
         var actualZ = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 2, new Cartesian4()));
         var actualTranslation = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 3, new Cartesian4()));
 
+        expect(returnedResult).toBe(result);
         expect(actualX).toEqual(expectedX);
         expect(actualY).toEqual(expectedY);
         expect(actualZ).toEqual(expectedZ);
         expect(actualTranslation).toEqual(origin);
     });
 
-    it('aircraftHeadingPitchRollToFixedFrame works with a result parameter', function() {
+    it('headingPitchRollToFixedFrame works with a HeadingPitchRoll object and a result parameter', function() {
         var origin = new Cartesian3(1.0, 0.0, 0.0);
         var heading = CesiumMath.toRadians(20.0);
         var pitch = CesiumMath.toRadians(30.0);
         var roll = CesiumMath.toRadians(40.0);
+        var hpr = new HeadingPitchRoll(heading, pitch, roll);
 
         var expectedRotation = Matrix3.fromQuaternion(Quaternion.fromHeadingPitchRoll(heading, pitch, roll));
         var expectedX = Matrix3.getColumn(expectedRotation, 0, new Cartesian3());
         var expectedY = Matrix3.getColumn(expectedRotation, 1, new Cartesian3());
         var expectedZ = Matrix3.getColumn(expectedRotation, 2, new Cartesian3());
 
-        Cartesian3.fromElements(expectedX.z, -expectedX.y, expectedX.x, expectedX);
-        Cartesian3.fromElements(expectedY.z, -expectedY.y, expectedY.x, expectedY);
-        Cartesian3.fromElements(expectedZ.z, -expectedZ.y, expectedZ.x, expectedZ);
-
-        scratchHeadingPitchRoll.heading = heading;
-        scratchHeadingPitchRoll.pitch = pitch;
-        scratchHeadingPitchRoll.roll = roll;
+        Cartesian3.fromElements(expectedX.z, expectedX.x, expectedX.y, expectedX);
+        Cartesian3.fromElements(expectedY.z, expectedY.x, expectedY.y, expectedY);
+        Cartesian3.fromElements(expectedZ.z, expectedZ.x, expectedZ.y, expectedZ);
 
         var result = new Matrix4();
-        var returnedResult = Transforms.aircraftHeadingPitchRollToFixedFrame(origin, scratchHeadingPitchRoll, Ellipsoid.UNIT_SPHERE, result);
+        var returnedResult = Transforms.headingPitchRollToFixedFrame(origin, hpr, Ellipsoid.UNIT_SPHERE, result);
         var actualX = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 0, new Cartesian4()));
         var actualY = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 1, new Cartesian4()));
         var actualZ = Cartesian3.fromCartesian4(Matrix4.getColumn(returnedResult, 2, new Cartesian4()));
@@ -396,7 +390,7 @@ defineSuite([
         scratchHeadingPitchRoll.pitch = CesiumMath.toRadians(30.0);
         scratchHeadingPitchRoll.roll = CesiumMath.toRadians(40.0);
 
-        var transform = Transforms.aircraftHeadingPitchRollToFixedFrame(origin, scratchHeadingPitchRoll, Ellipsoid.UNIT_SPHERE);
+        var transform = Transforms.headingPitchRollToFixedFrame(origin, scratchHeadingPitchRoll, Ellipsoid.UNIT_SPHERE);
         var expected = Matrix4.getRotation(transform, new Matrix3());
 
         var quaternion = Transforms.aircraftHeadingPitchRollQuaternion(origin, scratchHeadingPitchRoll, Ellipsoid.UNIT_SPHERE);
@@ -410,7 +404,7 @@ defineSuite([
         scratchHeadingPitchRoll.pitch = CesiumMath.toRadians(30.0);
         scratchHeadingPitchRoll.roll = CesiumMath.toRadians(40.0);
 
-        var transform = Transforms.aircraftHeadingPitchRollToFixedFrame(origin, scratchHeadingPitchRoll, Ellipsoid.UNIT_SPHERE);
+        var transform = Transforms.headingPitchRollToFixedFrame(origin, scratchHeadingPitchRoll, Ellipsoid.UNIT_SPHERE);
         var expected = Matrix4.getRotation(transform, new Matrix3());
 
         var result = new Quaternion();
@@ -948,18 +942,6 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
-    it('aircraftHeadingPitchRollToFixedFrame throws without an origin', function() {
-        expect(function() {
-            Transforms.aircraftHeadingPitchRollToFixedFrame(undefined, scratchHeadingPitchRoll);
-        }).toThrowDeveloperError();
-    });
-
-    it('aircraftHeadingPitchRollToFixedFrame throws without an headingPitchRoll', function() {
-        expect(function() {
-            Transforms.aircraftHeadingPitchRollToFixedFrame(Cartesian3.ZERO, undefined);
-        }).toThrowDeveloperError();
-    });
-
     it('aircraftHeadingPitchRollQuaternion throws without an origin', function() {
         expect(function() {
             Transforms.aircraftHeadingPitchRollQuaternion(undefined, scratchHeadingPitchRoll);