Menu - Top - Home - Donate to Me

H3DU.Math

Back to documentation index.

H3DU.Math()

A collection of math functions for working with vectors, matrices, quaternions, and other mathematical objects.

See the tutorial "H3DU's Math Functions" for more information.

Members

Methods

H3DU.Math.GlobalPitchRollYaw (constant)

Indicates that a vector's rotation occurs as a pitch, then roll, then yaw (each rotation around the original axes).

H3DU.Math.GlobalPitchYawRoll (constant)

Indicates that a vector's rotation occurs as a pitch, then yaw, then roll (each rotation around the original axes), or in the reverse order around

H3DU.Math.GlobalRollPitchYaw (constant)

Indicates that a vector's rotation occurs as a roll, then pitch, then yaw (each rotation around the original axes).

H3DU.Math.GlobalRollYawPitch (constant)

Indicates that a vector's rotation occurs as a roll, then yaw, then pitch (each rotation around the original axes).

H3DU.Math.GlobalYawPitchRoll (constant)

Indicates that a vector's rotation occurs as a yaw, then pitch, then roll (each rotation around the original axes).

H3DU.Math.GlobalYawRollPitch (constant)

Indicates that a vector's rotation occurs as a yaw, then roll, then pitch (each rotation around the original axes).

H3DU.Math.HalfPi (constant)

Closest approximation to pi divided by 2, or a 90-degree turn in radians.

Default Value: 1.5707963267948966

H3DU.Math.LocalPitchRollYaw (constant)

Indicates that a vector's rotation occurs as a pitch, then roll, then yaw, where the roll and yaw occur around the rotated object's new axes and not necessarily the original axes.

H3DU.Math.LocalPitchYawRoll (constant)

Indicates that a vector's rotation occurs as a pitch, then yaw, then roll, where the yaw and roll occur around the rotated object's new axes and not necessarily the original axes.

H3DU.Math.LocalRollPitchYaw (constant)

Indicates that a vector's rotation occurs as a roll, then pitch, then yaw, where the pitch and yaw occur around the rotated object's new axes and not necessarily the original axes.

H3DU.Math.LocalRollYawPitch (constant)

Indicates that a vector's rotation occurs as a roll, then yaw, then pitch, where the yaw and pitch occur around the rotated object's new axes and not necessarily the original axes.

H3DU.Math.LocalYawPitchRoll (constant)

Indicates that a vector's rotation occurs as a yaw, then pitch, then roll, where the pitch and roll occur around the rotated object's new axes and not necessarily the original axes.

H3DU.Math.LocalYawRollPitch (constant)

Indicates that a vector's rotation occurs as a yaw, then roll, then pitch, where the roll and pitch occur around the rotated object's new axes and not necessarily the original axes.

H3DU.Math.Num180DividedByPi (constant)

Closest approximation to 180 divided by pi, or the number of degrees in a radian. Multiply by this number to convert radians to degrees.

Default Value: 57.29577951308232

H3DU.Math.PiDividedBy180 (constant)

Closest approximation to pi divided by 180, or the number of radians in a degree. Multiply by this number to convert degrees to radians.

Default Value: 0.017453292519943295

H3DU.Math.PiTimes2 (constant)

Closest approximation to pi times 2, or a 360-degree turn in radians.

Default Value: 6.283185307179586

H3DU.Math.PitchRollYaw (constant)

Deprecated: This constant's name is ambiguous between local and global rotations. Use H3DU.Math.GlobalPitchRollYaw instead.

Indicates that a vector's rotation occurs as a pitch, then roll, then yaw (each rotation around the original axes).

H3DU.Math.PitchYawRoll (constant)

Deprecated: This constant's name is ambiguous between local and global rotations. Use H3DU.Math.GlobalPitchYawRoll instead.

Indicates that a vector's rotation occurs as a pitch, then yaw, then roll (each rotation around the original axes).

H3DU.Math.RollPitchYaw (constant)

Deprecated: This constant's name is ambiguous between local and global rotations. Use H3DU.Math.GlobalRollPitchYaw instead.

Indicates that a vector's rotation occurs as a roll, then pitch, then yaw (each rotation around the original axes).

H3DU.Math.RollYawPitch (constant)

Deprecated: This constant's name is ambiguous between local and global rotations. Use H3DU.Math.GlobalRollYawPitch instead.

Indicates that a vector's rotation occurs as a roll, then yaw, then pitch (each rotation around the original axes).

H3DU.Math.ToDegrees (constant)

Closest approximation to 180 divided by pi, or the number of degrees in a radian. Multiply by this number to convert radians to degrees.

H3DU.Math.ToRadians (constant)

Closest approximation to pi divided by 180, or the number of radians in a degree. Multiply by this number to convert degrees to radians.

H3DU.Math.YawPitchRoll (constant)

Deprecated: This constant's name is ambiguous between local and global rotations. Use H3DU.Math.GlobalYawPitchRoll instead.

Indicates that a vector's rotation occurs as a yaw, then pitch, then roll (each rotation around the original axes).

H3DU.Math.YawRollPitch (constant)

Deprecated: This constant's name is ambiguous between local and global rotations. Use H3DU.Math.GlobalYawRollPitch instead.

Indicates that a vector's rotation occurs as a yaw, then roll, then pitch (each rotation around the original axes).

(static) H3DU.Math.boxCenter(box)

Finds the center of a 3D bounding box.

Parameters

Return Value

A 3-element array containing the X, Y, and Z coordinates, respectively, of the bounding box's center. (Type: Array.<number>)

(static) H3DU.Math.boxDimensions(box)

Finds the dimensions of a 3D bounding box. This is done by subtracting the first three values of the given array with its last three values.

Parameters

Return Value

A 3-element array containing the width, height, and depth of the bounding box, respectively. If at least one of the minimum coordinates is greater than its corresponding maximum coordinate, the array can contain negative values. (Type: Array.<number>)

(static) H3DU.Math.boxIsEmpty(box)

Determines whether a 3D bounding box is empty. This is determined if the minimum coordinate is larger than the corresponding maximum coordinate.

Parameters

Return Value

true if at least one of the minimum coordinates is greater than its corresponding maximum coordinate; otherwise, false. (Type: boolean)

(static) H3DU.Math.colorToLinear(srgb)

Converts a color from nonlinearized to linearized sRGB using the sRGB transfer function, and returns a new vector with the result.

Linearized RGB is linear because of its linear relationship of light emitted by a surface of the given color.

Parameters

Return Value

A three-element vector giving the red, green, and blue components, in that order, of the given color in linearized sRGB. The alpha component will be as specified in the "srgb" parameter. (Type: Array.<number>)

(static) H3DU.Math.colorTosRGB(lin)

Converts a color from linearized to nonlinearized sRGB using the sRGB transfer function, and returns a new vector with the result.

Linearized RGB is linear because of its linear relationship of light emitted by a surface of the given color.

Parameters

Return Value

lin A four-element vector giving the red, green, blue, and alpha components, in that order, of the given color in nonlinearized sRGB. The alpha component will be as specified in the "lin" parameter. (Type: Array.<number>)

(static) H3DU.Math.frustumHasBox(frustum, box)

Determines whether an axis-aligned bounding box is at least partially inside a view frustum.

