Class: Matrix

Matrix(m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44)

Represents a 4 x 4 double precision matrix stored in a Float64Array in row-major order.

Constructor

new Matrix(m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44)

Constructs a matrix.
Parameters:
Name Type Description
m11 Number matrix element at row 1, column 1.
m12 Number matrix element at row 1, column 2.
m13 Number matrix element at row 1, column 3.
m14 Number matrix element at row 1, column 4.
m21 Number matrix element at row 2, column 1.
m22 Number matrix element at row 2, column 2.
m23 Number matrix element at row 2, column 3.
m24 Number matrix element at row 2, column 4.
m31 Number matrix element at row 3, column 1.
m32 Number matrix element at row 3, column 2.
m33 Number matrix element at row 3, column 3.
m34 Number matrix element at row 3, column 4.
m41 Number matrix element at row 4, column 1.
m42 Number matrix element at row 4, column 2.
m43 Number matrix element at row 4, column 3.
m44 Number matrix element at row 4, column 4.
Source:

Methods

(static) fromIdentity() → {Matrix}

Creates an identity matrix.
Source:
Returns:
A new identity matrix.
Type
Matrix

(static) principalAxesFromPoints(points, axis1, axis2, axis3)

Computes the principal axes of a point collection expressed in a typed array.
Parameters:
Name Type Description
points Float32Array The points for which to compute the axes, expressed as X0, Y0, Z0, X1, Y1, Z1, ...
axis1 Vec3 A vector in which to return the first (longest) principal axis.
axis2 Vec3 A vector in which to return the second (mid-length) principal axis.
axis3 Vec3 A vector in which to return the third (shortest) principal axis.
Source:
Throws:
If the specified points array is null, undefined or empty, or one of the specified axes arguments is null or undefined.
Type
ArgumentError

clone() → {Matrix}

Creates a new matrix that is a copy of this matrix.
Source:
Returns:
The new matrix.
Type
Matrix

columnMajorComponents(result) → {Float32Array}

Stores this matrix's components in column-major order in a specified array.

The array must have space for at least 16 elements. This matrix's components are stored in the array starting with row 0 column 0 in index 0, row 1 column 0 in index 1, row 2 column 0 in index 2, and so on.

Parameters:
Name Type Description
result Float32Array | Float64Array | Array.<Number> An array of at least 16 elements. Upon return, contains this matrix's components in column-major.
Source:
Throws:
If the specified result array in null or undefined.
Type
ArgumentError
Returns:
The specified result array.
Type
Float32Array

copy(matrix) → {Matrix}

Copies the components of a specified matrix to this matrix.
Parameters:
Name Type Description
matrix Matrix The matrix to copy.
Source:
Throws:
If the specified matrix is null or undefined.
Type
ArgumentError
Returns:
This matrix set to the values of the specified matrix.
Type
Matrix

eigensystemFromSymmetricMatrix(result1, result2, result3)

Computes the eigenvectors of this matrix.

The eigenvectors are returned sorted from the most prominent vector to the least prominent vector. Each eigenvector has length equal to its corresponding eigenvalue.

Parameters:
Name Type Description
result1 Vec3 A pre-allocated vector in which to return the most prominent eigenvector.
result2 Vec3 A pre-allocated vector in which to return the second most prominent eigenvector.
result3 Vec3 A pre-allocated vector in which to return the least prominent eigenvector.
Source:
Throws:
if any argument is null or undefined or if this matrix is not symmetric.
Type
ArgumentError

equals(matrix) → {boolean}

Indicates whether the components of this matrix are equal to those of a specified matrix.
Parameters:
Name Type Description
matrix Matrix The matrix to test equality with. May be null or undefined, in which case this function returns false.
Source:
Returns:
true if all components of this matrix are equal to the corresponding components of the specified matrix, otherwise false.
Type
boolean

extractEyePoint(result) → {Vec3}

Returns this viewing matrix's eye point.

This method assumes that this matrix represents a viewing matrix. If this does not represent a viewing matrix the results are undefined.

In model coordinates, a viewing matrix's eye point is the point the viewer is looking from and maps to the center of the screen.

