Finish Matrix4 implementation.

CHANGES.md

@@ -54,12 +54,16 @@ Beta Releases
    * `Ellipsoid.toCartographic3s` was renamed to `Ellipsoid.cartesianArrayToCartographicArray`.
    * `Ellipsoid.cartographicDegreesToCartesian` was removed.  Code that previously looked like `ellipsoid.cartographicDegreesToCartesian(new Cartographic(45, 50, 10))` should now look like `ellipsoid.cartographicToCartesian(Cartographic.fromDegrees(45, 50, 10))`.
    * `Math.cartographic3ToRadians`, `Math.cartographic2ToRadians`, `Math.cartographic2ToDegrees`, and `Math.cartographic3ToDegrees` were removed.  These functions are no longer needed because Cartographic instances are always represented in radians. 
-   * The `multiplyWithMatrix` function on each `Matrix` type was renamed to `multiply`. 
    * All functions starting with `multiplyWith` now start with `multiplyBy` to be consistent with functions starting with `divideBy`. 
+   * The `multiplyWithMatrix` function on each `Matrix` type was renamed to `multiply`.
+   * All three Matrix classes have been largely re-written for consistency and performance.  The `values` property has been eliminated and Matrices are no longer immutable.  Code that previously looked like `matrix = matrix.setColumn0Row0(12);` now looks like `matrix[Matrix2.COLUMN0ROW0] = 12;`.  Code that previously looked like `matrix.setColumn3(cartesian3);` now looked like `matrix.setColumn(3, cartesian3, matrix)`. 
 * All `Cartesian2` operations now have static versions that work with any objects exposing `x` and `y` properties.
 * All `Cartesian2` operations now have static versions that work with any objects exposing `x`, `y`, and `z` properties.
 * All `Cartesian3` operations now have static versions that work with any objects exposing `x`, `y`, `z` and `w` properties.
 * All `Cartographic` operations now have static versions that work with any objects exposing `longitude`, `latitude`, and `height` properties.
+* All `Matrix` classes are now indexable like arrays.
+* All `Matrix` operations now have static versions of all prototype functions and anywhere we take a Matrix instance as input can now also take an Array or TypedArray.
+* All `Matrix`, `Cartesian`, and `Cartographic` operations now take an optional result parameter for object re-use to reduce memory pressure.
 * Added `Cartographic.fromDegrees` make creating Cartographic instances from values in degrees easier. 
 * Added `addImage` to `TextureAtlas` so images can be added to a texture atlas after it is constructed.
 * Added `Scene.pickEllipsoid`, which picks either the ellipsoid or the map depending on the current `SceneMode`.

Examples/Sandbox/CodeSnippets/Picking.js

@@ -308,7 +308,7 @@
 
             // Setup code
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             sensors = new Cesium.SensorVolumeCollection(undefined);
             sensor = sensors.addRectangularPyramid({

Examples/Sandbox/CodeSnippets/SensorVolumes.js

@@ -11,7 +11,7 @@
     Sandbox.RectangularPyramidSensorVolume = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var sensors = new Cesium.SensorVolumeCollection(undefined);
             sensors.addRectangularPyramid({
@@ -31,7 +31,7 @@
     Sandbox.CustomSensorVolume = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var directions = [];
             for (var i = 0; i < 20; ++i) {
@@ -58,7 +58,7 @@
     Sandbox.ConicSensorVolume = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var sensors = new Cesium.SensorVolumeCollection(undefined);
             sensors.addComplexConic({
@@ -78,7 +78,7 @@
     Sandbox.ConicSensorVolumeClockAngles = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var sensors = new Cesium.SensorVolumeCollection(undefined);
             sensors.addComplexConic({
@@ -147,7 +147,7 @@
     Sandbox.StripeSensorMaterial = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             // Also try HorizontalStripeMaterial
             var material = new Cesium.HorizontalStripeMaterial(undefined);    // Use default colors
@@ -171,7 +171,7 @@
     Sandbox.DistanceIntervalSensorMaterial = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.DistanceIntervalMaterial({
                 intervals : [
@@ -224,7 +224,7 @@
     Sandbox.CheckerboardSensorMaterial = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.CheckerboardMaterial({
                 lightColor : {
@@ -260,7 +260,7 @@
     Sandbox.DotSensorMaterial = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.DotMaterial({
                 lightColor : {
@@ -296,7 +296,7 @@
     Sandbox.TieDyeSensorMaterial = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.TieDyeMaterial(undefined);    // Use default colors
 
@@ -319,7 +319,7 @@
     Sandbox.FacetSensorMaterial = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.FacetMaterial(undefined); // Use default colors
 
@@ -342,7 +342,7 @@
     Sandbox.BlobSensorMaterial = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.BlobMaterial(undefined);  // Use default colors
 
@@ -370,7 +370,7 @@
             primitives.add(sensors);
 
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var lightColor = {
                 red : 1.0,
@@ -428,7 +428,7 @@
     Sandbox.ErosionSensorAnimation = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.CheckerboardMaterial(undefined);
 
@@ -453,7 +453,7 @@
     Sandbox.AlphaSensorAnimation = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.CheckerboardMaterial(undefined);
 
@@ -478,7 +478,7 @@
     Sandbox.AnimateSensorStripes = function (scene, ellipsoid, primitives) {
         this.code = function () {
             var modelMatrix = Cesium.Transforms.northEastDownToFixedFrame(ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-90.0, 0.0)));
-            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.createTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
+            modelMatrix = modelMatrix.multiply(Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(3000000.0, 0.0, -3000000.0)));
 
             var material = new Cesium.HorizontalStripeMaterial(undefined);   // Use default colors
 

Source/Core/Cartesian3.js

@@ -44,8 +44,13 @@ define(['./DeveloperError'
      * @param {Spherical} spherical The Spherical to be converted to Cartesian3.
      * @param {Cartesian3} [cartesian3] The object in which the result will be stored, if undefined a new instance will be created.
      * @returns The modified result parameter, or a new instance if none was provided.
+     *
+     * @exception {DeveloperError} spherical is required.
      */
     Cartesian3.fromSpherical = function(spherical, result) {
+        if (typeof spherical === 'undefined') {
+            throw new DeveloperError('spherical is required');
+        }
         if (typeof result === 'undefined') {
             result = new Cartesian3();
         }

Source/Core/EllipsoidTangentPlane.js

@@ -30,9 +30,9 @@ define([
         var eastNorthUp = Transforms.eastNorthUpToFixedFrame(o, ellipsoid);
 
         this.origin = o;
-        this.xAxis = Cartesian3.fromCartesian4(eastNorthUp.getColumn0());
-        this.yAxis = Cartesian3.fromCartesian4(eastNorthUp.getColumn1());
-        this.normal = Cartesian3.fromCartesian4(eastNorthUp.getColumn2());
+        this.xAxis = Cartesian3.fromCartesian4(eastNorthUp.getColumn(0));
+        this.yAxis = Cartesian3.fromCartesian4(eastNorthUp.getColumn(1));
+        this.normal = Cartesian3.fromCartesian4(eastNorthUp.getColumn(2));
         this.d = -o.dot(o);
         this.ellipsoid = ellipsoid;
     };

Source/Core/Matrix2.js

@@ -684,10 +684,10 @@ define([
 
     /**
      * Creates a string representing this Matrix with each row being
-     * on a separate line and in the format '(column1, column2)'.
+     * on a separate line and in the format '(column0, column1)'.
      * @memberof Matrix2
      *
-     * @return {String} A string representing the provided Matrix with each row being on a separate line and in the format '(column1, column2)'.
+     * @return {String} A string representing the provided Matrix with each row being on a separate line and in the format '(column0, column1)'.
      */
     Matrix2.prototype.toString = function() {
         return '(' + this[0] + ', ' + this[2] + ')\n' +