Parameters

Return Value

true if the box may be partially or totally inside the frustum; false if the box is definitely outside the frustum, or if the box is empty (see "boxIsEmpty"). (Type: boolean)

(static) H3DU.Math.frustumHasPoint(frustum, x, y, z)

Determines whether a point is outside or inside a view frustum.

Parameters

Return Value

true if the point is inside; otherwise false; (Type: boolean)

(static) H3DU.Math.frustumHasSphere(frustum, x, y, z, radius)

Determines whether a sphere is at least partially inside a view frustum.

Parameters

Return Value

true if the sphere is partially or totally inside the frustum; false otherwise. (Type: boolean)

(static) H3DU.Math.interpCubicBezier(a, b, c, d, t)

An interpolation timing function based on the path of a cubic Bézier curve with end points (0, 0) and (1, 1) and with two configurable control points. The X coordinates of the curve indicate time, and the Y coordinates of the curve indicate how far the interpolation has reached.

To use this method, you must include the script "extras/interp.js". Example:

<script type="text/javascript" src="extras/interp.js"></script>

Parameters

Return Value

Number ranging from 0 through 1 that indicates how far the interpolation has reached. Returns 0 if t is 0 or less, and 1 if t is 1 or greater. (Type: number)

(static) H3DU.Math.mat3copy(mat)

Returns a copy of a 3x3 matrix.

Parameters

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.mat3identity()

Returns the identity 3x3 matrix (a matrix that keeps vectors unchanged when they are transformed with this matrix).

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.mat3invert(m)

Finds the inverse of a 3x3 matrix, describing a transformation that undoes the given transformation.

Parameters

Return Value

The resulting 3x3 matrix. Returns the identity matrix if this matrix's determinant, or overall scaling factor, is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.mat3multiply(a, b)

Multiplies two 3x3 matrices. A new matrix is returned. The matrices are multiplied such that the transformations they describe happen in reverse order. For example, if the first matrix (input matrix) describes a translation and the second matrix describes a scaling, the multiplied matrix will describe the effect of scaling then translation.

The matrix multiplication is effectively done by breaking up matrix b into three 3-element vectors (the first 3 elements make up the first vector, and so on), transforming each vector with matrix a, and putting the vectors back together into a new matrix.

Parameters

Return Value

The resulting 3x3 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat3transform(mat, v, [vy], [vz])

Transforms a 3-element vector with a 3x3 matrix and returns the transformed vector.

Transforming a vector (v) with a matrix (mat) is effectively done by breaking up mat into three 3-element vectors (the first 3 elements make up the first vector, and so on), multiplying each vector in mat by the corresponding component in v, and adding up the resulting vectors (except v) to get the transformed vector.

Parameters

Return Value

The transformed vector. (Type: Array.<number>)

(static) H3DU.Math.mat3transpose(m3)

Returns the transpose of a 3x3 matrix. (A transpose is a matrix whose rows are converted to columns and vice versa.)

Parameters

Return Value

The resulting 3x3 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat3transposeInPlace(mat)

Transposes a 3x3 matrix in place without creating a new matrix. (A transpose is a matrix whose rows are converted to columns and vice versa.)

Parameters

Return Value

The parameter "mat". (Type: Array.<number>)

(static) H3DU.Math.mat4copy(mat)

Returns a copy of a 4x4 matrix.

Parameters

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.mat4frustum(l, r, b, t, near, far)

Returns a 4x4 matrix representing a perspective projection in the form of a view frustum, or the limits in the "camera"'s view.

When just this matrix is used to transform vertices, the X, Y, and Z coordinates within the view volume (as is the case in WebGL) will range from -W to W (where W is the fourth component of the transformed vertex). For a matrix in which Z coordinates range from 0 to W, divide the 15th element of the result (zero-based index 14) by 2.

This method is designed for enabling a right-handed coordinate system. To adjust the result of this method for a left-handed system, reverse the sign of the 9th, 10th, 11th, and 12th elements of the result (zero-based indices 8, 9, 10, and 11).

Parameters

This value should be greater than 0, and should be set to the highest distance from the "camera" that the application can afford to clip out for being too close, for example, 0.5, 1, or higher.

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4identity()

Returns the identity 4x4 matrix (a matrix that keeps vectors unchanged when they are transformed with this matrix).

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.mat4inverseTranspose3(m4)

Returns the transposed result of the inverted 3x3 upper left corner of the given 4x4 matrix.

This is usually used to convert a model-view matrix (view matrix multiplied by model or world matrix) to a matrix for transforming surface normals in order to keep them perpendicular to a surface transformed by the model-view matrix. Normals are then transformed by this matrix and then converted to unit vectors. But if the input matrix uses only rotations, translations, and/or uniform scaling (same scaling in X, Y, and Z), the 3x3 upper left of the input matrix can be used instead of the inverse-transpose matrix to transform the normals.

Parameters

Return Value

The resulting 3x3 matrix. If the matrix can't be inverted, returns the identity 3x3 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4invert(m)

Finds the inverse of a 4x4 matrix, describing a transformation that undoes the given transformation.

Parameters

Return Value

The resulting 4x4 matrix. Returns the identity matrix if this matrix's determinant, or overall scaling factor, is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.mat4isIdentity(mat)

Returns whether a 4x4 matrix is the identity matrix.

Parameters

Return Value

Return value. (Type: boolean)

(static) H3DU.Math.mat4lookat(viewerPos, [lookingAt], [up])

Returns a 4x4 matrix that represents a camera view, transforming world space coordinates to eye space (or camera space). This essentially rotates a "camera" and moves it to somewhere in the scene. In eye space:

This method is designed for use in a right-handed coordinate system (the Z axis's direction will be from the "camera" to the point looked at). To adjust the result of this method for a left-handed system, reverse the sign of the 1st, 3rd, 5th, 7th, 9th, 11th, 13th, and 15th elements of the result (zero-based indices 0, 2, 4, 6, 8, 10, 12, and 14); the Z axis's direction will thus be from the point looked at to the "camera".

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

Example

The following example calls this method with an up vector of (0, 1, 0) except if the view direction is parallel to that vector or nearly so.

var upVector=[0,1,0]; // Y axis
var viewdir=HMath.vec3sub(lookingAt, viewerPos);
var par=HMath.vec3length(HMath.vec3cross(viewdir,upVector));
if(par<0.00001)upVector=[0,0,1]; // view is almost parallel, so use Z axis
var matrix=HMath.mat4lookat(viewerPos,lookingAt,upVector);

The following example creates an isometric projection for a right-handed coordinate system. The Y axis will point up, the Z axis toward the bottom left, and the X axis toward the bottom right.

// Assumes an orthographic projection matrix is used. Example:
// var projectionMatrix=H3DU.Math.mat4ortho(-10,10,-10,10,-50,50);
// Camera will be at (1,1,1) -- actually (sqrt(1/3),sqrt(1/3),sqrt(1/3)) --
// and point toward [0,0,0]
var lookPoint=[0,0,0];
var cameraPoint=H3DU.Math.vec3normalize([1,1,1]);
cameraPoint=H3DU.Math.vec3add(cameraPoint,lookPoint);
var matrix=HMath.mat4lookat(cameraPoint,lookPoint);

The following example is like the previous example, but with the Z axis pointing up.

var lookPoint=[0,0,0];
var cameraPoint=H3DU.Math.vec3normalize([1,1,1]);
cameraPoint=H3DU.Math.vec3add(cameraPoint,lookPoint);
// Positive Z axis is the up vector
var matrix=HMath.mat4lookat(cameraPoint,lookPoint,[0,0,1]);

(static) H3DU.Math.mat4multiply(a, b)

Multiplies two 4x4 matrices. A new matrix is returned. The matrices are multiplied such that the transformations they describe happen in reverse order. For example, if the first matrix (input matrix) describes a translation and the second matrix describes a scaling, the multiplied matrix will describe the effect of scaling then translation.

The matrix multiplication is effectively done by breaking up matrix b into four 4-element vectors (the first 4 elements make up the first vector, and so on), transforming each vector with matrix a, and putting the vectors back together into a new matrix.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4oblique(alpha, phi)

Returns a 4x4 view matrix representing an oblique projection, when used in conjunction with an orthographic projection.

This method works the same way in right-handed and left-handed coordinate systems.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4ortho(l, r, b, t, n, f)

Returns a 4x4 matrix representing an orthographic projection. In this projection, the left clipping plane is parallel to the right clipping plane and the top to the bottom.

The projection returned by this method only scales and/or shifts the view, so that objects with the same size won't appear smaller as they get more distant from the "camera".

When just this matrix is used to transform vertices, the X, Y, and Z coordinates within the view volume (as is the case in WebGL) will range from -1 to 1. For a matrix in which Z coordinates range from 0 to 1, divide the 11th and 15th elements of the result (zero-based indices 10 and 14) by 2, then add 0.5 to the 15th element.

This method is designed for enabling a right-handed coordinate system. To adjust the result of this method for a left-handed system, reverse the sign of the 11th element of the result (zero-based index 10).

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4ortho2d(l, r, b, t)

Returns a 4x4 matrix representing a 2D orthographic projection.

This is the same as mat4ortho() with the near clipping plane set to -1 and the far clipping plane set to 1.

This method is designed for enabling a right-handed coordinate system. See mat4ortho() for information on the meaning of coordinates when using this matrix and on adjusting the matrix for other conventions.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4ortho2dAspect(l, r, b, t, aspect)

Returns a 4x4 matrix representing a 2D orthographic projection, retaining the view rectangle's aspect ratio.

If the view rectangle's aspect ratio doesn't match the desired aspect ratio, the view rectangle will be centered on the viewport or otherwise moved and scaled so as to keep the entire view rectangle visible without stretching or squishing it.

This is the same as mat4orthoAspect() with the near clipping plane set to -1 and the far clipping plane set to 1.

This method is designed for enabling a right-handed coordinate system. See mat4ortho() for information on the meaning of coordinates when using this matrix and on adjusting the matrix for other conventions.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4orthoAspect(l, r, b, t, n, f, aspect)

Returns a 4x4 matrix representing an orthographic projection, retaining the view rectangle's aspect ratio.

If the view rectangle's aspect ratio doesn't match the desired aspect ratio, the view rectangle will be centered on the viewport or otherwise moved and scaled so as to keep the entire view rectangle visible without stretching or squishing it.

The projection returned by this method only scales and/or shifts the view, so that objects with the same size won't appear smaller as they get more distant from the "camera".

This method is designed for enabling a right-handed coordinate system. See mat4ortho() for information on the meaning of coordinates when using this matrix and on adjusting the matrix for other conventions.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4perspective(fovY, aspectRatio, near, far)

Returns a 4x4 matrix representing a perspective projection.

When just this matrix is used to transform vertices, the X, Y, and Z coordinates within the view volume (as is the case in WebGL) will range from -W to W (where W is the fourth component of the transformed vertex) and increase from left to right and bottom to top. For a matrix in which Z coordinates range from 0 to W, divide the 15th element of the result (zero-based index 14) by 2.

This method is designed for enabling a right-handed coordinate system. To adjust the result of this method for a left-handed system, reverse the sign of the 9th, 10th, 11th, and 12th elements of the result (zero-based indices 8, 9, 10, and 11).

Parameters

This value should be greater than 0, and should be set to the highest distance from the "camera" that the application can afford to clip out for being too close, for example, 0.5, 1, or higher.

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4perspectiveHorizontal(fovX, aspectRatio, near, far)

Returns a 4x4 matrix representing a perspective projection, given an X axis field of view. When just this matrix is used to transform vertices, the X, Y, and Z coordinates within the view volume (as is the case in WebGL) will range from -W to W (where W is the fourth component of the transformed vertex) and increase from left to right and bottom to top. For a matrix in which Z coordinates range from 0 to W, divide the 15th element of the result (zero-based index 14) by 2.

This method is designed for enabling a right-handed coordinate system. To adjust the result of this method for a left-handed system, reverse the sign of the 9th, 10th, 11th, and 12th elements of the result (zero-based indices 8, 9, 10, and 11).

Parameters

This value should be greater than 0, and should be set to the highest distance from the "camera" that the application can afford to clip out for being too close, for example, 0.5, 1, or higher.

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4projectVec3(mat, v, [vy], [vz])

Transforms a 3-element vector with a 4x4 matrix and returns a perspective-correct version of the vector as a 3D point.

The transformation involves transforming a 4-element vector with the same X, Y, and Z coordinates, but with a W coordinate equal to 1, with the 4x4 matrix, and then dividing X, Y, and Z of the transformed 4-element vector by that vector's W (a perspective divide), then returning that vector's new X, Y, and Z.

Parameters

Return Value

The transformed 3-element vector. The elements, in order, are the transformed vector's X, Y, and Z coordinates. (Type: Array.<number>)

(static) H3DU.Math.mat4rotate(mat, angle, v, vy, vz)

Multiplies a 4x4 matrix by a rotation transformation that rotates vectors by the given rotation angle and around the given axis of rotation, and returns a new matrix. The effect will be that the rotation transformation will happen before the transformation described in the given matrix, when applied in the global coordinate frame.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4rotated(angle, v, vy, vz)

Returns a 4x4 matrix representing a rotation transformation that rotates vectors by the given rotation angle and around the given axis of rotation.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4scale(mat, v3, v3y, v3z)

Multiplies a 4x4 matrix by a scaling transformation.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4scaleInPlace(mat, v3, [v3y], [v3z])

Modifies a 4x4 matrix by multiplying it by a scaling transformation.

Parameters

Return Value

The same parameter as "mat". (Type: Array.<number>)

(static) H3DU.Math.mat4scaled(v3, v3y, v3z)

Returns a 4x4 matrix representing a scaling transformation.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4toFrustumPlanes(matrix)

Finds the six clipping planes of a view frustum defined by a 4x4 matrix. These six planes together form the shape of a "chopped-off" pyramid (or frustum).

In this model, the eye, or camera, is placed at the top of the pyramid (before being chopped off), four planes are placed at the pyramid's sides, one plane (the far plane) forms its base, and a final plane (the near plane) is the pyramid's chopped off top.

Parameters

Return Value

An array of six 4-element arrays representing the six clipping planes of the view frustum. In order, they are the left, right, top, bottom, near, and far clipping planes. All six planes will be normalized (see H3DU.Math.planeNormalizeInPlace). (Type: Array.<Array.<number>>)

(static) H3DU.Math.mat4toMat3(m4)

Returns the upper-left part of a 4x4 matrix as a new 3x3 matrix.

Parameters

Return Value

The resulting 3x3 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4transform(mat, v, [vy], [vz], [vw])

Transforms a 4-element vector with a 4x4 matrix and returns the transformed vector.

Transforming a vector (v) with a matrix (mat) is effectively done by breaking up mat into four 4-element vectors (the first 4 elements make up the first vector, and so on), multiplying each vector in mat by the corresponding component in v, and adding up the resulting vectors (except v) to get the transformed vector.

Parameters

Return Value

The transformed vector. (Type: Array.<number>)

(static) H3DU.Math.mat4transformVec3(mat, v, [vy], [vz])

Transforms a 3-element vector with a 4x4 matrix as though it were an affine transformation matrix (without perspective) and returns the transformed vector. The effect is as though elements 3, 7, 11, and 15 (counting from 0) of the matrix were assumed to be (0, 0, 0, 1) instead of their actual values and as though the 3-element vector had a fourth element valued at 1.

For most purposes, use the H3DU.Math.mat4projectVec3 method instead, which supports 4x4 matrices that may be in a perspective projection (whose last row is not necessarily (0, 0, 0, 1)).

Parameters

Return Value

The transformed 3-element vector. (Type: Array.<number>)

(static) H3DU.Math.mat4translate(mat, v3, v3y, v3z)

Multiplies a 4x4 matrix by a translation transformation.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4translated(v3, v3y, v3z)

Returns a 4x4 matrix representing a translation.

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4transpose(m4)

Returns the transpose of a 4x4 matrix. (A transpose is a matrix whose rows are converted to columns and vice versa.)

Parameters

Return Value

The resulting 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.mat4transposeInPlace(mat)

Transposes a 4x4 matrix in place without creating a new matrix. (A transpose is a matrix whose rows are converted to columns and vice versa.)

Parameters

Return Value

The parameter "mat". (Type: Array.<number>)

(static) H3DU.Math.planeFromNormalAndPoint(normal, point)

Creates a plane from a normal vector and a point on the plane.

Parameters

Return Value

A four-element array describing the plane. (Type: Array.<number>)

(static) H3DU.Math.planeNorm(plane)

Deprecated: Use H3DU.Math.planeNormalize instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.planeNormalize.

Parameters

Return Value

The normalized plane. (Type: Array.<number>)

(static) H3DU.Math.planeNormInPlace(plane)

Deprecated: Use H3DU.Math.planeNormalizeInPlace instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.planeNormalizeInPlace.

Parameters

Return Value

The parameter "plane" (Type: Array.<number>)

(static) H3DU.Math.planeNormalize(plane)

Normalizes this plane so that its normal is a unit vector, unless all the normal's components are 0, and returns a new plane with the result. The plane's distance will be divided by the normal's length. Returns a new plane.

Parameters

Return Value

A normalized version of the plane. Note that due to rounding error, the length of the plane's normal might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.planeNormalizeInPlace(plane)

Normalizes this plane so that its normal is a unit vector, unless all the normal's components are 0, and sets this plane to the result. The plane's distance will be divided by the current normal's length.

Parameters

Return Value

The parameter "plane". (Type: Array.<number>)

(static) H3DU.Math.quatConjugate(quat)

Returns a quaternion that describes a rotation that undoes the given rotation (an "inverted" rotation); this is done by reversing the sign of the X, Y, and Z components (which describe the quaternion's axis of rotation). The return value won't necessarily be a unit vector.

Parameters

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.quatCopy(a)

Returns a copy of a quaternion.

Parameters

Return Value

Return value. (Type: Array.<number>)

See Also

H3DU.Math.vec4copy

(static) H3DU.Math.quatDot(a, b)

Finds the dot product of two quaternions. It's equal to the sum of the products of their components (for example, a's X times b's X).

Parameters

Return Value

Return value. (Type: number)

See Also

H3DU.Math.vec4dot

(static) H3DU.Math.quatFromAxisAngle(angle, v, vy, vz)

Generates a quaternion from a rotation transformation that rotates vectors by the given rotation angle and around the given axis of rotation,

Parameters

Return Value

The generated quaternion. A quaternion's first three elements (X, Y, Z) describe an axis of rotation whose length is the sine of half of "angle", and its fourth element (W) is the cosine of half of "angle". (Type: Array.<number>)

(static) H3DU.Math.quatFromMat4(m)

Generates a quaternion from the vector rotation described in a 4x4 matrix. The upper 3x3 portion of the matrix is used for this calculation. The results are undefined if the matrix includes any transformation other than rotation.

Parameters

Return Value

The resulting quaternion. (Type: Array.<number>)

(static) H3DU.Math.quatFromTaitBryan(pitchDegrees, yawDegrees, rollDegrees, [mode])

Generates a quaternion from pitch, yaw and roll angles (or Tait-Bryan angles). See "Axis of Rotation" in "H3DU's Math Functions" for the meaning of each angle.

Parameters

Return Value

The generated quaternion. (Type: Array.<number>)

(static) H3DU.Math.quatFromVectors(vec1, vec2)

Generates a quaternion describing a rotation between two 3-element vectors. The quaternion will describe the rotation required to rotate the ray described in the first vector toward the ray described in the second vector. The vectors need not be unit vectors.

Parameters

Return Value

The generated quaternion, which will be a unit vector. (Type: Array.<number>)

(static) H3DU.Math.quatIdentity()

Returns the identity quaternion of multiplication, (0, 0, 0, 1).

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.quatInverse(quat)

Deprecated: Use H3DU.Math.quatInvert instead.

Inverts the rotation given in this quaternion, describing a rotation that undoes the given rotation. Returns a new quaternion; same as the quatInverse method.

Parameters

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.quatInvert(quat)

Returns a quaternion that describes a rotation that undoes the given rotation (an "inverted" rotation) and is converted to a unit vector.

Parameters

Return Value

Return value. (Type: Array.<number>)

See Also

H3DU.Math.quatConjugate

(static) H3DU.Math.quatIsIdentity(quat)

Returns whether this quaternion is the identity quaternion, (0, 0, 0, 1).

Parameters

Return Value

Return value. (Type: boolean)

(static) H3DU.Math.quatLength(quat)

Returns the distance of this quaternion from the origin. It's the same as the square root of the sum of the squares of its components.

Parameters

Return Value

Return value. (Type: number)

See Also

H3DU.Math.vec4length

(static) H3DU.Math.quatMultiply(a, b)

Multiplies two quaternions, creating a composite rotation. The quaternions are multiplied such that the second quaternion's rotation happens before the first quaternion's rotation when applied in the global coordinate frame.

If both quaternions are unit vectors, the resulting quaternion will also be a unit vector. However, for best results, you should normalize the quaternions every few multiplications (using H3DU.Math.quatNormalize or H3DU.Math.quatNormalizeInPlace), since successive multiplications can cause rounding errors.

Quaternion multiplication is not commutative except in the last component of the resulting quaternion, since the definition of quaternion multiplication includes taking a cross product of a's and b's first three components, in that order, and the cross product is not commutative (see also H3DU.Math.vec3cross).

Parameters

Return Value

The resulting quaternion. (Type: Array.<number>)

(static) H3DU.Math.quatNlerp(q1, q2, factor)

Returns a quaternion that lies along the shortest path between the given two quaternion rotations, using a linear interpolation function, and converts it to a unit vector. This is called a normalized linear interpolation, or "nlerp".

Because the shortest path is curved, not straight, this method will generally not interpolate at constant velocity; however, the difference in this velocity when interpolating is rarely noticeable and this method is generally faster than the H3DU.Math.quatSlerp method.

Parameters

Return Value

The interpolated quaternion, which will be a unit vector. (Type: Array.<number>)

(static) H3DU.Math.quatNorm(quat)

Deprecated: Use H3DU.Math.quatNormalize instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.quatNormalize.

Parameters

Return Value

The normalized quaternion. (Type: Array.<number>)

(static) H3DU.Math.quatNormInPlace(quat)

Deprecated: Use H3DU.Math.quatNormalizeInPlace instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.quatNormalizeInPlace.

Parameters

Return Value

The parameter "quat" (Type: Array.<number>)

(static) H3DU.Math.quatNormalize(quat)

Converts a quaternion to a unit vector; returns a new quaternion. When a quaternion is normalized, the distance from the origin to that quaternion becomes 1 (unless all its components are 0). A quaternion is normalized by dividing each of its components by its length.

Parameters

Return Value

The normalized quaternion. Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

See Also

H3DU.Math.vec4normalize

(static) H3DU.Math.quatNormalizeInPlace(quat)

Converts a quaternion to a unit vector. When a quaternion is normalized, it describes the same rotation but the distance from the origin to that quaternion becomes 1 (unless all its components are 0). A quaternion is normalized by dividing each of its components by its length.

Parameters

Return Value

The parameter "quat". Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

See Also

H3DU.Math.vec4normalizeInPlace

(static) H3DU.Math.quatRotate(quat, angle, v, vy, vz)

Multiplies a quaternion by a rotation transformation that rotates vectors by the given rotation angle and around the given axis of rotation. The result is such that the angle-axis rotation happens before the quaternion's rotation when applied in the global coordinate frame.

This method is equivalent to the following (see also H3DU.Math.quatMultiply):

return quatMultiply(quat,quatFromAxisAngle(angle,v,vy,vz));

Parameters

Return Value

The resulting quaternion. (Type: Array.<number>)

(static) H3DU.Math.quatScale(a, scalar)

Multiplies each element of a quaternion by a factor and returns the result as a new quaternion.

Parameters

Return Value

The resulting quaternion. (Type: Array.<number>)

See Also

H3DU.Math.vec4scaleInPlace

(static) H3DU.Math.quatScaleInPlace(a, scalar)

Multiplies each element of a quaternion by a factor and stores the result in that quaternion.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

See Also

H3DU.Math.vec4scaleInPlace

(static) H3DU.Math.quatSlerp(q1, q2, factor)

Returns a quaternion that lies along the shortest path between the given two quaternion rotations, using a spherical interpolation function. This is called spherical linear interpolation, or "slerp". (A spherical interpolation finds the shortest angle between the two quaternions -- which are treated as 4D vectors -- and then finds a vector with a smaller angle between it and the first quaternion. The "factor" parameter specifies how small the new angle will be relative to the original angle.)

This method will generally interpolate at constant velocity; however, this method is commutative (the order in which the quaternions are given matters), unlike quatNlerp, making it unsuitable for blending multiple quaternion rotations, and this method is generally more computationally expensive than the quatNlerp method.

Parameters

Return Value

The interpolated quaternion. (Type: Array.<number>)

See Also

"Understanding Slerp, Then Not Using It", Jonathan Blow, for additional background

(static) H3DU.Math.quatToAxisAngle(a)

Calculates the vector rotation for this quaternion in the form of the angle to rotate the vector by and an axis of rotation to rotate that vector around.

Parameters

Return Value

A 4-element array giving the axis of rotation as the first three elements, followed by the angle in degrees as the fourth element. If "a" is a unit vector, the axis of rotation will be a unit vector. (Type: Array.<number>)

(static) H3DU.Math.quatToMat4(quat)

Generates a 4x4 matrix describing the rotation described by this quaternion.

Parameters

Return Value

The generated 4x4 matrix. (Type: Array.<number>)

(static) H3DU.Math.quatToTaitBryan(a, [mode])

Converts this quaternion to the same version of the rotation in the form of pitch, yaw, and roll angles (or Tait-Bryan angles).

Parameters

Return Value

A 3-element array containing the pitch, yaw, and roll angles (X, Y, and Z axis angles), in that order and in degrees, by which to rotate vectors. See "Axis of Rotation" in "H3DU's Math Functions" for the meaning of each angle. (Type: Array.<number>)

(static) H3DU.Math.quatTransform(q, v)

Transforms a 3- or 4-element vector using a quaternion's vector rotation.

Parameters

Return Value

A 4-element vector representing the transformed vector. The fourth element will be 1.0. If the input vector has 3 elements, a 3-element vector will be returned instead. (Type: Array.<number>)

(static) H3DU.Math.vec2abs(a)

Returns a new 2-element vector with the absolute value of each of its components.

Parameters

Return Value

The resulting 2-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec2absInPlace(a)

Sets each component of the given 2-element vector to its absolute value.

Parameters

Return Value

The vector "a". (Type: Array.<number>)

(static) H3DU.Math.vec2add(a, b)

Adds two 2-element vectors and returns a new vector with the result. Adding two vectors is the same as adding each of their components. The resulting vector:

Parameters

Return Value

The resulting 2-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec2addInPlace(a, b)

Adds two 2-element vectors and stores the result in the first vector. Adding two vectors is the same as adding each of their components. The resulting vector:

Parameters

Return Value

The parameter "a" (Type: Array.<number>)

(static) H3DU.Math.vec2assign(dst, src)

Assigns the values of a 2-element vector into another 2-element vector.

Parameters

Return Value

The parameter "dst" (Type: Array.<number>)

(static) H3DU.Math.vec2clamp(a, min, max)

Returns a 2-element vector in which each element of the given 2-element vector is clamped so it's not less than one value or greater than another value.

Parameters

Return Value

The resulting vector. (Type: Array.<number>)

(static) H3DU.Math.vec2clampInPlace(a, min, max)

Clamps each element of the given 2-element vector so it's not less than one value or greater than another value.

Parameters

Return Value

The resulting vector. (Type: Array.<number>)

(static) H3DU.Math.vec2copy(vec)

Returns a copy of a 2-element vector.

Parameters

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.vec2dist(vecFrom, vecTo)

Finds the straight-line distance from one three-element vector to another, treating both as 3D points.

Parameters

Return Value

The distance between the two vectors. (Type: number)

(static) H3DU.Math.vec2dot(a, b)

Finds the dot product of two 2-element vectors. It's the sum of the products of their components (for example, a's X times b's X).

For properties of the dot product, see H3DU.Math.vec3dot.

Parameters

Return Value

A number representing the dot product. (Type: number)

Example

The following shows a fast way to compare a vector's length using the dot product.

// Check if the vector's length squared is less than 20 units squared
if(H3DU.Math.vec2dot(vector, vector)<20*20) {
// The vector's length is shorter than 20 units
}

(static) H3DU.Math.vec2length(a)

Returns the distance of this 2-element vector from the origin, also known as its length or magnitude. It's the same as the square root of the sum of the squares of its components.

Note that if vectors are merely sorted or compared by their lengths (and those lengths are not added or multiplied together or the like), it's faster to sort or compare them by the squares of their lengths (to find the square of a 2-element vector's length, call H3DU.Math.vec2dot passing the same vector as both of its arguments).

Parameters

Return Value

Return value. (Type: number)

(static) H3DU.Math.vec2lerp(v1, v2, factor)

Does a linear interpolation between two 2-element vectors; returns a new vector.

Parameters

Return Value

The interpolated vector. (Type: Array.<number>)

(static) H3DU.Math.vec2mul(a, b)

Multiplies each of the components of two 2-element vectors and returns a new vector with the result.

Parameters

Return Value

The resulting 2-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec2mulInPlace(a, b)

Multiplies each of the components of two 2-element vectors and stores the result in the first vector.

Parameters

Return Value

The parameter "a" (Type: Array.<number>)

(static) H3DU.Math.vec2negate(a)

Negates a 2-element vector and returns a new vector with the result, which is generally a vector with the same length but opposite direction. Negating a vector is the same as reversing the sign of each of its components.

Parameters

Return Value

The resulting 2-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec2negateInPlace(a)

Negates a 2-element vector in place, generally resulting in a vector with the same length but opposite direction. Negating a vector is the same as reversing the sign of each of its components.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec2normalize(vec)

Converts a 2-element vector to a unit vector; returns a new vector. When a vector is normalized, its direction remains the same but the distance from the origin to that vector becomes 1 (unless all its components are 0). A vector is normalized by dividing each of its components by its length.

Parameters

Return Value

The resulting vector. Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

Example

The following example changes the length of a line segment.

var startPt=[x1,y1]; // Line segment's start
var endPt=[x2,y2]; // Line segment's end
// Find difference between endPt and startPt
var delta=H3DU.Math.vec2sub(endPt,startPt);
// Normalize delta to a unit vector
var deltaNorm=H3DU.Math.vec2normalize(delta);
// Rescale to the desired length, here, 10
H3DU.Math.vec2scaleInPlace(deltaNorm,10);
// Find the new endpoint
endPt=H3DU.Math.vec2add(startPt,deltaNorm);

(static) H3DU.Math.vec2normalizeInPlace(vec)

Converts a 2-element vector to a unit vector. When a vector is normalized, its direction remains the same but the distance from the origin to that vector becomes 1 (unless all its components are 0). A vector is normalized by dividing each of its components by its length.

Parameters

Return Value

The parameter "vec". Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.vec2perp(vec)

Returns an arbitrary 2-element vector that is perpendicular (orthogonal) to the given 2-element vector. The return value will not be converted to a unit vector.

Parameters

Return Value

A perpendicular 2-element vector. Returns (0,0) if "vec" is (0,0). (Type: Array.<number>)

(static) H3DU.Math.vec2proj(vec, refVec)

Returns the projection of a 2-element vector on the given reference vector. Assuming both vectors start at the same point, the resulting vector will be parallel to the reference vector but will make the closest approach possible to the projected vector's endpoint. The difference between the projected vector and the return value will be perpendicular to the reference vector.

Parameters

Return Value

The projection of "vec" on "refVec". Returns (0,0,0) if "refVec"'s length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.vec2reflect(incident, normal)

Returns a vector that reflects off a surface.

Parameters

Return Value

A vector that has the same length as "incident" but is reflected away from the surface. (Type: Array.<number>)

(static) H3DU.Math.vec2scale(a, scalar)

Multiplies each element of a 2-element vector by a factor. Returns a new vector that is parallel to the old vector but with its length multiplied by the given factor. If the factor is positive, the vector will point in the same direction; if negative, in the opposite direction; if zero, the vector's components will all be 0.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec2scaleInPlace(a, scalar)

Multiplies each element of a 2-element vector by a factor, so that the vector is parallel to the old vector but its length is multiplied by the given factor. If the factor is positive, the vector will point in the same direction; if negative, in the opposite direction; if zero, the vector's components will all be 0.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec2sub(a, b)

Subtracts the second vector from the first vector and returns a new vector with the result. Subtracting two vectors is the same as subtracting each of their components.

Parameters

Return Value

The resulting 2-element vector. This is the vector to a from b. (Type: Array.<number>)

(static) H3DU.Math.vec2subInPlace(a, b)

Subtracts the second vector from the first vector and stores the result in the first vector. Subtracting two vectors is the same as subtracting each of their components.

Parameters

Return Value

The parameter "a". This is the vector to the previous a from b. (Type: Array.<number>)

(static) H3DU.Math.vec3abs(a)

Returns a new 3-element vector with the absolute value of each of its components.

Parameters

Return Value

The resulting 3-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec3absInPlace(a)

Sets each component of the given 3-element vector to its absolute value.

Parameters

Return Value

The vector "a". (Type: Array.<number>)

(static) H3DU.Math.vec3add(a, b)

Adds two 3-element vectors and returns a new vector with the result. Adding two vectors is the same as adding each of their components. The resulting vector:

Parameters

Return Value

The resulting 3-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec3addInPlace(a, b)

Adds two 3-element vectors and stores the result in the first vector. Adding two vectors is the same as adding each of their components. The resulting vector:

Parameters

Return Value

The parameter "a" (Type: Array.<number>)

(static) H3DU.Math.vec3assign(dst, src)

Assigns the values of a 3-element vector into another 3-element vector.

Parameters

Return Value

The parameter "dst" (Type: Array.<number>)

(static) H3DU.Math.vec3clamp(a, min, max)

Returns a 3-element vector in which each element of the given 3-element vector is clamped so it's not less than one value or greater than another value.

Parameters

Return Value

The resulting vector. (Type: Array.<number>)

(static) H3DU.Math.vec3clampInPlace(a, min, max)

Clamps each element of the given 3-element vector so it's not less than one value or greater than another value.

Parameters

Return Value

The resulting vector. (Type: Array.<number>)

(static) H3DU.Math.vec3copy(vec)

Returns a copy of a 3-element vector.

Parameters

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.vec3cross(a, b)

Finds the cross product of two 3-element vectors (called A and B). The following are properties of the cross product:

The cross product (c) of vectors a and b is found as follows:
c.x = a.y * b.z - a.z * b.y
c.y = a.z * b.x - a.x * b.z
c.z = a.x * b.y - a.y * b.x

Parameters

Return Value

A 3-element vector containing the cross product. (Type: Array.<number>)

Example

The following example uses the cross product to calculate a triangle's normal vector and its area.

var a=triangle[0];
var b=triangle[1];
var c=triangle[2];
// Find vector from C to A
var da=H3DU.Math.vec3sub(a,c);
// Find vector from C to B
var db=H3DU.Math.vec3sub(b,c);
// The triangle's normal is the cross product of da and db
var normal=H3DU.Math.vec3cross(da,db);
// Find the triangle's area
var area=H3DU.Math.vec3length(normal)*0.5;

The following example finds the cosine and sine of the angle between two unit vectors and the orthogonal unit vector of both.

var cr=H3DU.Math.vec3cross(unitA,unitB);
// Cosine of the angle. Will be positive or negative depending on
// the shortest angle between the vectors.
var cosine=H3DU.Math.vec3dot(unitA,unitB);
// Sine of the angle. Note that the sine will always be 0 or greater because
// the shortest angle betw0] ? cr : H3DU.Math.vec3scale(cr,1.0/sine);

(static) H3DU.Math.vec3dist(vecFrom, vecTo)

Finds the straight-line distance from one three-element vector to another, treating both as 3D points.

Parameters

Return Value

The distance between the two vectors. (Type: number)

(static) H3DU.Math.vec3dot(a, b)

Finds the dot product of two 3-element vectors. It's the sum of the products of their components (for example, a's X times b's X).

The following are properties of the dot product:

Parameters

Return Value

A number representing the dot product. (Type: number)

Example

The following shows a fast way to compare a vector's length using the dot product.

// Check if the vector's length squared is less than 20 units squared
if(H3DU.Math.vec3dot(vector, vector)<20*20) {
// The vector's length is shorter than 20 units
}

(static) H3DU.Math.vec3fromWindowPoint(vector, matrix, viewport, [yUp])

Unprojects the window coordinates given in a 3-element vector, using the given transformation matrix and viewport rectangle.

In the window coordinate space, X coordinates increase rightward and Y coordinates increase upward or downward depending on the "yUp" parameter, and Z coordinates within the view volume range from 0 to 1 and increase from front to back.

Parameters

Return Value

A 3-element array giving the coordinates of the unprojected point, in that order. (Type: Array.<number>)

(static) H3DU.Math.vec3length(a)

Returns the distance of this 3-element vector from the origin, also known as its length or magnitude. It's the same as the square root of the sum of the squares of its components.

Note that if vectors are merely sorted or compared by their lengths (and those lengths are not added or multiplied together or the like), it's faster to sort or compare them by the squares of their lengths (to find the square of a 3-element vector's length, call H3DU.Math.vec3dot passing the same vector as both of its arguments).