Parameters:
Name Type Description
result Vec3 A pre-allocated Vec3 in which to return the extracted values.
Source:
Throws:
If the specified result argument is null or undefined.
Type
ArgumentError
Returns:
The specified result argument containing the viewing matrix's eye point, in model coordinates.
Type
Vec3

extractForwardVector(result) → {Vec3}

Returns this viewing matrix's forward vector.

This method assumes that this matrix represents a viewing matrix. If this does not represent a viewing matrix the results are undefined.

Parameters:
Name Type Description
result Vec3 A pre-allocated Vec3 in which to return the extracted values.
Source:
Throws:
If the specified result argument is null or undefined.
Type
ArgumentError
Returns:
The specified result argument containing the viewing matrix's forward vector, in model coordinates.
Type
Vec3

extractRotationAngles(result) → {Vec3}

Returns the rotation angles of this matrix.
Parameters:
Name Type Description
result Vec3 A pre-allocated Vec3 in which to return the rotation angles.
Source:
Throws:
If the specified result argument is null or undefined.
Type
ArgumentError
Returns:
The specified result argument set to the rotation angles of this matrix. The angles are in degrees.
Type
Vec3

extractTranslation(result) → {Vec3}

Returns the translation components of this matrix.
Parameters:
Name Type Description
result Vec3 A pre-allocated Vec3 in which to return the translation components.
Source:
Throws:
If the specified result argument is null or undefined.
Type
ArgumentError
Returns:
The specified result argument set to the translation components of this matrix.
Type
Vec3

extractViewingParameters(origin, roll, globe, result) → {Object}

Extracts this viewing matrix's parameters given a viewing origin and a globe.

This method assumes that this matrix represents a viewing matrix. If this does not represent a viewing matrix the results are undefined.

This returns a parameterization of this viewing matrix based on the specified origin and globe. The origin indicates the model coordinate point that the view's orientation is relative to, while the globe provides the necessary model coordinate context for the origin and the orientation. The origin should be either the view's eye point or a point on the view's forward vector. The view's roll must be specified in order to disambiguate heading and roll when the view's tilt is zero.

The following list outlines the returned key-value pairs and their meanings:

  • 'origin' - The geographic position corresponding to the origin point.
  • 'range' - The distance between the specified origin point and the view's eye point, in model coordinates.
  • 'heading' - The view's heading angle relative to the globe's north pointing tangent at the origin point, in degrees.
  • 'tilt' - The view's tilt angle relative to the globe's normal vector at the origin point, in degrees.
  • 'roll' - The view's roll relative to the globe's normal vector at the origin point, in degrees.
Parameters:
Name Type Description
origin Vec3 The origin of the viewing parameters, in model coordinates.
roll Number The view's roll, in degrees.
globe Globe The globe the viewer is looking at.
result Object A pre-allocated object in which to return the viewing parameters.
Source:
Throws:
If either the specified origin or globe are null or undefined or the specified result argument is null or undefined.
Type
ArgumentError
Returns:
The specified result argument containing a parameterization of this viewing matrix.
Type
Object

invertMatrix(matrix) → {Matrix}

Inverts the specified matrix and stores the result in this matrix.

This throws an exception if the specified matrix is singular.

The result of this method is undefined if this matrix is passed in as the matrix to invert.

Parameters:
Name Type Description
matrix Matrix The matrix whose inverse is computed.
Source:
Throws:
If the specified matrix is null, undefined or cannot be inverted.
Type
ArgumentError
Returns:
This matrix set to the inverse of the specified matrix.
Type
Matrix

invertOrthonormalMatrix(matrix) → {Matrix}

Inverts the specified matrix and stores the result in this matrix.

The specified matrix is assumed to represent an orthonormal transform matrix. This matrix's upper 3x3 is transposed, then its fourth column is transformed by the transposed upper 3x3 and negated.

The result of this method is undefined if this matrix is passed in as the matrix to invert.

Parameters:
Name Type Description
matrix Matrix The matrix whose inverse is computed. This matrix is assumed to represent an orthonormal transform matrix.
Source:
Throws:
If the specified matrix is null or undefined.
Type
ArgumentError
Returns:
This matrix set to the inverse of the specified matrix.
Type
Matrix

