H3DU.MathUtil
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
- GlobalPitchRollYaw
Indicates that a vector’s rotation occurs as a pitch, then roll, then yaw (each rotation around the original axes). - GlobalPitchYawRoll
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 - GlobalRollPitchYaw
Indicates that a vector’s rotation occurs as a roll, then pitch, then yaw (each rotation around the original axes). - GlobalRollYawPitch
Indicates that a vector’s rotation occurs as a roll, then yaw, then pitch (each rotation around the original axes). - GlobalYawPitchRoll
Indicates that a vector’s rotation occurs as a yaw, then pitch, then roll (each rotation around the original axes). - GlobalYawRollPitch
Indicates that a vector’s rotation occurs as a yaw, then roll, then pitch (each rotation around the original axes). - HalfPi
Closest approximation to pi divided by 2, or a 90-degree turn in radians. - LocalPitchRollYaw
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. - LocalPitchYawRoll
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. - LocalRollPitchYaw
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. - LocalRollYawPitch
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. - LocalYawPitchRoll
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. - LocalYawRollPitch
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. - Num180DividedByPi
Closest approximation to 180 divided by pi, or the number of degrees in a radian. - PiDividedBy180
Closest approximation to pi divided by 180, or the number of radians in a degree. - PiTimes2
Closest approximation to pi times 2, or a 360-degree turn in radians. - ToDegrees
Closest approximation to 180 divided by pi, or the number of degrees in a radian. - ToRadians
Closest approximation to pi divided by 180, or the number of radians in a degree.
Methods
- boxCenter
Finds the center of a 3D bounding box. - boxDimensions
Finds the dimensions of a 3D bounding box. - boxIsEmpty
Determines whether a 3D bounding box is empty. - colorToLinear
Converts a color from encoded sRGB to linear sRGB using the sRGB transfer function, and returns a new vector with the result. - colorTosRGB
Converts a color from linear sRGB to encoded sRGB using the sRGB transfer function, and returns a new vector with the result. - frustumHasBox
Determines whether an axis-aligned bounding box is at least partially inside a view frustum. - frustumHasPoint
Determines whether a point is outside or inside a view frustum. - frustumHasSphere
Determines whether a sphere is at least partially inside a view frustum. - interpCubicBezier
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. - mat3copy
Returns a copy of a 3x3 matrix. - mat3identity
Returns the identity 3x3 matrix (a matrix that keeps vectors unchanged when they are transformed with this matrix). - mat3invert
Finds the inverse of a 3x3 matrix, describing a transformation that undoes the given transformation. - mat3multiply
Multiplies two 3x3 matrices. - mat3transform
Transforms a 3-element vector with a 3x3 matrix and returns the transformed vector. - mat3transpose
Returns the transpose of a 3x3 matrix. - mat3transposeInPlace
Transposes a 3x3 matrix in place without creating a new matrix. - mat4copy
Returns a copy of a 4x4 matrix. - mat4frustum
Returns a 4x4 matrix representing a perspective projection in the form of a view frustum, or the limits in the “camera”’s view. - mat4identity
Returns the identity 4x4 matrix (a matrix that keeps vectors unchanged when they are transformed with this matrix). - mat4inverseTranspose3
Returns the transposed result of the inverted 3x3 upper left corner of the given 4x4 matrix. - mat4invert
Finds the inverse of a 4x4 matrix, describing a transformation that undoes the given transformation. - mat4isIdentity
Returns whether a 4x4 matrix is the identity matrix. - mat4lookat
Returns a 4x4 matrix that represents a camera view, transforming world space coordinates, shared by every object in a scene, to coordinates in eye space (also called camera space or view space). - mat4multiply
Multiplies two 4x4 matrices. - mat4oblique
Returns a 4x4 view matrix representing an oblique projection, when used in conjunction with an orthographic projection. - mat4ortho
Returns a 4x4 matrix representing an orthographic projection. - mat4ortho2d
Returns a 4x4 matrix representing a 2D orthographic projection. - mat4ortho2dAspect
Returns a 4x4 matrix representing a 2D orthographic projection, retaining the view rectangle’s aspect ratio. - mat4orthoAspect
Returns a 4x4 matrix representing an orthographic projection, retaining the view rectangle’s aspect ratio. - mat4perspective
Returns a 4x4 matrix representing a perspective projection. - mat4perspectiveHorizontal
Returns a 4x4 matrix representing a perspective projection, given an X axis field of view. - mat4projectVec3
Transforms a 3-element vector with a 4x4 matrix and returns a perspective-correct version of the vector as a 3D point. - mat4rotate
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. - mat4rotated
Returns a 4x4 matrix representing a rotation transformation that rotates vectors by the given rotation angle and around the given axis of rotation. - mat4scale
Multiplies a 4x4 matrix by a scaling transformation. - mat4scaleInPlace
Modifies a 4x4 matrix by multiplying it by a scaling transformation. - mat4scaled
Returns a 4x4 matrix representing a scaling transformation. - mat4toFrustumPlanes
Finds the six clipping planes of a view frustum defined by a 4x4 matrix. - mat4toMat3
Returns the upper-left part of a 4x4 matrix as a new 3x3 matrix. - mat4transform
Transforms a 4-element vector with a 4x4 matrix and returns the transformed vector. - mat4transformVec3
Transforms a 3-element vector with a 4x4 matrix as though it were an affine transformation matrix (without perspective) and returns the transformed vector. - mat4translate
Multiplies a 4x4 matrix by a translation transformation. - mat4translated
Returns a 4x4 matrix representing a translation. - mat4transpose
Returns the transpose of a 4x4 matrix. - mat4transposeInPlace
Transposes a 4x4 matrix in place without creating a new matrix. - planeFromNormalAndPoint
Creates a plane from a normal vector and a point on the plane. - planeNormalize
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. - planeNormalizeInPlace
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. - quatConjugate
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). - quatCopy
Returns a copy of a quaternion. - quatDot
Finds the dot product of two quaternions. - quatFromAxisAngle
Generates a quaternion from a rotation transformation that rotates vectors by the given rotation angle and around the given axis of rotation, - quatFromMat4
Generates a quaternion from the vector rotation described in a 4x4 matrix. - quatFromTaitBryan
Generates a quaternion from pitch, yaw and roll angles (or Tait–Bryan angles). - quatFromVectors
Generates a quaternion describing a rotation between two 3-element vectors. - quatIdentity
Returns the identity quaternion of multiplication, (0, 0, 0, 1). - quatInvert
Returns a quaternion that describes a rotation that undoes the given rotation (an “inverted” rotation) and is converted to a unit vector. - quatIsIdentity
Returns whether this quaternion is the identity quaternion, (0, 0, 0, 1). - quatLength
Returns the distance of this quaternion from the origin. - quatMultiply
Multiplies two quaternions, creating a composite rotation. - quatNlerp
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. - quatNormalize
Converts a quaternion to a unit vector; returns a new quaternion. - quatNormalizeInPlace
Converts a quaternion to a unit vector. - quatRotate
Multiplies a quaternion by a rotation transformation that rotates vectors by the given rotation angle and around the given axis of rotation. - quatScale
Multiplies each element of a quaternion by a factor and returns the result as a new quaternion. - quatScaleInPlace
Multiplies each element of a quaternion by a factor and stores the result in that quaternion. - quatSlerp
Returns a quaternion that lies along the shortest path between the given two quaternion rotations, using a spherical interpolation function. - quatToAxisAngle
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. - quatToMat4
Generates a 4x4 matrix describing the rotation described by this quaternion. - quatToTaitBryan
Converts this quaternion to the same version of the rotation in the form of pitch, yaw, and roll angles (or Tait–Bryan angles). - quatTransform
Transforms a 3- or 4-element vector using a quaternion’s vector rotation. - vec2abs
Returns a new 2-element vector with the absolute value of each of its components. - vec2absInPlace
Sets each component of the given 2-element vector to its absolute value. - vec2add
Adds two 2-element vectors and returns a new vector with the result. - vec2addInPlace
Adds two 2-element vectors and stores the result in the first vector. - vec2assign
Assigns the values of a 2-element vector into another 2-element vector. - vec2clamp
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. - vec2clampInPlace
Clamps each element of the given 2-element vector so it’s not less than one value or greater than another value. - vec2copy
Returns a copy of a 2-element vector. - vec2dist
Finds the straight-line distance from one three-element vector to another, treating both as 3D points. - vec2dot
Finds the dot product of two 2-element vectors. - vec2length
Returns the distance of this 2-element vector from the origin, also known as its length or magnitude. - vec2lerp
Does a linear interpolation between two 2-element vectors; returns a new vector. - vec2mul
Multiplies each of the components of two 2-element vectors and returns a new vector with the result. - vec2mulInPlace
Multiplies each of the components of two 2-element vectors and stores the result in the first vector. - vec2negate
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. - vec2negateInPlace
Negates a 2-element vector in place, generally resulting in a vector with the same length but opposite direction. - vec2normalize
Converts a 2-element vector to a unit vector; returns a new vector. - vec2normalizeInPlace
Converts a 2-element vector to a unit vector. - vec2perp
Returns an arbitrary 2-element vector that is perpendicular (orthogonal) to the given 2-element vector. - vec2proj
Returns the projection of a 2-element vector on the given reference vector. - vec2reflect
Returns a vector that reflects off a surface. - vec2scale
Multiplies each element of a 2-element vector by a factor. - vec2scaleInPlace
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. - vec2sub
Subtracts the second vector from the first vector and returns a new vector with the result. - vec2subInPlace
Subtracts the second vector from the first vector and stores the result in the first vector. - vec3abs
Returns a new 3-element vector with the absolute value of each of its components. - vec3absInPlace
Sets each component of the given 3-element vector to its absolute value. - vec3add
Adds two 3-element vectors and returns a new vector with the result. - vec3addInPlace
Adds two 3-element vectors and stores the result in the first vector. - vec3assign
Assigns the values of a 3-element vector into another 3-element vector. - vec3clamp
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. - vec3clampInPlace
Clamps each element of the given 3-element vector so it’s not less than one value or greater than another value. - vec3copy
Returns a copy of a 3-element vector. - vec3cross
Finds the cross product of two 3-element vectors (called A and B). - vec3dist
Finds the straight-line distance from one three-element vector to another, treating both as 3D points. - vec3dot
Finds the dot product of two 3-element vectors. - vec3fromWindowPoint
Unprojects the window coordinates given in a 3-element vector, using the given transformation matrix and viewport rectangle. - vec3length
Returns the distance of this 3-element vector from the origin, also known as its length or magnitude. - vec3lerp
Does a linear interpolation between two 3-element vectors; returns a new vector. - vec3mul
Multiplies each of the components of two 3-element vectors and returns a new vector with the result. - vec3mulInPlace
Multiplies each of the components of two 3-element vectors and stores the result in the first vector. - vec3negate
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. - vec3negateInPlace
Negates a 3-element vector in place, generally resulting in a vector with the same length but opposite direction. - vec3normalize
Converts a 3-element vector to a unit vector; returns a new vector. - vec3normalizeInPlace
Converts a 3-element vector to a unit vector. - vec3perp
Returns an arbitrary 3-element vector that is perpendicular (orthogonal) to the given 3-element vector. - vec3proj
Returns the projection of a 3-element vector on the given reference vector. - vec3reflect
Returns a vector that reflects off a surface. - vec3scale
Multiplies each element of a 3-element vector by a factor. - vec3scaleInPlace
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. - vec3sub
Subtracts the second vector from the first vector and returns a new vector with the result. - vec3subInPlace
Subtracts the second vector from the first vector and stores the result in the first vector. - vec3toWindowPoint
Transforms the 3D point specified in this 3-element vector to its window coordinates using the given transformation matrix and viewport rectangle. - vec3triple
Finds the scalar triple product of three vectors (A, B, and C). - vec4abs
Returns a new 4-element vector with the absolute value of each of its components. - vec4absInPlace
Sets each component of the given 4-element vector to its absolute value. - vec4add
Adds two 4-element vectors and returns a new vector with the result. - vec4addInPlace
Adds two 4-element vectors and stores the result in the first vector. - vec4assign
Assigns the values of a 4-element vector into another 4-element vector. - vec4clamp
Returns a 4-element vector in which each element of the given 4-element vector is clamped - vec4clampInPlace
Clamps each element of the given 4-element vector so it’s not less than one value or greater than another value. - vec4copy
Returns a copy of a 4-element vector. - vec4dot
Finds the dot product of two 4-element vectors. - vec4length
Returns the distance of this 4-element vector from the origin, also known as its length or magnitude. - vec4lerp
Does a linear interpolation between two 4-element vectors; returns a new vector. - vec4negate
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. - vec4negateInPlace
Negates a 4-element vector in place, generally resulting in a vector with the same length but opposite direction. - vec4normalize
Converts a 4-element vector to a unit vector; returns a new vector. - vec4normalizeInPlace
Converts a 4-element vector to a unit vector. - vec4proj
Returns the projection of a 4-element vector on the given reference vector. - vec4scale
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. - vec4scaleInPlace
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. - vec4sub
Subtracts the second vector from the first vector and returns a new vector with the result. - vec4subInPlace
Subtracts the second vector from the first vector and stores the result in the first vector.
### H3DU.MathUtil.GlobalPitchRollYaw (constant)
Indicates that a vector’s rotation occurs as a pitch, then roll, then yaw (each rotation around the original axes).
### H3DU.MathUtil.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.MathUtil.GlobalRollPitchYaw (constant)
Indicates that a vector’s rotation occurs as a roll, then pitch, then yaw (each rotation around the original axes).
### H3DU.MathUtil.GlobalRollYawPitch (constant)
Indicates that a vector’s rotation occurs as a roll, then yaw, then pitch (each rotation around the original axes).
### H3DU.MathUtil.GlobalYawPitchRoll (constant)
Indicates that a vector’s rotation occurs as a yaw, then pitch, then roll (each rotation around the original axes).
### H3DU.MathUtil.GlobalYawRollPitch (constant)
Indicates that a vector’s rotation occurs as a yaw, then roll, then pitch (each rotation around the original axes).
### H3DU.MathUtil.HalfPi (constant)
Closest approximation to pi divided by 2, or a 90-degree turn in radians.
Default Value: 1.5707963267948966
### H3DU.MathUtil.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.MathUtil.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.MathUtil.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.MathUtil.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.MathUtil.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.MathUtil.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.MathUtil.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.MathUtil.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.MathUtil.PiTimes2 (constant)
Closest approximation to pi times 2, or a 360-degree turn in radians.
Default Value: 6.283185307179586
### H3DU.MathUtil.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.MathUtil.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.
### (static) H3DU.MathUtil.boxCenter(box)
Finds the center of a 3D bounding box.
Parameters
box(Type: Array.<number>)
An axis-aligned bounding box, which is an array of six values. The first three values are the smallest X, Y, and Z coordinates, and the last three values are the largest X, Y, and Z coordinates.
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.MathUtil.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
box(Type: Array.<number>)
An axis-aligned bounding box, which is an array of six values. The first three values are the smallest X, Y, and Z coordinates, and the last three values are the largest X, Y, and Z coordinates.
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.MathUtil.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
box(Type: Array.<number>)
An axis-aligned bounding box, which is an array of six values. The first three values are the smallest X, Y, and Z coordinates, and the last three values are the largest X, Y, and Z coordinates.
Return Value
true if at least one
of the minimum coordinates is greater than its
corresponding maximum coordinate; otherwise, false. (Type: boolean)
### (static) H3DU.MathUtil.colorToLinear(srgb)
Converts a color from encoded sRGB to linear sRGB using the sRGB transfer function, and returns a new vector with the result.
Linear RGB is linear because of its linear relationship of light emitted by a surface of the given color.
Parameters
srgb(Type: Array.<number>)
A three- or four-element vector giving the red, green, and blue components, in that order, of an sRGB color. The alpha component is either the fourth element in the case of a four-element vector, or 1.0 in the case of a three-element vector. Each element in the vector ranges from 0 through 1.
Return Value
A three-element vector giving the red, green, and blue components, in that order, of the given color in linear sRGB. The alpha component will be as specified in the “srgb” parameter. (Type: Array.<number>)
### (static) H3DU.MathUtil.colorTosRGB(lin)
Converts a color from linear sRGB to encoded sRGB using the sRGB transfer function, and returns a new vector with the result.
Linear RGB is linear because of its linear relationship of light emitted by a surface of the given color.
Parameters
lin(Type: Array.<number>)
A three- or four-element vector giving the red, green, and blue components, in that order, of a linear RGB color. The alpha component is either the fourth element in the case of a four-element vector, or 1.0 in the case of a three-element vector. Each element in the vector ranges from 0 through 1.
Return Value
lin A four-element vector giving the red, green, blue, and alpha components, in that order, of the given color in encoded sRGB. The alpha component will be as specified in the “lin” parameter. (Type: Array.<number>)
### (static) H3DU.MathUtil.frustumHasBox(frustum, box)
Determines whether an axis-aligned bounding box is at least partially inside a view frustum.
Parameters
frustum(Type: Array.<Array.<number»)
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.box(Type: Array.<number>)
An axis-aligned bounding box in world space, which is an array of six values. The first three values are the smallest X, Y, and Z coordinates, and the last three values are the largest X, Y, and Z coordinates.
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.MathUtil.frustumHasPoint(frustum, x, y, z)
Determines whether a point is outside or inside a view frustum.
Parameters
frustum(Type: Array.<Array.<number»)
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.x(Type: number)
X coordinate of a point in world space.y(Type: number)
Y coordinate of a point in world space.z(Type: number)
Z coordinate of a point in world space.
Return Value
true if the point is inside; otherwise false; (Type: boolean)
### (static) H3DU.MathUtil.frustumHasSphere(frustum, x, y, z, radius)
Determines whether a sphere is at least partially inside a view frustum.
Parameters
frustum(Type: Array.<Array.<number»)
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.x(Type: number)
X coordinate of the sphere’s center in world space.y(Type: number)
Y coordinate of the sphere’s center in world space.z(Type: number)
Z coordinate of the sphere’s center in world space.radius(Type: number)
Radius of the sphere in world-space units.
Return Value
true if the sphere
is partially or totally
inside the frustum; false otherwise. (Type: boolean)
### (static) H3DU.MathUtil.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.
Parameters
a(Type: number)
X coordinate of the first configurable control point of the curve. Should be within the range 0 through 1.b(Type: number)
Y coordinate of the first configurable control point of the curve. Should be within the range 0 through 1, but may exceed this range.c(Type: number)
X coordinate of the second configurable control point of the curve. Should be within the range 0 through 1.d(Type: number)
Y coordinate of the second configurable control point of the curve. Should be within the range 0 through 1, but may exceed this range.t(Type: number)
Number ranging from 0 through 1 that indicates time.
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.MathUtil.mat3copy(mat)
Returns a copy of a 3x3 matrix.
Parameters
mat(Type: Array.<number>)
A 3x3atrix.
Return Value
Return value. (Type: Array.<number>)
### (static) H3DU.MathUtil.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.MathUtil.mat3invert(m)
Finds the inverse of a 3x3 matrix, describing a transformation that undoes the given transformation.
Parameters
m(Type: Array.<number>)
A 3x3 matrix.
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.MathUtil.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
a(Type: Array.<number>)
The first matrix.b(Type: Array.<number>)
The second matrix.
Return Value
The resulting 3x3 matrix. (Type: Array.<number>)
### (static) H3DU.MathUtil.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
mat(Type: Array.<number>)
A 3x3 matrix.-
v(Type: Array.<number>number)
X coordinate. If “vy”, and “vz” are omitted, this value can instead be a 4-element array giving the X, Y, and Z coordinates. vy(Type: number) (optional)
Y coordinate.vz(Type: number) (optional)
Z coordinate. To transform a 2D point, set Z to 1, and divide the result’s X and Y by the result’s Z.
Return Value
The transformed vector. (Type: Array.<number>)
### (static) H3DU.MathUtil.mat3transpose(m3)
Returns the transpose of a 3x3 matrix. (A transpose is a matrix whose rows are converted to columns and vice versa.)
Parameters
m3(Type: Array.<number>)
A 3x3 matrix.
Return Value
The resulting 3x3 matrix. (Type: Array.<number>)
### (static) H3DU.MathUtil.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
mat(Type: Array.<number>)
A 3x3 matrix.
Return Value
The parameter “mat”. (Type: Array.<number>)
### (static) H3DU.MathUtil.mat4copy(mat)
Returns a copy of a 4x4 matrix.
Parameters
mat(Type: Array.<number>)
A 4x4 matrix.
Return Value
Return value. (Type: Array.<number>)
### (static) H3DU.MathUtil.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
l(Type: number)
X coordinate of the point in eye space where the left clipping plane meets the near clipping plane.r(Type: number)
X coordinate of the point in eye space where the right clipping plane meets the near clipping plane. (“l” is usually less than “r”, so that X coordinates increase from left to right. If “l” is greater than “r”, X coordinates increase in the opposite direction.)b(Type: number)
Y coordinate of the point in eye space where the bottom clipping plane meets the near clipping plane.t(Type: number)
Y coordinate of the point in eye space where the top clipping plane meets the near clipping plane. (“b” is usually less than “t”, so that Y coordinates increase upward, as they do in WebGL when just this matrix is used to transform vertices. If “b” is greater than “t”, Y coordinates increase in the opposite direction.)near(Type: number)
The distance, in eye space, from the “camera” to the near clipping plane. Objects closer than this distance won’t be seen.
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.
* far (Type: number)
The distance, in eye space, from the “camera” to the far clipping plane. Objects farther than this distance won’t be seen.
This value should be greater than 0 and should be set so that the absolute ratio of “far” to “near” is as small as the application can accept. (“near” is usually less than “far”, so that Z coordinates increase from near to far in the direction from the back to the front of the “eye”, as they do in WebGL when just this matrix is used to transform vertices. If “near” is greater than “far”, Z coordinates increase in the opposite direction.)
In the usual case that “far” is greater than “near”, depth buffer values will be more concentrated around the near plane than around the far plane due to the perspective projection. The greater the ratio of “far” to “near”, the more concentrated the values will be around the near plane, and the more likely two objects close to the far plane will have identical depth values. (Most WebGL implementations support 24-bit depth buffers, meaning they support 16,777,216 possible values per pixel.)
Return Value
The resulting 4x4 matrix. (Type: Array.<number>)
### (static) H3DU.MathUtil.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.MathUtil.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
m4(Type: Array.<number>)
A 4x4 matrix.
Return Value
The resulting 3x3 matrix. If the matrix can’t be inverted, returns the identity 3x3 matrix. (Type: Array.<number>)
### (static) H3DU.MathUtil.mat4invert(m)
Finds the inverse of a 4x4 matrix, describing a transformation that undoes the given transformation.
Parameters
m(Type: Array.<number>)
A 4x4 matrix.
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.MathUtil.mat4isIdentity(mat)
Returns whether a 4x4 matrix is the identity matrix.
Parameters
mat(Type: Array.<number>)
A 4x4 matrix.
Return Value
Return value. (Type: boolean)
### (static) H3DU.MathUtil.mat4lookat(viewerPos, [lookingAt], [up])
Returns a 4x4 matrix that represents a camera view, transforming world space coordinates, shared by every object in a scene, to coordinates in eye space (also called camera space or view space). This essentially rotates a “camera” and moves it to somewhere in the scene. In eye space:<ul>
viewerPos in world space,
and points away from the viewer toward the lookingAt
position in world space. This generally
puts lookingAt at the center of the view.
up vector guides this direction.
lookingAt point.</ul>
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
* `viewerPos` (Type: Array.<number>)A 3-element vector specifying the "camera" position in world space.
When used in conjunction with an orthographic projection, set this parameter to the value of
lookingAt plus a unit vector (for example, using MathUtil.vec3add) to form an axonometric projection (if the unit vector is [sqrt(1/3),sqrt(1/3),sqrt(1/3)], the result is an isometric projection). See the examples below.
* `lookingAt` (Type: Array.<number>) (optional)A 3-element vector specifying the point in world space that the "camera" is looking at. May be null or omitted, in which case the default is the coordinates (0,0,0). * `up` (Type: Array.<number>) (optional)
A 3-element vector specifying the direction from the center of the "camera" to its top. This parameter may be null or omitted, in which case the default is the vector (0, 1, 0), the vector that results when the "camera" is held upright.
This vector must not be parallel to the view direction (the direction from "viewerPos" to "lookingAt"). (See the example for one way to ensure this.)
#### Return Value The resulting 4x4 matrix. (Type: Array.<number>) #### Examples 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=MathUtil.vec3sub(lookingAt, viewerPos); var par=MathUtil.vec3length(MathUtil.vec3cross(viewdir,upVector)); if(par<0.00001)upVector=[0,0,1]; // view is almost parallel, so use Z axis var matrix=MathUtil.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=MathUtil.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=MathUtil.vec3normalize([1,1,1]); cameraPoint=MathUtil.vec3add(cameraPoint,lookPoint); var matrix=MathUtil.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=MathUtil.vec3normalize([1,1,1]); cameraPoint=MathUtil.vec3add(cameraPoint,lookPoint); // Positive Z axis is the up vector var matrix=MathUtil.mat4lookat(cameraPoint,lookPoint,[0,0,1]); The following example creates a camera view matrix using the viewer position, the viewing direction, and the up vector (a "look-to" matrix): var viewDirection=[0,0,1] var viewerPos=[0,0,0] var upVector=[0,1,0] var lookingAt=MathUtil.vec3add(viewerPos,viewDirection); var matrix=MathUtil.mat4lookat(viewerPos,lookingAt,upVector); ### (static) H3DU.MathUtil.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
* `a` (Type: Array.<number>)The first matrix. * `b` (Type: Array.<number>)
The second matrix. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `alpha` (Type: number)
Controls how much the Z axis is stretched. In degrees. A value of 45 (
arctan(1)) indicates a cabinet projection, and a value of 63.435 (arctan(2)) indicates a cavalier projection.
* `phi` (Type: number)Controls the apparent angle of the negative Z axis in relation to the positive X axis. In degrees. 0 means the negative Z axis appears to point in the same direction as the positive X axis, and 90, in the same direction as the positive Y axis. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `l` (Type: number)
Leftmost coordinate of the orthographic view. * `r` (Type: number)
Rightmost coordinate of the orthographic view. ("l" is usually less than "r", so that X coordinates increase from left to right. If "l" is greater than "r", X coordinates increase in the opposite direction.) * `b` (Type: number)
Bottommost coordinate of the orthographic view. * `t` (Type: number)
Topmost coordinate of the orthographic view. ("b" is usually less than "t", so that Y coordinates increase upward, as they do in WebGL when just this matrix is used to transform vertices. If "b" is greater than "t", Y coordinates increase in the opposite direction.) * `n` (Type: number)
Distance from the "camera" to the near clipping plane. A positive value means the plane is in front of the viewer. * `f` (Type: number)
Distance from the "camera" to the far clipping plane. A positive value means the plane is in front of the viewer. ("n" is usually less than "f", so that Z coordinates increase from near to far in the direction from the back to the front of the "eye", as they do in WebGL when just this matrix is used to transform vertices. If "n" is greater than "f", Z coordinates increase in the opposite direction.) The absolute difference between n and f should be as small as the application can accept. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `l` (Type: number)
Leftmost coordinate of the orthographic view. * `r` (Type: number)
Rightmost coordinate of the orthographic view. ("l" is usually less than "r", so that X coordinates increase from left to right. If "l" is greater than "r", X coordinates increase in the opposite direction.) * `b` (Type: number)
Bottommost coordinate of the orthographic view. * `t` (Type: number)
Topmost coordinate of the orthographic view. ("b" is usually less than "t", so that Y coordinates increase upward, as they do in WebGL when just this matrix is used to transform vertices. If "b" is greater than "t", Y coordinates increase in the opposite direction.) #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `l` (Type: number)
Leftmost coordinate of the view rectangle. * `r` (Type: number)
Rightmost coordinate of the orthographic view. ("l" is usually less than "r", so that X coordinates increase from left to right. If "l" is greater than "r", X coordinates increase in the opposite direction.) * `b` (Type: number)
Bottommost coordinate of the orthographic view. * `t` (Type: number)
Topmost coordinate of the orthographic view. ("b" is usually less than "t", so that Y coordinates increase upward, as they do in WebGL when just this matrix is used to transform vertices. If "b" is greater than "t", Y coordinates increase in the opposite direction.) * `aspect` (Type: number)
The ratio of width to height of the viewport, usually the scene's aspect ratio. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `l` (Type: number)
Leftmost coordinate of the view rectangle. * `r` (Type: number)
Rightmost coordinate of the orthographic view. ("l" is usually less than "r", so that X coordinates increase from left to right. If "l" is greater than "r", X coordinates increase in the opposite direction.) * `b` (Type: number)
Bottommost coordinate of the orthographic view. * `t` (Type: number)
Topmost coordinate of the orthographic view. ("b" is usually less than "t", so that Y coordinates increase upward, as they do in WebGL when just this matrix is used to transform vertices. If "b" is greater than "t", Y coordinates increase in the opposite direction.) * `n` (Type: number)
Distance from the "camera" to the near clipping plane. A positive value means the plane is in front of the viewer. * `f` (Type: number)
Distance from the "camera" to the far clipping plane. A positive value means the plane is in front of the viewer. ("n" is usually less than "f", so that Z coordinates increase from near to far in the direction from the back to the front of the "eye", as they do in WebGL when just this matrix is used to transform vertices. If "n" is greater than "f", Z coordinates increase in the opposite direction.) The absolute difference between n and f should be as small as the application can accept. * `aspect` (Type: number)
The ratio of width to height of the viewport, usually the scene's aspect ratio. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `fovY` (Type: number)
Y axis field of view, in degrees, that is, the shortest angle between the top and bottom clipping planes. Should be less than 180 degrees. (The smaller this number, the bigger close objects appear to be. As a result, zooming out can be implemented by raising this value, and zooming in by lowering it.) * `aspectRatio` (Type: number)
The ratio of width to height of the viewport, usually the scene's aspect ratio. * `near` (Type: number)
The distance, in eye space, from the "camera" to the near clipping plane. Objects closer than this distance won't be seen. 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. * `far` (Type: number)
The distance, in eye space, from the "camera" to the far clipping plane. Objects farther than this distance won't be seen.
This value should be greater than 0 and should be set so that the absolute ratio of "far" to "near" is as small as the application can accept. ("near" is usually less than "far", so that Z coordinates increase from near to far in the direction from the back to the front of the "eye", as they do in WebGL when just this matrix is used to transform vertices. If "near" is greater than "far", Z coordinates increase in the opposite direction.)
In the usual case that "far" is greater than "near", depth buffer values will be more concentrated around the near plane than around the far plane due to the perspective projection. The greater the ratio of "far" to "near", the more concentrated the values will be around the near plane, and the more likely two objects close to the far plane will have identical depth values. (Most WebGL implementations support 24-bit depth buffers, meaning they support 16,777,216 possible values per pixel.) #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `fovX` (Type: number)
X axis field of view, in degrees, that is, the shortest angle between the left and right clipping planes. Should be less than 180 degrees. (The smaller this number, the bigger close objects appear to be. As a result, zooming out can be implemented by raising this value, and zooming in by lowering it.) * `aspectRatio` (Type: number)
The ratio of width to height of the viewport, usually the scene's aspect ratio. * `near` (Type: number)
The distance, in eye space, from the "camera" to the near clipping plane. Objects closer than this distance won't be seen. 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. * `far` (Type: number)
The distance, in eye space, from the "camera" to the far clipping plane. Objects farther than this distance won't be seen.
This value should be greater than 0 and should be set so that the absolute ratio of "far" to "near" is as small as the application can accept. ("near" is usually less than "far", so that Z coordinates increase from near to far in the direction from the back to the front of the "eye", as they do in WebGL when just this matrix is used to transform vertices. If "near" is greater than "far", Z coordinates increase in the opposite direction.)
In the usual case that "far" is greater than "near", depth buffer values will be more concentrated around the near plane than around the far plane due to the perspective projection. The greater the ratio of "far" to "near", the more concentrated the values will be around the near plane, and the more likely two objects close to the far plane will have identical depth values. (Most WebGL implementations support 24-bit depth buffers, meaning they support 16,777,216 possible values per pixel.) #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `mat` (Type: Array.<number>)
A 4x4 matrix to use to transform the vector. This will generally be a projection-view matrix (projection matrix multiplied by the view matrix, in that order), if the vector to transform is in world space, or a model-view-projection matrix, that is, (projection-view matrix multiplied by the model [world] matrix, in that order), if the vector is in model (object) space.
If the matrix includes a projection transform returned by MathUtil.mat4ortho, MathUtil.mat4perspective, or similar Math methods, the X, Y, and Z coordinates within the view volume (as is the case in WebGL) will range from -1 to 1 and increase from left to right, front to back, and bottom to top, unless otherwise specified in those methods' documentation. * `v` (Type: Array.<number> | number)
X coordinate of a 3D point to transform. If "vy" and "vz" are omitted, this value can instead be a 3-element array giving the X, Y, and Z coordinates. * `vy` (Type: number) (optional)
Y coordinate. * `vz` (Type: number) (optional)
Z coordinate. To transform a 2D point, set Z to 0. #### 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.MathUtil.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 * `mat` (Type: Array.<number>)
A 4x4 matrix to multiply. * `angle` (Type: Array.<number> | number)
The desired angle to rotate in degrees. If "v", "vy", and "vz" are omitted, this can instead be a 4-element array giving the axis of rotation as the first three elements, followed by the angle in degrees as the fourth element. * `v` (Type: Array.<number> | number)
X-component of the point lying on the axis of rotation. If "vy" and "vz" are omitted, this can instead be a 3-element array giving the axis of rotation. * `vy` (Type: number)
Y-component of the point lying on the axis of rotation. * `vz` (Type: number)
Z-component of the point lying on the axis of rotation. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `angle` (Type: Array.<number> | number)
The desired angle to rotate in degrees. If "v", "vy", and "vz" are omitted, this can instead be a 4-element array giving the axis of rotation as the first three elements, followed by the angle in degrees as the fourth element. * `v` (Type: Array.<number> | number)
X-component of the point lying on the axis of rotation. If "vy" and "vz" are omitted, this can instead be a 3-element array giving the axis of rotation. * `vy` (Type: number)
Y-component of the point lying on the axis of rotation. * `vz` (Type: number)
Z-component of the point lying on the axis of rotation. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) #### Examples The following example rotates a vector, "vec", about the Z axis by the given angle, "angle". var newVector H3DU.MathUtil.mat4projectVec3( H3DU.MathUtil.mat4rotated(angle, 0, 0, 1), vec); ### (static) H3DU.MathUtil.mat4scale(mat, v3, v3y, v3z) Multiplies a 4x4 matrix by a scaling transformation. #### Parameters * `mat` (Type: Array.<number>)
4x4 matrix to multiply. * `v3` (Type: Array.<number> | number)
Scale factor along the X axis. A scale factor can be negative, in which case the transformation also causes reflection about the corresponding axis. If "v3y" and "v3z" are omitted, this value can instead be a 3-element array giving the scale factors along the X, Y, and Z axes. * `v3y` (Type: number)
Scale factor along the Y axis. * `v3z` (Type: number)
Scale factor along the Z axis. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.mat4scaleInPlace(mat, v3, [v3y], [v3z]) Modifies a 4x4 matrix by multiplying it by a scaling transformation. #### Parameters * `mat` (Type: Array.<number>)
A 4x4 matrix. * `v3` (Type: Array.<number> | number)
Scale factor along the X axis. A scale factor can be negative, in which case the transformation also causes reflection about the corresponding axis. If "v3y" and "v3z" are omitted, this value can instead be a 3-element array giving the scale factors along the X, Y, and Z axes. * `v3y` (Type: number) (optional)
Scale factor along the Y axis. * `v3z` (Type: number) (optional)
Scale factor along the Z axis. #### Return Value The same parameter as "mat". (Type: Array.<number>) ### (static) H3DU.MathUtil.mat4scaled(v3, v3y, v3z) Returns a 4x4 matrix representing a scaling transformation. #### Parameters * `v3` (Type: Array.<number> | number)
Scale factor along the X axis. A scale factor can be negative, in which case the transformation also causes reflection about the corresponding axis. If "v3y" and "v3z" are omitted, this value can instead be a 3-element array giving the scale factors along the X, Y, and Z axes. * `v3y` (Type: number)
Scale factor along the Y axis. * `v3z` (Type: number)
Scale factor along the Z axis. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `matrix` (Type: Array.<number>)
A 4x4 matrix. This will usually be a projection-view matrix (projection matrix multiplied by view matrix, in that order). #### 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 MathUtil.planeNormalizeInPlace). (Type: Array.<Array.<number>>) ### (static) H3DU.MathUtil.mat4toMat3(m4) Returns the upper-left part of a 4x4 matrix as a new 3x3 matrix. #### Parameters * `m4` (Type: Array.<number>)
A 4x4 matrix. #### Return Value The resulting 3x3 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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
* `mat` (Type: Array.<number>)A 4x4 matrix. * `v` (Type: Array.<number> | number)
X coordinate. If "vy", "vz", and "vw" are omitted, this value can instead be a 4-element array giving the X, Y, Z, and W coordinates. * `vy` (Type: number) (optional)
Y coordinate. * `vz` (Type: number) (optional)
Z coordinate. * `vw` (Type: number) (optional)
W coordinate. To transform a 3D point, set W to 1 and divide the result's X, Y, and Z by the result's W. To transform a 2D point, set Z to 0 and W to 1 and divide the result's X and Y by the result's W. #### Return Value The transformed vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 MathUtil.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 * `mat` (Type: Array.<number>)
A 4x4 matrix. * `v` (Type: Array.<number> | number)
X coordinate. If "vy" and "vz" are omitted, this value can instead be a 4-element array giving the X, Y, and Z coordinates. * `vy` (Type: number) (optional)
Y coordinate. * `vz` (Type: number) (optional)
Z coordinate. To transform a 2D point, set Z to 0. #### Return Value The transformed 3-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.mat4translate(mat, v3, v3y, v3z) Multiplies a 4x4 matrix by a translation transformation. #### Parameters * `mat` (Type: Array.<number>)
The matrix to multiply. * `v3` (Type: Array.<number> | number)
Translation along the X axis. If "v3y" and "v3z" are omitted, this value can instead be a 3-element array giving the translations along the X, Y, and Z axes. * `v3y` (Type: number)
Translation along the Y axis. * `v3z` (Type: number)
Translation along the Z axis. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.mat4translated(v3, v3y, v3z) Returns a 4x4 matrix representing a translation. #### Parameters * `v3` (Type: Array.<number> | number)
Translation along the X axis. If "v3y" and "v3z" are omitted, this value can instead be a 3-element array giving the translations along the X, Y, and Z axes. * `v3y` (Type: number)
Translation along the Y axis. * `v3z` (Type: number)
Translation along the Z axis. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.mat4transpose(m4) Returns the transpose of a 4x4 matrix. (A transpose is a matrix whose rows are converted to columns and vice versa.) #### Parameters * `m4` (Type: Array.<number>)
A 4x4 matrix. #### Return Value The resulting 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `mat` (Type: Array.<number>)
A 4x4 matrix. #### Return Value The parameter "mat". (Type: Array.<number>) ### (static) H3DU.MathUtil.planeFromNormalAndPoint(normal, point) Creates a plane from a normal vector and a point on the plane. #### Parameters * `normal` (Type: Array.<number>)
A three-element array identifying the plane's normal vector. * `point` (Type: Array.<number>)
A three-element array identifying a point on the plane. #### Return Value A four-element array describing the plane. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `plane` (Type: Array.<number>)
A four-element array defining the plane. The first three elements of the array are the X, Y, and Z components of the plane's normal vector, and the fourth element is the shortest distance from the plane to the origin, or if negative, from the origin to the plane, divided by the normal's length. #### 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.MathUtil.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 * `plane` (Type: Array.<number>)
A four-element array defining the plane. The first three elements of the array are the X, Y, and Z components of the plane's normal vector, and the fourth element is the shortest distance from the plane to the origin, or if negative, from the origin to the plane, divided by the normal's length. #### Return Value The parameter "plane". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `quat` (Type: Array.<number>)
A quaternion, containing four elements. #### Return Value Return value. (Type: Array.<number>) ### (static) H3DU.MathUtil.quatCopy(a) Returns a copy of a quaternion. #### Parameters * `a` (Type: Array.<number>)
A quaternion. #### Return Value Return value. (Type: Array.<number>) #### See Also MathUtil.vec4copy ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The first quaternion. * `b` (Type: Array.<number>)
The second quaternion. #### Return Value Return value. (Type: number) #### See Also MathUtil.vec4dot ### (static) H3DU.MathUtil.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 * `angle` (Type: Array.<number> | number)
The desired angle to rotate in degrees. If "v", "vy", and "vz" are omitted, this can instead be a 4-element array giving the axis of rotation as the first three elements, followed by the angle in degrees as the fourth element. * `v` (Type: Array.<number> | number)
X-component of the point lying on the axis of rotation. If "vy" and "vz" are omitted, this can instead be a 3-element array giving the axis of rotation. * `vy` (Type: number)
Y-component of the point lying on the axis of rotation. * `vz` (Type: number)
Z-component of the point lying on the axis of rotation. #### 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.MathUtil.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 * `m` (Type: Array.<number>)
A 4x4 matrix. #### Return Value The resulting quaternion. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `pitchDegrees` (Type: number)
Vector rotation about the X axis (upward or downward turn), in degrees. This can instead be a 3-element array giving the rotation about the X axis, Y axis, and Z axis, respectively. * `yawDegrees` (Type: number)
Vector rotation about the Y axis (left or right turn), in degrees. May be null or omitted if "pitchDegrees" is an array. * `rollDegrees` (Type: number)
Vector rotation about the Z axis (swaying side by side), in degrees. May be null or omitted if "pitchDegrees" is an array. * `mode` (Type: number) (optional)
Specifies the order in which the rotations will occur (in terms of their effect). This is one of the Math constants such as MathUtil.LocalPitchYawRoll and MathUtil.GlobalYawRollPitch. If null, undefined, or omitted, the default is MathUtil.GlobalRollPitchYaw. The constants starting with
Global describe a vector rotation in the order given, each about the original axes (these angles are also called extrinsic angles). The constants starting with Local describe a vector rotation in the order given, where the second and third rotations occur around the rotated object's new axes and not necessarily the original axes (these angles are also called intrinsic angles). The order of Local rotations has the same result as the reversed order of Global rotations and vice versa.
#### Return Value
The generated quaternion. (Type: Array.<number>)
### (static) H3DU.MathUtil.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
* `vec1` (Type: Array.<number>)The first 3-element vector. * `vec2` (Type: Array.<number>)
The second 3-element vector. #### Return Value The generated quaternion, which will be a unit vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.quatIdentity() Returns the identity quaternion of multiplication, (0, 0, 0, 1). #### Return Value Return value. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `quat` (Type: Array.<number>)
A quaternion, containing four elements. #### Return Value Return value. (Type: Array.<number>) #### See Also MathUtil.quatConjugate ### (static) H3DU.MathUtil.quatIsIdentity(quat) Returns whether this quaternion is the identity quaternion, (0, 0, 0, 1). #### Parameters * `quat` (Type: Array.<number>)
A quaternion, containing four elements. #### Return Value Return value. (Type: boolean) ### (static) H3DU.MathUtil.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 * `quat` (Type: Array.<number>)
The quaternion. #### Return Value Return value. (Type: number) #### See Also MathUtil.vec4length ### (static) H3DU.MathUtil.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 MathUtil.quatNormalize or MathUtil.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 MathUtil.vec3cross).
#### Parameters
* `a` (Type: Array.<number>)The first quaternion. * `b` (Type: Array.<number>)
The second quaternion. #### Return Value The resulting quaternion. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 MathUtil.quatSlerp method. #### Parameters * `q1` (Type: Array.<number>)
The first quaternion. Must be a unit vector. * `q2` (Type: Array.<number>)
The second quaternion. Must be a unit vector. * `factor` (Type: number)
A value that usually ranges from 0 through 1. Closer to 0 means closer to q1, and closer to 1 means closer to q2. #### Return Value The interpolated quaternion, which will be a unit vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `quat` (Type: Array.<number>)
A quaternion, containing four elements. #### 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 MathUtil.vec4normalize ### (static) H3DU.MathUtil.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 * `quat` (Type: Array.<number>)
A quaternion, containing four elements. #### 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 MathUtil.vec4normalizeInPlace ### (static) H3DU.MathUtil.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 MathUtil.quatMultiply): return quatMultiply(quat,quatFromAxisAngle(angle,v,vy,vz)); #### Parameters * `quat` (Type: Array.<number>)
Quaternion to rotate. * `angle` (Type: Array.<number> | number)
The desired angle to rotate in degrees. If "v", "vy", and "vz" are omitted, this can instead be a 4-element array giving the axis of rotation as the first three elements, followed by the angle in degrees as the fourth element. * `v` (Type: Array.<number> | number)
X-component of the point lying on the axis of rotation. If "vy" and "vz" are omitted, this can instead be a 3-element array giving the axis of rotation. * `vy` (Type: number)
Y-component of the point lying on the axis of rotation. * `vz` (Type: number)
Z-component of the point lying on the axis of rotation. #### Return Value The resulting quaternion. (Type: Array.<number>) ### (static) H3DU.MathUtil.quatScale(a, scalar) Multiplies each element of a quaternion by a factor and returns the result as a new quaternion. #### Parameters * `a` (Type: Array.<number>)
A quaternion. * `scalar` (Type: number)
A factor to multiply. #### Return Value The resulting quaternion. (Type: Array.<number>) #### See Also MathUtil.vec4scaleInPlace ### (static) H3DU.MathUtil.quatScaleInPlace(a, scalar) Multiplies each element of a quaternion by a factor and stores the result in that quaternion. #### Parameters * `a` (Type: Array.<number>)
A quaternion. * `scalar` (Type: number)
A factor to multiply. #### Return Value The parameter "a". (Type: Array.<number>) #### See Also MathUtil.vec4scaleInPlace ### (static) H3DU.MathUtil.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 not commutative (that is, 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 * `q1` (Type: Array.<number>)
The first quaternion. Must be a unit vector. * `q2` (Type: Array.<number>)
The second quaternion. Must be a unit vector. * `factor` (Type: number)
A value that usually ranges from 0 through 1. Closer to 0 means closer to q1, and closer to 1 means closer to q2. #### Return Value The interpolated quaternion. (Type: Array.<number>) #### See Also ["Understanding Slerp, Then Not Using It", Jonathan Blow](http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/), for additional background ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A quaternion. Must be a unit vector. #### 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.MathUtil.quatToMat4(quat) Generates a 4x4 matrix describing the rotation described by this quaternion. #### Parameters * `quat` (Type: Array.<number>)
A quaternion, containing four elements. #### Return Value The generated 4x4 matrix. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A quaternion. Should be a unit vector. * `mode` (Type: number) (optional)
Specifies the order in which the rotations will occur (in terms of their effect, not in terms of how they will be returned by this method). This is one of the Math constants such as MathUtil.LocalPitchYawRoll and MathUtil.GlobalYawRollPitch. If null, undefined, or omitted, the default is MathUtil.GlobalRollPitchYaw. The constants starting with
Global describe a vector rotation in the order given, each about the original axes (these angles are also called extrinsic angles). The constants starting with Local describe a vector rotation in the order given, where the second and third rotations occur around the rotated object's new axes and not necessarily the original axes (these angles are also called intrinsic angles). The order of Local rotations has the same result as the reversed order of Global rotations and vice versa.
#### 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.MathUtil.quatTransform(q, v)
Transforms a 3- or 4-element vector using a
quaternion's vector rotation.
#### Parameters
* `q` (Type: Array.<number>)A quaternion describing the rotation. * `v` (Type: Array.<number>)
A 3- or 4-element vector to transform. The fourth element, if any, is ignored. #### 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.MathUtil.vec2abs(a) Returns a new 2-element vector with the absolute value of each of its components. #### Parameters * `a` (Type: Array.<number>)
A 2-element vector. #### Return Value The resulting 2-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec2absInPlace(a) Sets each component of the given 2-element vector to its absolute value. #### Parameters * `a` (Type: Array.<number>)
A 2-element vector. #### Return Value The vector "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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:
- describes a straight-line path for the combined paths described by the given vectors, in either order, and
- will come "between" the two vectors given (at their shortest angle) if all three start
at the same position.</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 2-element vector. * `b` (Type: Array.<number>)
The second 2-element vector. #### Return Value The resulting 2-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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:- describes a straight-line path for the combined paths described by the given vectors, in either order, and
- will come "between" the two vectors given (at their shortest angle) if all three start
at the same position.</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 2-element vector. * `b` (Type: Array.<number>)
The second 2-element vector. #### Return Value The parameter "a" (Type: Array.<number>) ### (static) H3DU.MathUtil.vec2assign(dst, src) Assigns the values of a 2-element vector into another 2-element vector. #### Parameters * `dst` (Type: Array.<number>)
The 2-element vector to assign to. * `src` (Type: Array.<number>)
The 2-element vector whose values will be copied. #### Return Value The parameter "dst" (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The vector to clamp. * `min` (Type: number)
Lowest possible value. Should not be greater than "max". * `max` (Type: number)
Highest possible value. Should not be less than "min". #### Return Value The resulting vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The vector to clamp. * `min` (Type: number)
Lowest possible value. Should not be greater than "max". * `max` (Type: number)
Highest possible value. Should not be less than "min". #### Return Value The resulting vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec2copy(vec) Returns a copy of a 2-element vector. #### Parameters * `vec` (Type: Array.<number>)
A 2-element vector. #### Return Value Return value. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec2dist(vecFrom, vecTo) Finds the straight-line distance from one three-element vector to another, treating both as 3D points. #### Parameters * `vecFrom` (Type: Array.<number>)
The first 2-element vector. * `vecTo` (Type: Array.<number>)
The second 2-element vector. #### Return Value The distance between the two vectors. (Type: number) ### (static) H3DU.MathUtil.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 MathUtil.vec3dot. #### Parameters * `a` (Type: Array.<number>)
The first 2-element vector. * `b` (Type: Array.<number>)
The second 2-element vector. #### Return Value A number representing the dot product. (Type: number) #### Examples 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(MathUtil.vec2dot(vector, vector)<20*20) { // The vector's length is shorter than 20 units } ### (static) H3DU.MathUtil.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 MathUtil.vec2dot passing the same vector as both of its arguments). #### Parameters * `a` (Type: Array.<number>)
A 2-element vector. #### Return Value Return value. (Type: number) ### (static) H3DU.MathUtil.vec2lerp(v1, v2, factor) Does a linear interpolation between two 2-element vectors; returns a new vector. #### Parameters * `v1` (Type: Array.<number>)
The first vector to interpolate. The interpolation will occur on each component of this vector and v2. * `v2` (Type: Array.<number>)
The second vector to interpolate. * `factor` (Type: number)
A value that usually ranges from 0 through 1. Closer to 0 means closer to v1, and closer to 1 means closer to v2.
For a nonlinear interpolation, define a function that takes a value that usually ranges from 0 through 1 and returns a value generally ranging from 0 through 1, and pass the result of that function to this method. For examples, see MathUtil.vec3lerp. #### Return Value The interpolated vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec2mul(a, b) Multiplies each of the components of two 2-element vectors and returns a new vector with the result. #### Parameters * `a` (Type: Array.<number>)
The first 2-element vector. * `b` (Type: Array.<number>)
The second 2-element vector. #### Return Value The resulting 2-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec2mulInPlace(a, b) Multiplies each of the components of two 2-element vectors and stores the result in the first vector. #### Parameters * `a` (Type: Array.<number>)
The first 2-element vector. * `b` (Type: Array.<number>)
The second 2-element vector. #### Return Value The parameter "a" (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 2-element vector. #### Return Value The resulting 2-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 2-element vector. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `vec` (Type: Array.<number>)
A 2-element vector. #### 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>) #### Examples 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=MathUtil.vec2sub(endPt,startPt); // Normalize delta to a unit vector var deltaNorm=MathUtil.vec2normalize(delta); // Rescale to the desired length, here, 10 MathUtil.vec2scaleInPlace(deltaNorm,10); // Find the new endpoint endPt=MathUtil.vec2add(startPt,deltaNorm); ### (static) H3DU.MathUtil.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 * `vec` (Type: Array.<number>)
A 2-element vector. #### 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.MathUtil.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 * `vec` (Type: Array.<number>)
A 2-element vector. #### Return Value A perpendicular 2-element vector. Returns (0,0) if "vec" is (0,0). (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `vec` (Type: Array.<number>)
The vector to project. * `refVec` (Type: Array.<number>)
The reference vector whose length will be adjusted. #### 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.MathUtil.vec2reflect(incident, normal) Returns a vector that reflects off a surface. #### Parameters * `incident` (Type: Array.<number>)
Incident vector, or a vector headed in the direction of the surface, as a 2-element vector. * `normal` (Type: Array.<number>)
Surface normal vector, or a vector that's perpendicular to the surface, as a 2-element vector. Should be a unit vector. #### Return Value A vector that has the same length as "incident" but is reflected away from the surface. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 2-element vector. * `scalar` (Type: number)
A factor to multiply. To divide a vector by a number, the factor will be 1 divided by that number. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 2-element vector. * `scalar` (Type: number)
A factor to multiply. To divide a vector by a number, the factor will be 1 divided by that number. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The first 2-element vector. * `b` (Type: Array.<number>)
The second 2-element vector. #### Return Value The resulting 2-element vector. This is the vector toafromb. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The first 2-element vector. * `b` (Type: Array.<number>)
The second 2-element vector. #### Return Value The parameter "a". This is the vector to the previousafromb. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec3abs(a) Returns a new 3-element vector with the absolute value of each of its components. #### Parameters * `a` (Type: Array.<number>)
A 3-element vector. #### Return Value The resulting 3-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec3absInPlace(a) Sets each component of the given 3-element vector to its absolute value. #### Parameters * `a` (Type: Array.<number>)
A 3-element vector. #### Return Value The vector "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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:- describes a straight-line path for the combined paths described by the given vectors, in either order, and
- will come "between" the two vectors given (at their shortest angle) if all three start
at the same position.</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value The resulting 3-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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:- describes a straight-line path for the combined paths described by the given vectors, in either order, and
- will come "between" the two vectors given (at their shortest angle) if all three start
at the same position.</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value The parameter "a" (Type: Array.<number>) ### (static) H3DU.MathUtil.vec3assign(dst, src) Assigns the values of a 3-element vector into another 3-element vector. #### Parameters * `dst` (Type: Array.<number>)
The 3-element vector to assign to. * `src` (Type: Array.<number>)
The 3-element vector whose values will be copied. #### Return Value The parameter "dst" (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The vector to clamp. * `min` (Type: number)
Lowest possible value. Should not be greater than "max". * `max` (Type: number)
Highest possible value. Should not be less than "min". #### Return Value The resulting vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The vector to clamp. * `min` (Type: number)
Lowest possible value. Should not be greater than "max". * `max` (Type: number)
Highest possible value. Should not be less than "min". #### Return Value The resulting vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec3copy(vec) Returns a copy of a 3-element vector. #### Parameters * `vec` (Type: Array.<number>)
A 3-element vector. #### Return Value Return value. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 will be a vector that is orthogonal (perpendicular) to both A and B.
- Switching the order of A and B results in a cross product vector with the same length but opposite direction. (Thus, the cross product is not commutative, but it is anticommutative.)
- Let there be a triangle formed by point A, point B, and the point (0,0,0) in that order. While the cross product of A and B points toward the viewer, the triangle's vertices are oriented counterclockwise for right-handed coordinate systems, or clockwise for left-handed systems. The triangle's area is half of the cross product's length.
- The length of the cross
product equals |a| * |b| * |sin θ|
where |x| is the length of vector x, and
θ is the shortest angle between a and b.
It follows that:
- If the length is 0, then A and B are parallel vectors (0 or 180 degrees apart).
- If A and B are unit vectors, the length equals the absolute value of the sine of the shortest angle between A and B.
- If A and B are unit vectors, the cross product will be a unit vector only if A is perpendicular
to B (the shortest angle between A and B will be 90 degrees, since sin 90° = 1).
</ul></ul>
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 * `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value A 3-element vector containing the cross product. (Type: Array.<number>) #### Examples 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=MathUtil.vec3sub(a,c); // Find vector from C to B var db=MathUtil.vec3sub(b,c); // The triangle's normal is the cross product of da and db var normal=MathUtil.vec3cross(da,db); // Find the triangle's area var area=MathUtil.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=MathUtil.vec3cross(unitA,unitB); // Cosine of the angle. Will be positive or negative depending on // the shortest angle between the vectors. var cosine=MathUtil.vec3dot(unitA,unitB); // Sine of the angle. Note that the sine will always be 0 or greater because // the shortest angle between them is positive or 0 degrees. var sine=MathUtil.vec3length(cr); ### (static) H3DU.MathUtil.vec3dist(vecFrom, vecTo) Finds the straight-line distance from one three-element vector to another, treating both as 3D points. #### Parameters * `vecFrom` (Type: Array.<number>)
The first 3-element vector. * `vecTo` (Type: Array.<number>)
The second 3-element vector. #### Return Value The distance between the two vectors. (Type: number) ### (static) H3DU.MathUtil.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:- The dot
product equals |a| * |b| * cos θ
where |x| is the length of vector x, and
θ is the shortest angle between a and b.
It follows that:
- A dot product of 0 indicates that the vectors are 90 degrees apart, making them orthogonal (perpendicular to each other).
- A dot product greater than 0 means less than 90 degrees apart.
- A dot product less than 0 means greater than 90 degrees apart.
- If both vectors are unit vectors, the cosine
of the shortest angle between them is equal to their dot product.
However,
Math.acoswon't return a negative angle from that cosine, so the dot product can't be used to determine if one vector is "ahead of" or "behind" another vector. - If both vectors are unit vectors, a dot product of 1 or -1 indicates that the two vectors are parallel (and the vectors are 0 or 180 degrees apart, respectively.)
- If one of the vectors is a unit vector, the dot product's absolute value will be the length that vector must have to make the closest approach to the other vector's endpoint. If the dot product is negative, the unit vector must also be in the opposite direction to approach the other vector's endpoint. </ul>
- If the two vectors are the same, the return value indicates the vector's length squared. This is illustrated in the example.
- Switching the order of the two vectors results in the
same dot product. (Thus, the dot product is commutative.)
</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value A number representing the dot product. (Type: number) #### Examples 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(MathUtil.vec3dot(vector, vector)<20*20) { // The vector's length is shorter than 20 units } ### (static) H3DU.MathUtil.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 * `vector` (Type: Array.<number>)
A 3-element vector giving the X, Y, and Z coordinates of the 3D point to transform, in window coordinates. * `matrix` (Type: Array.<number>)
A 4x4 matrix. After undoing the transformation to window coordinates, the vector will be transformed by the inverse of this matrix according to the MathUtil.mat4projectVec3 method.
To convert to world space, this parameter will generally be a projection-view matrix (projection matrix multiplied by the view matrix, in that order). To convert to object (model) space, this parameter will generally be a model-view-projection matrix (projection-view matrix multiplied by the world [model] matrix, in that order). See MathUtil.vec3toWindowPoint for the meaning of window coordinates with respect to the "matrix" and "yUp" parameters. * `viewport` (Type: Array.<number>)
A 4-element array specifying the starting position and size of the viewport in window units (such as pixels). In order, the four elements are the starting position's X coordinate, its Y coordinate, the viewport's width, and the viewport's height. Throws an error if the width or height is less than 0. * `yUp` (Type: boolean) (optional)
If omitted or a "falsy" value, reverses the sign of the Y coordinate returned by the MathUtil.mat4projectVec3 method before converting it to window coordinates. If true, the Y coordinate will remain unchanged. If window Y coordinates increase upward, the viewport's starting position is at the lower left corner. If those coordinates increase downward, the viewport's starting position is at the upper left corner. #### Return Value A 3-element array giving the coordinates of the unprojected point, in that order. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 MathUtil.vec3dot passing the same vector as both of its arguments). #### Parameters * `a` (Type: Array.<number>)
A 3-element vector. #### Return Value Return value. (Type: number) ### (static) H3DU.MathUtil.vec3lerp(v1, v2, factor) Does a linear interpolation between two 3-element vectors; returns a new vector. #### Parameters * `v1` (Type: Array.<number>)
The first vector to interpolate. The interpolation will occur on each component of this vector and v2. * `v2` (Type: Array.<number>)
The second vector to interpolate. * `factor` (Type: number)
A value that usually ranges from 0 through 1. Closer to 0 means closer to v1, and closer to 1 means closer to v2.
For a nonlinear interpolation, define a function that takes a value that usually ranges from 0 through 1 and returns a value generally ranging from 0 through 1, and pass the result of that function to this method.
The following are examples of interpolation functions. See also the code examples following this list.- Linear:
factor. Constant speed. - Powers:
Math.pow(factor, N), where N > 0. For example, N=2 means a square, N=3 means cube, N=1/2 means square root, and N=1/3 means cube root. If N > 1, this function starts slow and ends fast. If N < 1, this function starts fast and ends slow. - Sine:
Math.sin(Math.PI\*0.5\*factor). This function starts fast and ends slow. - Smoothstep:
(3.0-2.0\*factor)\*factor\*factor. This function starts and ends slow, and speeds up in the middle. - Perlin's "Smootherstep":
(10+factor\*(factor\*6-15))\*factor\*factor\*factor. This function starts and ends slow, and speeds up in the middle. - Discrete-step timing, where N is a number of steps greater than 0:
- Position start:
factor < 0 ? 0 : Math.max(1.0,(1.0+Math.floor(factor\*N))/N). - Position end:
Math.floor(factor\*N)/N.
- Position start:
- Inverted interpolation:
1.0-INTF(1.0-factor), whereINTF(x)is another interpolation function. This function reverses the speed behavior; for example, a function that started fast now starts slow. - Ease:
factor < 0.5 ? INTF(factor\*2)\*0.5 : 1.0-(INTF((1.0-factor)\*2)\*0.5), whereINTF(x)is another interpolation function. Depending on the underlying function, this function eases in, then eases out, or vice versa. </ul> #### Return Value The interpolated vector. (Type: Array.<number>) #### Examples 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 = MathUtil.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 = MathUtil.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 = MathUtil.vec3lerp(vector1, vector2, factor); ### (static) H3DU.MathUtil.vec3mul(a, b) Multiplies each of the components of two 3-element vectors and returns a new vector with the result. #### Parameters * `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value The resulting 3-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec3mulInPlace(a, b) Multiplies each of the components of two 3-element vectors and stores the result in the first vector. #### Parameters * `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value The parameter "a" (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 3-element vector. #### Return Value The resulting 3-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 3-element vector. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `vec` (Type: Array.<number>)
A 3-element vector. #### 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>) #### Examples 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=MathUtil.vec3sub(endPt,startPt); // Normalize delta to a unit vector var deltaNorm=MathUtil.vec3normalize(delta); // Rescale to the desired length, here, 10 MathUtil.vec3scaleInPlace(deltaNorm,10); // Find the new endpoint endPt=MathUtil.vec3add(startPt,deltaNorm); ### (static) H3DU.MathUtil.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 * `vec` (Type: Array.<number>)
A 3-element vector. #### 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.MathUtil.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 * `vec` (Type: Array.<number>)
A 3-element vector. #### Return Value A perpendicular 3-element vector. Returns (0,0,0) if "vec" is (0,0,0). (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `vec` (Type: Array.<number>)
The vector to project. * `refVec` (Type: Array.<number>)
The reference vector whose length will be adjusted. #### 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.MathUtil.vec3reflect(incident, normal) Returns a vector that reflects off a surface. #### Parameters * `incident` (Type: Array.<number>)
Incident vector, or a vector headed in the direction of the surface, as a 3-element vector. * `normal` (Type: Array.<number>)
Surface normal vector, or a vector that's perpendicular to the surface, as a 3-element vector. Should be a unit vector. #### Return Value A vector that has the same length as "incident" but is reflected away from the surface. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 3-element vector. * `scalar` (Type: number)
A factor to multiply. To divide a vector by a number, the factor will be 1 divided by that number. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 3-element vector. * `scalar` (Type: number)
A factor to multiply. To divide a vector by a number, the factor will be 1 divided by that number. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value The resulting 3-element vector. This is the vector toafromb. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector. #### Return Value The parameter "a". This is the vector to the previousafromb. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `vector` (Type: Array.<number>)
A 3-element vector giving the X, Y, and Z coordinates of the 3D point to transform. * `matrix` (Type: Array.<number>)
A 4x4 matrix to use to transform the vector according to the MathUtil.mat4projectVec3 method, before the transformed vector is converted to window coordinates.
This parameter will generally be a projection-view matrix (projection matrix multiplied by the view matrix, in that order), if the vector to transform is in world space, or a model-view-projection matrix, that is, (projection-view matrix multiplied by the model [world] matrix, in that order), if the vector is in model (object) space.
If the matrix includes a projection transform returned by MathUtil.mat4ortho, MathUtil.mat4perspective, or similar MathUtil methods, then in the window coordinate space, X coordinates increase rightward, Y coordinates increase upward, and Z coordinates within the view volume range from 0 to 1 and increase from front to back, unless otherwise specified in those methods' documentation. If "yUp" is omitted or is a "falsy" value, the Y coordinates increase downward instead of upward or vice versa. * `viewport` (Type: Array.<number>)
A 4-element array specifying the starting position and size of the viewport in window units (such as pixels). In order, the four elements are the starting position's X coordinate, its Y coordinate, the viewport's width, and the viewport's height. Throws an error if the width or height is less than 0. * `yUp` (Type: boolean) (optional)
If omitted or a "falsy" value, reverses the sign of the Y coordinate returned by the MathUtil.mat4projectVec3 method before converting it to window coordinates. If true, the Y coordinate will remain unchanged. If window Y coordinates increase upward, the viewport's starting position is at the lower left corner. If those coordinates increase downward, the viewport's starting position is at the upper left corner. #### Return Value A 3-element array giving the window coordinates, in that order. (Type: Array.<number>) ### (static) H3DU.MathUtil.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):- Switching the order of B and C, A and C, or A and B results in a triple product with its sign reversed. Moving all three parameters to different positions, though, results in the same triple product.
- The triple product's absolute value is the volume of a parallelepiped (skewed box) where three of its sides having a vertex in common are defined by A, B, and C, in any order.
- The triple product's absolute value divided by 6 is the volume of a tetrahedron, where three of its sides having a vertex in common are defined by A, B, and C, in any order.
- If the triple product is 0, all three vectors lie on the same plane (are coplanar).
- The triple product is the same as the determinant (overall scaling factor) of a 3x3 matrix whose rows or columns are the vectors A, B, and C, in that order.
- Assume A is perpendicular to vectors B and C. If the triple product is positive,
then A points in the same direction as the cross product of
B and C -- which will be perpendicular -- and the angle from B to C, when rotated
about vector A, is positive. If the triple product is negative, then A points in the
opposite direction from that cross product, and that angle is negative.
(See the example below.)
</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 3-element vector. * `b` (Type: Array.<number>)
The second 3-element vector, or the first parameter to the cross product. * `c` (Type: Array.<number>)
The third 3-element vector, or the second parameter to the cross product. #### Return Value A number giving the triple product. (Type: number) ### (static) H3DU.MathUtil.vec4abs(a) Returns a new 4-element vector with the absolute value of each of its components. #### Parameters * `a` (Type: Array.<number>)
A 4-element vector. #### Return Value The resulting 4-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec4absInPlace(a) Sets each component of the given 4-element vector to its absolute value. #### Parameters * `a` (Type: Array.<number>)
A 4-element vector. #### Return Value The vector "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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:- describes a straight-line path for the combined paths described by the given vectors, in either order, and
- will come "between" the two vectors given (at their shortest angle) if all three start
at the same position.</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 4-element vector. * `b` (Type: Array.<number>)
The second 4-element vector. #### Return Value The resulting 4-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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:- describes a straight-line path for the combined paths described by the given vectors, in either order, and
- will come "between" the two vectors given (at their shortest angle) if all three start
at the same position.</ul>
#### Parameters
* `a` (Type: Array.<number>)
The first 4-element vector. * `b` (Type: Array.<number>)
The second 4-element vector. #### Return Value The parameter "a". This is the vector to the previousafromb. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec4assign(dst, src) Assigns the values of a 4-element vector into another 4-element vector. #### Parameters * `dst` (Type: Array.<number>)
The 4-element vector to copy the source values to. * `src` (Type: Array.<number>)
The 4-element vector whose values will be copied. #### Return Value The parameter "dst". (Type: Array.<number>) ### (static) H3DU.MathUtil.vec4clamp(a, min, max) Returns a 4-element vector in which each element of the given 4-element vector is clamped #### Parameters * `a` (Type: Array.<number>)
The vector to clamp. * `min` (Type: number)
Lowest possible value. Should not be greater than "max". * `max` (Type: number)
Highest possible value. Should not be less than "min". #### Return Value The resulting vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The vector to clamp. * `min` (Type: number)
Lowest possible value. Should not be greater than "max". * `max` (Type: number)
Highest possible value. Should not be less than "min". #### Return Value The resulting vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.vec4copy(vec) Returns a copy of a 4-element vector. #### Parameters * `vec` (Type: Array.<number>)
A 4-element vector. #### Return Value Return value. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 MathUtil.vec3dot. #### Parameters * `a` (Type: Array.<number>)
The first 4-element vector. * `b` (Type: Array.<number>)
The second 4-element vector. #### Return Value Return value. (Type: number) ### (static) H3DU.MathUtil.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 MathUtil.vec4dot passing the same vector as both of its arguments). #### Parameters * `a` (Type: Array.<number>)
A 4-element vector. #### Return Value Return value. (Type: number) ### (static) H3DU.MathUtil.vec4lerp(v1, v2, factor) Does a linear interpolation between two 4-element vectors; returns a new vector. #### Parameters * `v1` (Type: Array.<number>)
The first vector to interpolate. The interpolation will occur on each component of this vector and v2. * `v2` (Type: Array.<number>)
The second vector to interpolate. * `factor` (Type: number)
A value that usually ranges from 0 through 1. Closer to 0 means closer to v1, and closer to 1 means closer to v2. For a nonlinear interpolation, define a function that takes a value that usually ranges from 0 through 1 and generally returns A value that usually ranges from 0 through 1, and pass the result of that function to this method. See the documentation for MathUtil.vec3lerp for examples of interpolation functions. #### Return Value The interpolated vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 4-element vector. #### Return Value The resulting 4-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 4-element vector. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `vec` (Type: Array.<number>)
A 4-element vector. #### 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.MathUtil.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 * `vec` (Type: Array.<number>)
A 4-element vector. #### 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.MathUtil.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 * `vec` (Type: Array.<number>)
The vector to project. * `refVec` (Type: Array.<number>)
The reference vector whose length will be adjusted. #### 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.MathUtil.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 * `a` (Type: Array.<number>)
A 4-element vector. * `scalar` (Type: number)
A factor to multiply. To divide a vector by a number, the factor will be 1 divided by that number. #### Return Value The resulting 4-element vector. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
A 4-element vector. * `scalar` (Type: number)
A factor to multiply. To divide a vector by a number, the factor will be 1 divided by that number. #### Return Value The parameter "a". (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The first 4-element vector. * `b` (Type: Array.<number>)
The second 4-element vector. #### Return Value The resulting 4-element vector. This is the vector toafromb. (Type: Array.<number>) ### (static) H3DU.MathUtil.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 * `a` (Type: Array.<number>)
The first 4-element vector. * `b` (Type: Array.<number>)
The second 4-element vector. #### Return Value The parameter "a" (Type: Array.<number>) [Back to documentation index.](index.html)
- Linear:
- The dot
product equals |a| * |b| * cos θ
where |x| is the length of vector x, and
θ is the shortest angle between a and b.
It follows that: