Class: Matrix3

Matrix3

new Matrix3(column0Row0, column1Row0, column2Row0, column0Row1, column1Row1, column2Row1, column0Row2, column1Row2, column2Row2)

A 3x3 matrix that can be indexed in column first order. For ease of code reading, constructor parameters are arranged in line priority order.

Name Type Default Description
column0Row0 Number 0.0 optional

The value of column 0 and row 0.
column1Row0 Number 0.0 optional

The value in column 1, row 0.
column2Row0 Number 0.0 optional

The value in column 2, row 0.
column0Row1 Number 0.0 optional

The value of column 0 and row 1.
column1Row1 Number 0.0 optional

The value in the first row of the first column.
column2Row1 Number 0.0 optional

The value in the first row of the second column.
column0Row2 Number 0.0 optional

The value in column 0, row 2.
column1Row2 Number 0.0 optional

The value in the second row of the first column.
column2Row2 Number 0.0 optional

The value in the second row of the second column.
See:

Members

lengthNumber

The number of elements used to package objects into an array

(static, constant) COLUMN0ROW0Number

The index of column 0 and row 0 in Matrix3.

(static, constant) COLUMN0ROW1Number

The index of column 0 and row 1 in Matrix3.

(static, constant) COLUMN0ROW2Number

The index of column 0 and row 2 in Matrix3.

(static, constant) COLUMN1ROW0Number

The index of column 1 and row 0 in Matrix3.

(static, constant) COLUMN1ROW1Number

The index of column 1 and row 1 in Matrix3.

(static, constant) COLUMN1ROW2Number

The index of column 1 and row 2 in Matrix3.

(static, constant) COLUMN2ROW0Number

The index of column 2 and row 0 in Matrix3.

(static, constant) COLUMN2ROW1Number

Matrix 3 index in column 2, row 1.

(static, constant) COLUMN2ROW2Number

Matrix 3 index in column 2, row 2.

(static, constant) IDENTITYMatrix3

Initialize an immutable Matrix3 instance as an identity matrix.

static packedLengthNumber

The number of elements used to package objects into an array.

(static, constant) ZEROMatrix3

An immutable Matrix3 instance initialized to a zero matrix.

Methods

clone(result){Matrix3}

Copy the provided Matrix3 instance.

Name Type Description
result Matrix3 optional

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters or a new Matrix3 instance (if not provided).

equals(right){Boolean}

Compare this matrix with the provided matrix, return true if they are equal, otherwise return false.

Name Type Description
right Matrix3 optional

Right hand matrix.
Returns:
Type Description
Boolean If they are equal, it is true; otherwise, it is false.

equalsEpsilon(right, epsilon){Boolean}

Compare this matrix with the provided matrix by component, return true if they are within the provided epsilon, otherwise return false.

Name Type Description
right Matrix3 optional

Right hand matrix.
epsilon Number

The epsilon used for equality testing.
Returns:
Type Description
Boolean If they are within the provided epsilon, it is true; otherwise, it is false.

toString(){String}

Create a string representing this matrix, with each row on a separate row, in the format of '(column0, column1, column2)'.

Returns:
Type Description
String The string representing the provided matrix, with each row on a separate row, in the format of '(column0, column1, column2)'.

static abs(matrix, result){Matrix3}

Calculate a matrix that contains the absolute (unsigned) values of the provided matrix elements.

Name Type Description
matrix Matrix3

A matrix with symbolic elements.
result Matrix3

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters.

static add(left, right, result){Matrix3}

Calculate the sum of two matrices.

Name Type Description
left Matrix3

The first matrix.
right Matrix3

The second matrix.
result Matrix3

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters.

static clone(matrix, result){Matrix3}

Copy Matrix3 instance.

Name Type Description
matrix Matrix3

The matrix to be copied.
result Matrix3 optional

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters or a new Matrix3 instance (if not provided). (If the matrix is undefined, return undefined)

static computeEigenDecomposition(matrix, result){Object}

Calculate the eigenvectors and eigenvalues of a symmetric matrix.

Return a diagonal matrix and a unitary matrix, for example: matrix=unitary matrix * diagonal matrix * transpose (unitary matrix)

The values along the diagonal of the diagonal matrix are eigenvalues. The columns of a unitary matrix are the corresponding eigenvectors.

Name Type Description
matrix Matrix3

Decompose the matrix into diagonal matrix and element matrix. Expected to be a symmetric matrix.
result Object optional

An object with unit and diagonal properties is a matrix used to store results.
Returns:
Type Description
Object The objects with unit and diagonal properties are the unit matrix and diagonal matrix, respectively.
Example
var a = //... symetric matrix
var result = {
    unitary : new SuperMap3D.Matrix3(),
    diagonal : new SuperMap3D.Matrix3()
};
SuperMap3D.Matrix3.computeEigenDecomposition(a, result);

var unitaryTranspose = SuperMap3D.Matrix3.transpose(result.unitary, new SuperMap3D.Matrix3());
var b = SuperMap3D.Matrix3.multiply(result.unitary, result.diagonal, new SuperMap3D.Matrix3());
SuperMap3D.Matrix3.multiply(b, unitaryTranspose, b); // b is now equal to a

var lambda = SuperMap3D.Matrix3.getColumn(result.diagonal, 0, new SuperMap3D.Cartesian3()).x;  // first eigenvalue
var v = SuperMap3D.Matrix3.getColumn(result.unitary, 0, new SuperMap3D.Cartesian3());          // first eigenvector
var c = SuperMap3D.Cartesian3.multiplyByScalar(v, lambda, new SuperMap3D.Cartesian3());        // equal to SuperMap3D.Matrix3.multiplyByVector(a, v)

static determinant(matrix){Number}

Calculate the determinant of the provided matrix.

Name Type Description
matrix Matrix3

The matrix to be used.
Returns:
Type Description
Number The value of the determinant of a matrix.

static equals(left, right){Boolean}

Compare the provided matrices one by one, return true if they are equal, otherwise return false.

Name Type Description
left Matrix3 optional

The first matrix.
right Matrix3 optional

The second matrix.
Returns:
Type Description
Boolean If they are equal, it is true; otherwise, it is false.

static equalsEpsilon(left, right, epsilon){Boolean}

Compare the provided matrices one by one, return true if they are within the provided epsilon, otherwise return false.

Name Type Description
left Matrix3 optional

The first matrix.
right Matrix3 optional

The second matrix.
epsilon Number

The epsilon used for equality testing.
Returns:
Type Description
Boolean If they are within the provided epsilon, it is true; otherwise, it is false.

static fromArray(array, startingIndex, result){Matrix3}

Create a Matrix3 from 9 consecutive elements in the array.

Name Type Default Description
array Array.<Number>

An array with 9 consecutive elements corresponding to the positions of the matrix. Assuming column priority order.
startingIndex Number 0 optional

The offset of the first element in the array corresponds to the position of the first column and first row in the matrix.
result Matrix3 optional

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters or a new Matrix3 instance (if not provided).
Example
// Create the Matrix3:
// [1.0, 2.0, 3.0]
// [1.0, 2.0, 3.0]
// [1.0, 2.0, 3.0]

var v = [1.0, 1.0, 1.0, 2.0, 2.0, 2.0, 3.0, 3.0, 3.0];
var m = SuperMap3D.Matrix3.fromArray(v);

// Create same Matrix3 with using an offset into an array
var v2 = [0.0, 0.0, 1.0, 1.0, 1.0, 2.0, 2.0, 2.0, 3.0, 3.0, 3.0];
var m2 = SuperMap3D.Matrix3.fromArray(v2, 2);

static fromColumnMajorArray(values, result){Matrix3}

Create a Matrix3 instance from a column main sequential array.

Name Type Description
values Array.<Number>

Column main order array.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.

static fromCrossProduct(vector, result){Matrix3}

Compute a Matrix3 instance that represents the cross product equivalent matrix of a Cartesian3 vector.

Name Type Description
vector Cartesian3

The vector on the left side of the cross product operation.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.
Example
// Creates
//   [0.0, -9.0,  8.0]
//   [9.0,  0.0, -7.0]
//   [-8.0, 7.0,  0.0]
var m = SuperMap3D.Matrix3.fromCrossProduct(new SuperMap3D.Cartesian3(7.0, 8.0, 9.0));

static fromHeadingPitchRoll(headingPitchRoll, result){Matrix3}

Calculate a 3x3 rotation matrix from the provided headingDitchRoll. (See) http://en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles )

Name Type Description
headingPitchRoll HeadingPitchRoll

The azimuth, elevation, and rotation to be used.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 A 3x3 rotation matrix for pitch rotation in this direction.

static fromQuaternion(quaternion, result){Matrix3}

Calculate a 3x3 rotation matrix based on the provided quaternions.

Name Type Description
quaternion Quaternion

The quaternion to be used.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 The 3x3 rotation matrix of this quaternion.

static fromRotationX(angle, result){Matrix3}

Create a rotation matrix around the x-axis.

Name Type Description
angle Number