Parameters

Return Value

Return value. (Type: number)

(static) H3DU.Math.vec3lerp(v1, v2, factor)

Does a linear interpolation between two 3-element vectors; returns a new vector.

Parameters

Return Value

The interpolated vector. (Type: Array.<number>)

Example

The following code does a nonlinear interpolation of two vectors that uses the cube of "factor" rather than "factor". Rather than at a constant speed, the vectors are interpolated slowly then very fast.

factor = factor*factor*factor; // cube the interpolation factor
var newVector = H3DU.Math.vec3lerp(vector1, vector2, factor);

The following code does an inverted cubic interpolation. This time, vectors are interpolated fast then very slowly.

factor = 1 - factor; // Invert the factor
factor = factor*factor*factor; // cube the interpolation factor
factor = 1 - factor; // Invert the result
var newVector = H3DU.Math.vec3lerp(vector1, vector2, factor);

The following code does the nonlinear interpolation called "smoothstep". It slows down at the beginning and end, and speeds up in the middle.

factor = (3.0-2.0*factor)*factor*factor; // smoothstep interpolation
var newVector = H3DU.Math.vec3lerp(vector1, vector2, factor);

(static) H3DU.Math.vec3mul(a, b)

Multiplies each of the components of two 3-element vectors and returns a new vector with the result.