multiply(m00, m01, m02, m03, m10, m11, m12, m13, m20, m21, m22, m23, m30, m31, m32, m33) → {Matrix}

Multiplies this matrix by a matrix specified by individual components.
Parameters:
Name Type Description
m00 Number matrix element at row 1, column 1.
m01 Number matrix element at row 1, column 2.
m02 Number matrix element at row 1, column 3.
m03 Number matrix element at row 1, column 4.
m10 Number matrix element at row 2, column 1.
m11 Number matrix element at row 2, column 2.
m12 Number matrix element at row 2, column 3.
m13 Number matrix element at row 2, column 4.
m20 Number matrix element at row 3, column 1.
m21 Number matrix element at row 3, column 2.
m22 Number matrix element at row 3, column 3.
m23 Number matrix element at row 3, column 4.
m30 Number matrix element at row 4, column 1.
m31 Number matrix element at row 4, column 2.
m32 Number matrix element at row 4, column 3.
m33 Number matrix element at row 4, column 4.
Source:
Returns:
This matrix with its components multiplied by the specified values.
Type
Matrix

multiplyByFirstPersonModelview(eyePosition, heading, tilt, roll, globe)

Multiplies this matrix by a first person viewing matrix for the specified globe.

A first person viewing matrix places the viewer's eye at the specified eyePosition. By default the viewer is looking straight down at the globe's surface from the eye position, with the globe's normal vector coming out of the screen and north pointing toward the top of the screen.

Heading specifies the viewer's azimuth, or its angle relative to North. Heading values range from -180 degrees to 180 degrees. A heading of 0 degrees looks North, 90 degrees looks East, +-180 degrees looks South, and -90 degrees looks West.

Tilt specifies the viewer's angle relative to the surface. Tilt values range from -180 degrees to 180 degrees. A tilt of 0 degrees looks straight down at the globe's surface, 90 degrees looks at the horizon, and 180 degrees looks straight up. Tilt values greater than 180 degrees cause the viewer to turn upside down, and are therefore rarely used.

Roll specifies the viewer's angle relative to the horizon. Roll values range from -180 degrees to 180 degrees. A roll of 0 degrees orients the viewer so that up is pointing to the top of the screen, at 90 degrees up is pointing to the right, at +-180 degrees up is pointing to the bottom, and at -90 up is pointing to the left.

Parameters:
Name Type Description
eyePosition Position The viewer's geographic eye position relative to the specified globe.
heading Number The viewer's angle relative to north, in degrees.
tilt Number The viewer's angle relative to the surface, in degrees.
roll Number The viewer's angle relative to the horizon, in degrees.
globe Globe The globe the viewer is looking at.
Source:
Throws:
If the specified position or globe is null or undefined.
Type
ArgumentError

multiplyByLocalCoordinateTransform(origin, globe)

Multiplies this matrix by a local coordinate system transform for the specified globe.

The local coordinate system is defined such that the local origin (0, 0, 0) maps to the specified origin point, the z axis maps to the globe's surface normal at the point, the y-axis maps to the north pointing tangent, and the x-axis maps to the east pointing tangent.

Parameters:
Name Type Description
origin Vec3 The local coordinate system origin, in model coordinates.
globe Globe The globe the coordinate system is relative to.
Source:
Throws:
If either argument is null or undefined.
Type
ArgumentError

multiplyByLookAtModelview(lookAtPosition, range, heading, tilt, roll, globe)

Multiplies this matrix by a look at viewing matrix for the specified globe.

A look at viewing matrix places the center of the screen at the specified lookAtPosition. By default the viewer is looking straight down at the look at position from the specified range, with the globe's normal vector coming out of the screen and north pointing toward the top of the screen.

Range specifies the distance between the look at position and the viewer's eye point. Range values may be any positive real number. A range of 0 places the eye point at the look at point, while a positive range moves the eye point away from but still looking at the look at point.

Heading specifies the viewer's azimuth, or its angle relative to North. Heading values range from -180 degrees to 180 degrees. A heading of 0 degrees looks North, 90 degrees looks East, +-180 degrees looks South, and -90 degrees looks West.