The angle of rotation, measured in radians. The positive angle is counterclockwise.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.
Example
// Rotate a point 45 degrees counterclockwise around the x-axis.
var p = new SuperMap3D.Cartesian3(5, 6, 7);
var m = SuperMap3D.Matrix3.fromRotationX(SuperMap3D.Math.toRadians(45.0));
var rotated = SuperMap3D.Matrix3.multiplyByVector(m, p, new SuperMap3D.Cartesian3());

static fromRotationY(angle, result){Matrix3}

Create a rotation matrix around the y-axis.

Name Type Description
angle Number

The angle of rotation, measured in radians. The positive angle is counterclockwise.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.
Example
// Rotate a point 45 degrees counterclockwise around the y-axis.
var p = new SuperMap3D.Cartesian3(5, 6, 7);
var m = SuperMap3D.Matrix3.fromRotationY(SuperMap3D.Math.toRadians(45.0));
var rotated = SuperMap3D.Matrix3.multiplyByVector(m, p, new SuperMap3D.Cartesian3());

static fromRotationZ(angle, result){Matrix3}

Create a rotation matrix around the z-axis.

Name Type Description
angle Number

The angle of rotation, measured in radians. The positive angle is counterclockwise.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.
Example
// Rotate a point 45 degrees counterclockwise around the z-axis.
var p = new SuperMap3D.Cartesian3(5, 6, 7);
var m = SuperMap3D.Matrix3.fromRotationZ(SuperMap3D.Math.toRadians(45.0));
var rotated = SuperMap3D.Matrix3.multiplyByVector(m, p, new SuperMap3D.Cartesian3());

static fromRowMajorArray(values, result){Matrix3}

Create a Matrix3 instance from the main sequential array of rows. The generated matrix will be arranged in column priority order.

Name Type Description
values Array.<Number>

Row primary order array.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.

static fromScale(scale, result){Matrix3}

Calculate a Matrix3 instance representing non-uniform proportions.

Name Type Description
scale Cartesian3

x. Y and Z scaling factors.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.
Example
// Creates
//   [7.0, 0.0, 0.0]
//   [0.0, 8.0, 0.0]
//   [0.0, 0.0, 9.0]
var m = SuperMap3D.Matrix3.fromScale(new SuperMap3D.Cartesian3(7.0, 8.0, 9.0));

static fromUniformScale(scale, result){Matrix3}

Calculate a Matrix3 instance that represents a uniform proportion.

Name Type Description
scale Number

Unified scaling factor.
result Matrix3 optional

If the object for storing results is undefined, a new instance will be created.
Returns:
Type Description
Matrix3 If the modified result parameters are not provided, they will be the new Matrix3 instance.
Example
// Creates
//   [2.0, 0.0, 0.0]
//   [0.0, 2.0, 0.0]
//   [0.0, 0.0, 2.0]
var m = SuperMap3D.Matrix3.fromUniformScale(2.0);

static getColumn(matrix, index, result){Cartesian3}

Read a copy of the matrix array at the provided index in the form of a Cartesian3 instance.

Name Type Description
matrix Matrix3

The matrix used.
index Number

The zero based index of the column to be retrieved.
result Cartesian3

The object that stores the results.
Throws:

The index must be 0, 1, or 2.

Type
DeveloperError
Returns:
Type Description
Cartesian3 The modified result parameters.

static getElementIndex(row, column){Number}

Calculate the array index of the elements in the rows and columns provided.

Name Type Description
row Number

The zero based index of the row.
column Number

Zero based index of the column.
Throws:

  • The row must be 0, 1, or 2.

    Type
    DeveloperError

  • The column must be 0, 1, or 2.

    Type
    DeveloperError
Returns:
Type Description
Number The index of the elements on the provided rows and columns.
Example
var myMatrix = new SuperMap3D.Matrix3();
var column1Row0Index = SuperMap3D.Matrix3.getElementIndex(1, 0);
var column1Row0 = myMatrix[column1Row0Index]
myMatrix[column1Row0Index] = 10.0;

static getMaximumScale(matrix){Number}

Assuming the matrix is an affine transformation, calculate the maximum proportion. The maximum ratio is the maximum length of the column vector.

Name Type Description
matrix Matrix3

Matrix.
Returns:
Type Description
Number Maximum proportion.

static getRow(matrix, index, result){Cartesian3}

Read a copy of the matrix row at the provided index in the form of a Cartesian3 instance.

Name Type Description
matrix Matrix3

The matrix used.
index Number

The zero based index of the record to be retrieved.
result Cartesian3

The object that stores the results.
Throws:

The index must be 0, 1, or 2.

Type
DeveloperError
Returns:
Type Description
Cartesian3 The modified result parameters.