Parameters

Return Value

The resulting 3-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec3mulInPlace(a, b)

Multiplies each of the components of two 3-element vectors and stores the result in the first vector.

Parameters

Return Value

The parameter "a" (Type: Array.<number>)

(static) H3DU.Math.vec3negate(a)

Negates a 3-element vector and returns a new vector with the result, which is generally a vector with the same length but opposite direction. Negating a vector is the same as reversing the sign of each of its components.

Parameters

Return Value

The resulting 3-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec3negateInPlace(a)

Negates a 3-element vector in place, generally resulting in a vector with the same length but opposite direction. Negating a vector is the same as reversing the sign of each of its components.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec3norm(vec)

Deprecated: Use H3DU.Math.vec3normalize instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.vec3normalize.

Parameters

Return Value

The normalized vector. (Type: Array.<number>)

(static) H3DU.Math.vec3normInPlace(vec)

Deprecated: Use H3DU.Math.vec3normalizeInPlace instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.vec3normalizeInPlace.

Parameters

Return Value

The parameter "vec" (Type: Array.<number>)

(static) H3DU.Math.vec3normalize(vec)

Converts a 3-element vector to a unit vector; returns a new vector. When a vector is normalized, its direction remains the same but the distance from the origin to that vector becomes 1 (unless all its components are 0). A vector is normalized by dividing each of its components by its length.