Tilt specifies the viewer's angle relative to the surface. Tilt values range from -180 degrees to 180 degrees. A tilt of 0 degrees looks straight down at the globe's surface, 90 degrees looks at the horizon, and 180 degrees looks straight up. Tilt values greater than 180 degrees cause the viewer to turn upside down, and are therefore rarely used.

Roll specifies the viewer's angle relative to the horizon. Roll values range from -180 degrees to 180 degrees. A roll of 0 degrees orients the viewer so that up is pointing to the top of the screen, at 90 degrees up is pointing to the right, at +-180 degrees up is pointing to the bottom, and at -90 up is pointing to the left.

Parameters:
Name Type Description
lookAtPosition Position The viewer's geographic look at position relative to the specified globe.
range Number The distance between the eye point and the look at point, in model coordinates.
heading Number The viewer's angle relative to north, in degrees.
tilt Number The viewer's angle relative to the surface, in degrees.
roll Number The viewer's angle relative to the horizon, in degrees.
globe Globe The globe the viewer is looking at.
Source:
Throws:
If either the specified look-at position or globe is null or undefined, or the specified range is less than zero.
Type
ArgumentError

multiplyByRotation(x, y, z, angleDegrees) → {Matrix}

Multiplies this matrix by a rotation matrix about a specified axis and angle.
Parameters:
Name Type Description
x Number The X component of the rotation axis.
y Number The Y component of the rotation axis.
z Number The Z component of the rotation axis.
angleDegrees Number The angle to rotate, in degrees.
Source:
Returns:
This matrix multiplied by the rotation matrix implied by the specified values.
Type
Matrix

multiplyByScale(xScale, yScale, zScale) → {Matrix}

Multiplies this matrix by a scale matrix with specified values.
Parameters:
Name Type Description
xScale Number The X scale component.
yScale Number The Y scale component.
zScale Number The Z scale component.
Source:
Returns:
This matrix multiplied by the scale matrix implied by the specified values.
Type
Matrix

multiplyByTextureTransform(texture)

Multiplies this matrix by a texture transform for the specified texture.

A texture image transform maps the bottom-left corner of the texture's image data to coordinate [0,0] and maps the top-right of the texture's image data to coordinate [1,1]. This correctly handles textures whose image data has non-power-of-two dimensions, and correctly orients textures whose image data has its origin in the upper-left corner.

Parameters:
Name Type Description
texture Texture The texture to multiply a transform for.
Source:
Throws:
If the texture is null or undefined.
Type
ArgumentError

multiplyByTranslation(x, y, z) → {Matrix}

Multiplies this matrix by a translation matrix with specified translation values.
Parameters:
Name Type Description
x Number The X translation component.
y Number The Y translation component.
z Number The Z translation component.
Source:
Returns:
This matrix multiplied by the translation matrix implied by the specified values.
Type
Matrix

multiplyMatrix(matrix) → {Matrix}

Multiplies this matrix by a specified matrix.
Parameters:
Name Type Description
matrix Matrix The matrix to multiply with this matrix.
Source:
Throws:
if the specified matrix is null or undefined.
Type
ArgumentError
Returns:
This matrix after multiplying it by the specified matrix.
Type
Matrix

offsetProjectionDepth(depthOffset) → {Matrix}

Applies a specified depth offset to this projection matrix.

This method assumes that this matrix represents a projection matrix. If this does not represent a projection matrix the results are undefined. Projection matrices can be created by calling setToPerspectiveProjection or setToScreenProjection.

The depth offset may be any real number and is typically used to draw geometry slightly closer to the user's eye in order to give those shapes visual priority over nearby or geometry. An offset of zero has no effect. An offset less than zero brings depth values closer to the eye, while an offset greater than zero pushes depth values away from the eye.

Depth offset may be applied to both perspective and orthographic projection matrices. The effect on each projection type is outlined here:

Perspective Projection

The effect of depth offset on a perspective projection increases exponentially with distance from the eye. This has the effect of adjusting the offset for the loss in depth precision with geometry drawn further from the eye. Distant geometry requires a greater offset to differentiate itself from nearby geometry, while close geometry does not.

Orthographic Projection

