MathUtil

Back to documentation index.

### new MathUtil()

A collection of math functions for working with vectors, matrices, quaternions, and other mathematical objects of interest to three-dimensional graphics programming.

## Vectors A vector is a line segment pointing in a certain direction in space and having a certain length and an unspecified starting point. A particular vector can instead be treated as describing a position (by pointing to that position from an origin (0,0,0)), or a color. In MathUtil, vectors are stored in arrays of numbers (usually three or four numbers), and functions dealing with vectors begin with “vec”. If a 4-element vector describes a position or direction, the elements are given as X, Y, Z, and W, in that order. If a 4-element vector describes a color, the elements are given as red, green, blue, and alpha, in that order (where each element ranges from 0-1). If a 3D direction is used in a 4-element vector function (one beginning with “vec4”), use 0 as the fourth element. If a 3D position (point) is used in a 4-element vector function, the fourth element is generally 1. (If the fourth element is anything other than 0, the vector is in homogeneous coordinates, where the 3D position equals the first three elements divided by the fourth.) A unit vector is a vector with a length of 1. (A vector’s length, or norm, is the square root of the sum of the squares of its components.) A vector can be “normalized” to a unit vector by dividing each of its components by its length (doing so won’t change the vector’s direction). The following functions normalize vectors and find their length: MathUtil.vec3normalize converts a 3-element vector to a unit vector; MathUtil.vec4normalize converts a 4-element vector to a unit vector; MathUtil.vec3length finds a 3-element vector’s length; MathUtil.vec4length finds a 4-element vector’s length. Note that due to rounding error, normalizing a vector with a MathUtil method might not necessarily result in a vector with a length of 1. ## Matrices A matrix is a rectangular array that can describe a transformation from one coordinate system to another. Transformations that matrices can describe include translation (shifting), scaling, and rotation. Functions dealing with matrices begin with “mat”. A 3 × 3 or 4 × 4 matrix has 9 or 16 elements, respectively. In mathematical publications, matrices are often notated in column-major order, in which each element of the matrix is placed in columns as opposed to rows, as in the following example:

$\left[\begin{array}{cccc}\mathrm{matrix[0]}& \mathrm{matrix[4]}& \mathrm{matrix[8]}& \mathrm{matrix[12]}\\ \mathrm{matrix[1]}& \mathrm{matrix[5]}& \mathrm{matrix[9]}& \mathrm{matrix[13]}\\ \mathrm{matrix[2]}& \mathrm{matrix[6]}& \mathrm{matrix[10]}& \mathrm{matrix[14]}\\ \mathrm{matrix[3]}& \mathrm{matrix[7]}& \mathrm{matrix[11]}& \mathrm{matrix[15]}\end{array}\right]$

The numbers in brackets in the matrix above are the zero-based indices into the matrix arrays passed to MathUtil’s matrix methods. For 3 × 3 matrices, the elements are arranged in the following order:

$\left[\begin{array}{ccc}\mathrm{matrix[0]}& \mathrm{matrix[3]}& \mathrm{matrix[6]}\\ \mathrm{matrix[1]}& \mathrm{matrix[4]}& \mathrm{matrix[7]}\\ \mathrm{matrix[2]}& \mathrm{matrix[5]}& \mathrm{matrix[8]}\end{array}\right]$

A Matrix Transforms Between Coordinate Systems: A transformed 3D coordinate system is made up of an x-, y-, and z-axes, and a center of the coordinate system. These are four 3-element vectors that describe how the three axes and the center map to the new coordinate system in relation to the old coordinate system. The following depiction of a 4 × 4 matrix illustrates the meaning of each of its elements. To keep things simple, this matrix’s transformation is one that keeps straight lines straight and parallel lines parallel.

$\left[\begin{array}{cccc}\mathrm{[0]\; x-axis\; X}& \mathrm{[4]\; y-axis\; X}& \mathrm{[8]\; z-axis\; X}& \mathrm{[12]\; Center\; X}\\ \mathrm{[1]\; x-axis\; Y}& \mathrm{[5]\; y-axis\; Y}& \mathrm{[9]\; z-axis\; Y}& \mathrm{[13]\; Center\; Y}\\ \mathrm{[2]\; x-axis\; Z}& \mathrm{[6]\; y-axis\; Z}& \mathrm{[10]\; z-axis\; Z}& \mathrm{[14]\; Center\; Z}\\ \mathrm{[3]\; 0}& \mathrm{[7]\; 0}& \mathrm{[11]\; 0}& \mathrm{[15]\; 1}\end{array}\right]$

The following is an example of a transformation matrix.