Parameters

Return Value

The resulting vector. Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

Example

The following example changes the length of a line segment.

var startPt=[x1,y1,z1]; // Line segment's start
var endPt=[x2,y2,z2]; // Line segment's end
// Find difference between endPt and startPt
var delta=H3DU.Math.vec3sub(endPt,startPt);
// Normalize delta to a unit vector
var deltaNorm=H3DU.Math.vec3normalize(delta);
// Rescale to the desired length, here, 10
H3DU.Math.vec3scaleInPlace(deltaNorm,10);
// Find the new endpoint
endPt=H3DU.Math.vec3add(startPt,deltaNorm);

(static) H3DU.Math.vec3normalizeInPlace(vec)

Converts a 3-element vector to a unit vector. When a vector is normalized, its direction remains the same but the distance from the origin to that vector becomes 1 (unless all its components are 0). A vector is normalized by dividing each of its components by its length.

Parameters

Return Value

The parameter "vec". Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.vec3perp(vec)

Returns an arbitrary 3-element vector that is perpendicular (orthogonal) to the given 3-element vector. The return value will not be converted to a unit vector.

Parameters

Return Value

A perpendicular 3-element vector. Returns (0,0,0) if "vec" is (0,0,0). (Type: Array.<number>)

(static) H3DU.Math.vec3proj(vec, refVec)