The effect of depth offset on an orthographic projection increases linearly with distance from the eye. While it is reasonable to apply a depth offset to an orthographic projection, the effect is most appropriate when applied to the projection used to draw the scene. For example, when an object's coordinates are projected by a perspective projection into screen coordinates then drawn using an orthographic projection, it is best to apply the offset to the original perspective projection. The method DrawContext.project performs the correct behavior for the projection type used to draw the scene.

Parameters:
Name Type Description
depthOffset Number The amount of offset to apply.
Source:
Returns:
This matrix with it's depth offset set to the specified offset.
Type
Matrix

set(m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44) → {Matrix}

Sets the components of this matrix to specified values.
Parameters:
Name Type Description
m11 Number matrix element at row 1, column 1.
m12 Number matrix element at row 1, column 2.
m13 Number matrix element at row 1, column 3.
m14 Number matrix element at row 1, column 4.
m21 Number matrix element at row 2, column 1.
m22 Number matrix element at row 2, column 2.
m23 Number matrix element at row 2, column 3.
m24 Number matrix element at row 2, column 4.
m31 Number matrix element at row 3, column 1.
m32 Number matrix element at row 3, column 2.
m33 Number matrix element at row 3, column 3.
m34 Number matrix element at row 3, column 4.
m41 Number matrix element at row 4, column 1.
m42 Number matrix element at row 4, column 2.
m43 Number matrix element at row 4, column 3.
m44 Number matrix element at row 4, column 4.
Source:
Returns:
This matrix with its components set to the specified values.
Type
Matrix

setScale(xScale, yScale, zScale) → {Matrix}

Sets the scale components of this matrix to specified values.
Parameters:
Name Type Description
xScale Number The X scale component.
yScale Number The Y scale component.
zScale Number The Z scale component.
Source:
Returns:
This matrix with its scale components set to the specified values and all other components unmodified.
Type
Matrix

setToCovarianceOfPoints(points) → {Matrix}

Sets this matrix to the symmetric covariance Matrix computed from the x, y, z coordinates of a specified points array.

The computed covariance matrix represents the correlation between each pair of x-, y-, and z-coordinates as they're distributed about the point array's arithmetic mean. Its layout is as follows:

C(x, x) C(x, y) C(x, z)
C(x, y) C(y, y) C(y, z)
C(x, z) C(y, z) C(z, z)

C(i, j) is the covariance of coordinates i and j, where i or j are a coordinate's dispersion about its mean value. If any entry is zero, then there's no correlation between the two coordinates defining that entry. If the returned matrix is diagonal, then all three coordinates are uncorrelated, and the specified point is distributed evenly about its mean point.

Parameters:
Name Type Description
points Float32Array | Float64Array | Array.<Number> The points to consider.
Source:
Throws:
If the specified array of points is null, undefined or empty.
Type
ArgumentError
Returns:
This matrix set to the covariance matrix for the specified list of points.
Type
Matrix

setToIdentity() → {Matrix}

Sets this matrix to the identity matrix.
Source:
Returns:
This matrix set to the identity matrix.
Type
Matrix

setToMultiply(matrixA, matrixB) → {Matrix}

Sets this matrix to the matrix product of two specified matrices.
Parameters:
Name Type Description
matrixA Matrix The first matrix multiplicand.
matrixB Matrix The second matrix multiplicand.
Source:
Throws:
If either specified matrix is null or undefined.
Type
ArgumentError
Returns:
This matrix set to the product of matrixA x matrixB.
Type
Matrix

setToPerspectiveProjection(viewportWidth, viewportHeight, nearDistance, farDistance)

Sets this matrix to a perspective projection matrix for the specified viewport dimensions and clip distances.

A perspective projection matrix maps points in eye coordinates into clip coordinates in a way that causes distant objects to appear smaller, and preserves the appropriate depth information for each point. In model coordinates, a perspective projection is defined by frustum originating at the eye position and extending outward in the viewer's direction. The near distance and the far distance identify the minimum and maximum distance, respectively, at which an object in the scene is visible. Near and far distances must be positive and may not be equal.

Parameters:
Name Type Description
viewportWidth Number The viewport width, in screen coordinates.
viewportHeight Number The viewport height, in screen coordinates.
nearDistance Number The near clip plane distance, in model coordinates.
farDistance Number The far clip plane distance, in model coordinates.
Source:
Throws:
If the specified width or height is less than or equal to zero, if the near and far distances are equal, or if either the near or far distance are less than or equal to zero.
Type
ArgumentError