static getScale(matrix, result){Cartesian3}

Assuming the matrix is an affine transformation, extract non-uniform proportions.

Name Type Description
matrix Matrix3

Matrix.
result Cartesian3

The object that stores the results.
Returns:
Type Description
Cartesian3 The modified result parameters.

static inverse(matrix, result){Matrix3}

Calculate the inverse matrix of the provided matrix.

Name Type Description
matrix Matrix3

The matrix to be reversed.
result Matrix3

The object that stores the results.
Throws:

Matrix is irreversible.

Type
DeveloperError
Returns:
Type Description
Matrix3 The modified result parameters.

static multiply(left, right, result){Matrix3}

Calculate the product of two matrices.

Name Type Description
left Matrix3

The first matrix.
right Matrix3

The second matrix.
result Matrix3

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters.

static multiplyByScalar(matrix, scalar, result){Matrix3}

Calculate the product of a matrix and a scalar.

Name Type Description
matrix Matrix3

Matrix.
scalar Number

The numerical value to be multiplied.
result Matrix3

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters.

static multiplyByScale(matrix, scale, result){Matrix3}

Calculate the product of a matrix multiplied by a non-uniform ratio.

Name Type Description
matrix Matrix3

Left hand matrix.
scale Cartesian3

Non uniform proportion of the right hand.
result Matrix3

The object that stores the results.
See:
Returns:
Type Description
Matrix3 The modified result parameters.
Example
// Instead of SuperMap3D.Matrix3.multiply(m, SuperMap3D.Matrix3.fromScale(scale), m);
SuperMap3D.Matrix3.multiplyByScale(m, scale, m);

static multiplyByVector(matrix, cartesian, result){Cartesian3}

Calculate the product of matrix and column vectors.

Name Type Description
matrix Matrix3

Matrix.
cartesian Cartesian3

special column.
result Cartesian3

The object that stores the results.
Returns:
Type Description
Cartesian3 The modified result parameters.

static negate(matrix, result){Matrix3}

Create a negative copy of the provided matrix.

Name Type Description
matrix Matrix3

The matrix to be negated.
result Matrix3

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters.

static pack(value, array, startingIndex){Array.<Number>}

Store the provided instance in the provided array.

Name Type Default Description
value Matrix3

The value to be packaged.
array Array.<Number>

The array to be packaged.
startingIndex Number 0 optional

Start packaging the array index of elements.
Returns:
Type Description
Array.<Number> The loaded array.

static setColumn(matrix, index, cartesian, result){Matrix3}

Compute a new matrix and replace the specified columns in the matrix with the provided Cartesian3 instance.

Name Type Description
matrix Matrix3

The matrix used.
index Number

The zero base index of the column to be set.
cartesian Cartesian3

Cartesian values will be assigned to the specified column.
result Matrix3

The object that stores the results.
Throws:

The index must be 0, 1, or 2.

Type
DeveloperError
Returns:
Type Description
Matrix3 The modified result parameters.

static setRow(matrix, index, cartesian, result){Matrix3}

Computes a new matrix that replaces the specified row in the provided matrix with the provided Cartesian3 instance.

Name Type Description
matrix Matrix3

The matrix used.
index Number

The zero based index of the row to be set.
cartesian Cartesian3

The Cartesian whose values will be assigned to the specified row.
result Matrix3

The object that stores the results.
Throws:

The index must be 0, 1, or 2.

Type
DeveloperError
Returns:
Type Description
Matrix3 The modified result parameters.

static subtract(left, right, result){Matrix3}

Calculate the difference between two matrices.

Name Type Description
left Matrix3

The first matrix.
right Matrix3

The second matrix.
result Matrix3

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters.

static toArray(matrix, result){Array.<Number>}

Create an Array from the provided Matrix3 instance. This array will be arranged in column priority order.

Name Type Description
matrix Matrix3

The matrix to be used.
result Array.<Number> optional

An array for storing results.
Returns:
Type Description
Array.<Number> Modified Array parameters or new Array instances (if not provided).

static transpose(matrix, result){Matrix3}

Calculate the transpose of the provided matrix.

Name Type Description
matrix Matrix3

The matrix to be transposed.
result Matrix3

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters.

static unpack(array, startingIndex, result){Matrix3}

Retrieve instances from the packaged array.

Name Type Default Description
array Array.<Number>

Packaged array.
startingIndex Number 0 optional

The starting index of the element to be unpacked.
result Matrix3 optional

The object that stores the results.
Returns:
Type Description
Matrix3 The modified result parameters or a new Matrix3 instance (if not provided).