Returns the projection of a 3-element vector on the given reference vector. Assuming both vectors start at the same point, the resulting vector will be parallel to the reference vector but will make the closest approach possible to the projected vector's endpoint. The difference between the projected vector and the return value will be perpendicular to the reference vector.

Parameters

Return Value

The projection of "vec" on "refVec". Returns (0,0,0) if "refVec"'s length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.vec3reflect(incident, normal)

Returns a vector that reflects off a surface.

Parameters

Return Value

A vector that has the same length as "incident" but is reflected away from the surface. (Type: Array.<number>)

(static) H3DU.Math.vec3scale(a, scalar)

Multiplies each element of a 3-element vector by a factor. Returns a new vector that is parallel to the old vector but with its length multiplied by the given factor. If the factor is positive, the vector will point in the same direction; if negative, in the opposite direction; if zero, the vector's components will all be 0.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec3scaleInPlace(a, scalar)

Multiplies each element of a 3-element vector by a factor, so that the vector is parallel to the old vector but its length is multiplied by the given factor. If the factor is positive, the vector will point in the same direction; if negative, in the opposite direction; if zero, the vector's components will all be 0.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec3sub(a, b)

Subtracts the second vector from the first vector and returns a new vector with the result. Subtracting two vectors is the same as subtracting each of their components.

