Add Matrix4.setScale

CHANGES.md

@@ -8,6 +8,7 @@ Change Log
 
 ##### Additions :tada:
 * Added `ClippingPlaneCollection.planeAdded` and `ClippingPlaneCollection.planeRemoved` events.  `planeAdded` is raised when a new plane is added to the collection and `planeRemoved` is raised when a plane is removed. [#6875](https://github.com/AnalyticalGraphicsInc/cesium/pull/6875)
+* Added `Matrix4.setScale` for setting the scale on an affine transformation matrix [#6888](https://github.com/AnalyticalGraphicsInc/cesium/pull/6888)
 
 ##### Fixes :wrench:
 * The Geocoder widget now takes terrain altitude into account when calculating its final destination.

Source/Core/Matrix4.js

@@ -1090,7 +1090,7 @@ define([
      *
      * @param {Matrix4} matrix The matrix to use.
      * @param {Cartesian3} translation The translation that replaces the translation of the provided matrix.
-     * @param {Cartesian4} result The object onto which to store the result.
+     * @param {Matrix4} result The object onto which to store the result.
      * @returns {Matrix4} The modified result parameter.
      */
     Matrix4.setTranslation = function(matrix, translation, result) {
@@ -1123,6 +1123,27 @@ define([
         return result;
     };
 
+    var scaleScratch = new Cartesian3();
+    /**
+     * Computes a new matrix that replaces the scale with the provided scale.  This assumes the matrix is an affine transformation
+     *
+     * @param {Matrix4} matrix The matrix to use.
+     * @param {Cartesian3} scale The scale that replaces the scale of the provided matrix.
+     * @param {Matrix4} result The object onto which to store the result.
+     * @returns {Matrix4} The modified result parameter.
+     */
+    Matrix4.setScale = function(matrix, scale, result) {
+        //>>includeStart('debug', pragmas.debug);
+        Check.typeOf.object('matrix', matrix);
+        Check.typeOf.object('scale', scale);
+        Check.typeOf.object('result', result);
+        //>>includeEnd('debug');
+
+        var existingScale = Matrix4.getScale(matrix, scaleScratch);
+        var newScale = Cartesian3.divideComponents(scale, existingScale, scaleScratch);
+        return Matrix4.multiplyByScale(matrix, newScale, result);
+    };
+
     /**
      * Retrieves a copy of the matrix row at the provided index as a Cartesian4 instance.
      *

Specs/Core/Matrix4Spec.js

@@ -476,6 +476,19 @@ defineSuite([
         expect(result).toEqual(expected);
     });
 
+    it('setScale works', function() {
+        var matrix = Matrix4.clone(Matrix4.IDENTITY);
+        var result = new Matrix4();
+        var newScale = new Cartesian3(1.0, 2.0, 3.0);
+
+        expect(Matrix4.getScale(matrix, new Cartesian3())).toEqual(new Cartesian3(1.0, 1.0, 1.0));
+
+        var returnedResult = Matrix4.setScale(matrix, newScale, result);
+
+        expect(Matrix4.getScale(returnedResult, new Cartesian3())).toEqual(newScale);
+        expect(result).toBe(returnedResult);
+    });
+
     it('getRow works for each row', function() {
         var matrix = new Matrix4(1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0);
         var expectedRow0 = new Cartesian4(1.0, 2.0, 3.0, 4.0);