setToScale(xScale, yScale, zScale) → {Matrix}

Sets this matrix to a scale matrix with specified scale components.
Parameters:
Name Type Description
xScale Number The X scale component.
yScale Number The Y scale component.
zScale Number The Z scale component.
Source:
Returns:
This matrix with its scale components set to those specified and all other components set to that of an identity matrix.
Type
Matrix

setToScreenProjection(viewportWidth, viewportHeight)

Sets this matrix to a screen projection matrix for the specified viewport dimensions.

A screen projection matrix is an orthographic projection that assumes that points in model coordinates represent a screen point and a depth. Screen projection matrices therefore map model coordinates directly into screen coordinates without modification. A point's xy coordinates are interpreted as literal screen coordinates and must be in the viewport to be visible. A point's z coordinate is interpreted as a depth value that ranges from 0 to 1. Additionally, the screen projection matrix preserves the depth value returned by DrawContext.project.

Parameters:
Name Type Description
viewportWidth Number The viewport width, in screen coordinates.
viewportHeight Number The viewport height, in screen coordinates.
Source:
Throws:
If the specified width or height is less than or equal to zero.
Type
ArgumentError

setToTranslation(x, y, z) → {Matrix}

Sets this matrix to a translation matrix with specified translation components.
Parameters:
Name Type Description
x Number The X translation component.
y Number The Y translation component.
z Number The Z translation component.
Source:
Returns:
This matrix with its translation components set to those specified and all other components set to that of an identity matrix.
Type
Matrix

setToTransposeOfMatrix(matrix) → {Matrix}

Sets this matrix to the transpose of a specified matrix.
Parameters:
Name Type Description
matrix Matrix The matrix whose transpose is to be copied.
Source:
Throws:
If the specified matrix in null or undefined.
Type
ArgumentError
Returns:
This matrix, with its values set to the transpose of the specified matrix.
Type
Matrix

setToUnitYFlip() → {Matrix}

Sets this matrix to one that flips and shifts the y-axis.

The resultant matrix maps Y=0 to Y=1 and Y=1 to Y=0. All existing values are overwritten. This matrix is usually used to change the coordinate origin from an upper left coordinate origin to a lower left coordinate origin. This is typically necessary to align the coordinate system of images (top-left origin) with that of OpenGL (bottom-left origin).

Source:
Returns:
This matrix set to values described above.
Type
Matrix

setTranslation(x, y, z) → {Matrix}

Sets the translation components of this matrix to specified values.
Parameters:
Name Type Description
x Number The X translation component.
y Number The Y translation component.
z Number The Z translation component.
Source:
Returns:
This matrix with its translation components set to the specified values and all other components unmodified.
Type
Matrix

unProject(screenPoint, viewport, result) → {boolean}

Transforms the specified screen point from WebGL screen coordinates to model coordinates. This method assumes this matrix represents an inverse modelview-projection matrix. The result of this method is undefined if this matrix is not an inverse modelview-projection matrix.

The screen point is understood to be in WebGL screen coordinates, with the origin in the bottom-left corner and axes that extend up and to the right from the origin.

This function stores the transformed point in the result argument, and returns true or false to indicate whether the transformation is successful. It returns false if the modelview or projection matrices are malformed, or if the screenPoint is clipped by the near clipping plane or the far clipping plane.

Parameters:
Name Type Description
screenPoint Vec3 The screen coordinate point to un-project.
viewport Rectangle The viewport defining the screen point's coordinate system
result Vec3 A pre-allocated vector in which to return the unprojected point.
Source:
Throws:
If either the specified point or result argument is null or undefined.
Type
ArgumentError
Returns:
true if the transformation is successful, otherwise false.
Type
boolean

upper3By3() → {Matrix}

Extracts and returns a new matrix whose upper 3x3 entries are identical to those of this matrix, and whose fourth row and column are 0 except for a 1 in the diagonal position.
Source:
Returns:
The upper 3x3 matrix of this matrix.
Type
Matrix