Parameters

Return Value

The resulting 3-element vector. This is the vector to a from b. (Type: Array.<number>)

(static) H3DU.Math.vec3subInPlace(a, b)

Subtracts the second vector from the first vector and stores the result in the first vector. Subtracting two vectors is the same as subtracting each of their components.

Parameters

Return Value

The parameter "a". This is the vector to the previous a from b. (Type: Array.<number>)

(static) H3DU.Math.vec3toWindowPoint(vector, matrix, viewport, [yUp])

Transforms the 3D point specified in this 3-element vector to its window coordinates using the given transformation matrix and viewport rectangle.

Parameters

Return Value

A 3-element array giving the window coordinates, in that order. (Type: Array.<number>)

(static) H3DU.Math.vec3triple(a, b, c)

Finds the scalar triple product of three vectors (A, B, and C). The triple product is the dot product of both A and the cross product of B and C. The following are properties of the scalar triple product (called triple product in what follows):

Parameters

Return Value

A number giving the triple product. (Type: number)

(static) H3DU.Math.vec4abs(a)

Returns a new 4-element vector with the absolute value of each of its components.

Parameters

Return Value

The resulting 4-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec4absInPlace(a)

Sets each component of the given 4-element vector to its absolute value.

Parameters

Return Value

The vector "a". (Type: Array.<number>)

(static) H3DU.Math.vec4add(a, b)

Adds two 4-element vectors and returns a new vector with the result. Adding two vectors is the same as adding each of their components. The resulting vector:

Parameters

Return Value

The resulting 4-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec4addInPlace(a, b)

Adds two 4-element vectors and stores the result in the first vector. Adding two vectors is the same as adding each of their components. The resulting vector:

Parameters

Return Value

The parameter "a". This is the vector to the previous a from b. (Type: Array.<number>)

(static) H3DU.Math.vec4assign(dst, src)

Assigns the values of a 4-element vector into another 4-element vector.

Parameters

Return Value

The parameter "dst". (Type: Array.<number>)

(static) H3DU.Math.vec4clamp(a, min, max)

Returns a 4-element vector in which each element of the given 4-element vector is clamped

Parameters

Return Value

The resulting vector. (Type: Array.<number>)

(static) H3DU.Math.vec4clampInPlace(a, min, max)

Clamps each element of the given 4-element vector so it's not less than one value or greater than another value.

Parameters

Return Value

The resulting vector. (Type: Array.<number>)

(static) H3DU.Math.vec4copy(vec)

Returns a copy of a 4-element vector.

Parameters

Return Value

Return value. (Type: Array.<number>)

(static) H3DU.Math.vec4dot(a, b)

Finds the dot product of two 4-element vectors. It's the sum of the products of their components (for example, a's X times b's X). For properties of the dot product, see H3DU.Math.vec3dot.

Parameters

Return Value

Return value. (Type: number)

(static) H3DU.Math.vec4length(a)

Returns the distance of this 4-element vector from the origin, also known as its length or magnitude. It's the same as the square root of the sum of the squares of its components.

Note that if vectors are merely sorted or compared by their lengths, it's faster to sort or compare them by the squares of their lengths (to find the square of a 4-element vector's length, call H3DU.Math.vec4dot passing the same vector as both of its arguments).

Parameters

Return Value

Return value. (Type: number)

(static) H3DU.Math.vec4lerp(v1, v2, factor)

Does a linear interpolation between two 4-element vectors; returns a new vector.

Parameters

Return Value

The interpolated vector. (Type: Array.<number>)

(static) H3DU.Math.vec4negate(a)

Negates a 4-element vector and returns a new vector with the result, which is generally a vector with the same length but opposite direction. Negating a vector is the same as reversing the sign of each of its components.

Parameters

Return Value

The resulting 4-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec4negateInPlace(a)

Negates a 4-element vector in place, generally resulting in a vector with the same length but opposite direction. Negating a vector is the same as reversing the sign of each of its components.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec4norm(vec)

Deprecated: Use H3DU.Math.vec4normalize instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.vec4normalize.

Parameters

Return Value

The normalized vector. (Type: Array.<number>)

(static) H3DU.Math.vec4normInPlace(vec)

Deprecated: Use H3DU.Math.vec4normalizeInPlace instead. The name of this method may be confused with a vector's "norm", another name for its length.

Deprecated alias for H3DU.Math.vec4normalizeInPlace.

Parameters

Return Value

The parameter "vec" (Type: Array.<number>)

(static) H3DU.Math.vec4normalize(vec)

Converts a 4-element vector to a unit vector; returns a new vector. When a vector is normalized, its direction remains the same but the distance from the origin to that vector becomes 1 (unless all its components are 0). A vector is normalized by dividing each of its components by its length.

Parameters

Return Value

The resulting vector. Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.vec4normalizeInPlace(vec)

Converts a 4-element vector to a unit vector. When a vector is normalized, its direction remains the same but the distance from the origin to that vector becomes 1 (unless all its components are 0). A vector is normalized by dividing each of its components by its length.

Parameters

Return Value

The parameter "vec". Note that due to rounding error, the vector's length might not be exactly equal to 1, and that the vector will remain unchanged if its length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.vec4proj(vec, refVec)

Returns the projection of a 4-element vector on the given reference vector. Assuming both vectors start at the same point, the resulting vector will be parallel to the reference vector but will make the closest approach possible to the projected vector's endpoint. The difference between the projected vector and the return value will be perpendicular to the reference vector.

Parameters

Return Value

The projection of "vec" on "refVec". Returns (0,0,0,0) if "refVec"'s length is 0 or extremely close to 0. (Type: Array.<number>)

(static) H3DU.Math.vec4scale(a, scalar)

Multiplies each element of a 4-element vector by a factor, returning a new vector that is parallel to the old vector but with its length multiplied by the given factor. If the factor is positive, the vector will point in the same direction; if negative, in the opposite direction; if zero, the vector's components will all be 0.

Parameters

Return Value

The resulting 4-element vector. (Type: Array.<number>)

(static) H3DU.Math.vec4scaleInPlace(a, scalar)

Multiplies each element of a 4-element vector by a factor, so that the vector is parallel to the old vector but its length is multiplied by the given factor. If the factor is positive, the vector will point in the same direction; if negative, in the opposite direction; if zero, the vector's components will all be 0.

Parameters

Return Value

The parameter "a". (Type: Array.<number>)

(static) H3DU.Math.vec4sub(a, b)

Subtracts the second vector from the first vector and returns a new vector with the result. Subtracting two vectors is the same as subtracting each of their components.

Parameters

Return Value

The resulting 4-element vector. This is the vector to a from b. (Type: Array.<number>)

(static) H3DU.Math.vec4subInPlace(a, b)

Subtracts the second vector from the first vector and stores the result in the first vector. Subtracting two vectors is the same as subtracting each of their components.

Parameters

Return Value

The parameter "a" (Type: Array.<number>)

Back to documentation index.