Narrating Prophetic Monks

# math3d

Vectors, Matrices and Quaternions for Node.js

## Features

• Only the necessary classes and functions for 3D graphics.
• Same coordinate system
• Same rotation order
• Similar syntax

With npm:

## API

All classes except Transform provide immutable objects.

### Coordinate System

As I used this project later on with Unity3D, I tried to keep everything as similar as possible. The coordinate system is the same as in Unity: y-Axis up, x-Axis right, z-Axis forward. The rotation order for Euler angles (used in Quaternion) is z then x then y.

### Vector3

A three-dimensional vector with x, y, z values; used for positions, directions or scales in 3D space.

#### Static variables

• back: Shorthand for writing Vector3(0, 0, -1).
• down: Shorthand for writing Vector3(0, -1, 0).
• forward: Shorthand for writing Vector3(0, 0, 1).
• left: Shorthand for writing Vector3(-1, 0, 0).
• one: Shorthand for writing Vector3(1, 1, -1).
• right: Shorthand for writing Vector3(1, 0, 0).
• up: Shorthand for writing Vector3(0, 1, 0).
• zero: Shorthand for writing Vector3(0, 0, 0).
• dimension: Always 3 for Vector3

#### Variables

• homogeneous: Returns the homogeneous Vector4 with w value 1 (readonly)
• magnitude: Magnitude (length) of the vector (readonly)
• values: An array containing the x, y, z values (readonly)
• vector4: Returns the responding Vector4 with w value 0 (readonly)
• x: x component of the vector (readonly)
• y: y component of the vector (readonly)
• z: z component of the vector (readonly)

#### Constructors

• Vector3([x: Number], [y: Number], [z: Number])
• Creates a Vector3 from the given x, y, z components
• All parameters are optional with default value 0
• Vector3.FromVector4(vector4)
• Creates a Vector3 from a Vector4 by clipping the w value

#### Public functions

• Returns the sum of two vectors
• average(vector3: Vector3) -> Vector3
• Returns the average of two vectors
• cross(vector3: Vector3) -> Vector3
• Cross product of two vectors
• distanceTo(vector3: Vector3) -> Number
• Distance from one vector to another
• dot(vector3: Vector3) -> Number
• Dot product of two vectors
• equals(vector3: Vector3) -> Boolean
• Returns true if two vectors are equal
• mulScalar(scalar: Number) -> Vector3
• Multiplies the vector with a scalar
• negate() -> Vector3
• Returns a vector with the opposite direction (multiplied by -1)
• normalize() -> Vector3
• Returns a normalized vector
• scale(vector3: Vector3) -> Vector3
• Scales the vector component by component with the given vector
• sub(vector3: Vector3) -> Vector3
• Subtracts one vector from another (this - vector3)
• toString() -> String
• A string responding to the vector in form (x,y,z)

### Vector4

A four-dimensional vector with x, y, z, w values. Used mostly for homogeneous coordinates.

#### Static variables

• one: Shorthand for writing Vector4(1, 1, 1, 1).
• zero: Shorthand for writing Vector4(0, 0, 0, 0).
• dimension: Always 4 for Vector4

#### Variables

• magnitude: Magnitude (length) of the vector (readonly)
• values: An array containing the x, y, z, w values (readonly)
• x: x component of the vector (readonly)
• y: y component of the vector (readonly)
• z: z component of the vector (readonly)
• w: w component of the vector (readonly)

#### Constructors

• Vector4([x: Number], [y: Number], [z: Number], [w: Number])
• Creates a Vector4 from the given x, y, z, w components
• All parameters are optional with default value 0

#### Public functions

• Returns the sum of two vectors
• distanceTo(vector4: Vector4) -> Number
• Distance from one vector to another
• dot(vector4: Vector4) -> Number
• Dot product of two vectors
• equals(vector4: Vector4) -> Boolean
• Returns true if two vectors are equal
• mulScalar(scalar: Number) -> Vector4
• Multiplies the vector with a scalar
• negate() -> Vector4
• Returns a vector with the opposite direction (multiplied by -1)
• normalize() -> Vector3
• Returns a normalized vector
• sub(vector4: Vector4) -> Vector3
• Subtracts one vector from another (this - vector4)
• toString() -> String
• A string responding to the vector in form (x,y,z,w)

### Quaternion

Each quaternion is composed of a vector (xyz) and a scalar rotation (w). Although their values are not very intuitive, they are used instead of the Euler angles to:

• avoid Gimbal lock
• avoid different rotation orders for Euler angles
• avoid multiple representation of the same rotation

It is advised not to use the x, y, z, w values directly, unless you really know what you are doing.

#### Static variables

• identity: Shorthand for writing Quaternion(0, 0, 0, 1).
• zero: Shorthand for writing Quaternion(0, 0, 0, 0).

#### Variables

• angleAxis: Angle Axis representation of the quaternion in form {axis: (Vector3), angle: Number} (readonly)
• eulerAngles: Euler angles responding to the quaternion in form {x: Number, y: Number, z: Number} (readonly)
• x: x component of the quaternion (readonly)
• y: y component of the quaternion (readonly)
• z: z component of the quaternion (readonly)
• w: w component of the quaternion (readonly)

#### Constructors

• Quaternion([x: Number], [y: Number], [z: Number], [w: Number])
• Creates a quaternion from the given x, y, z, w values
• All values are optional with default value 0 for x, y, z and 1 for w
• Quaternion.Euler(x: Number, y: Number, z: Number)
• Creates a quaternion that is rotated /z/ degrees around z-axis, /x/ degrees around x-axis and /y/ degrees around y-axis, in that exact order
• Quaternion.AngleAxis(axis: Vector3, angle: Number)
• Creates a quaternion that responds to a rotation of /angle/ degrees around /axis/

#### Public functions

• angleTo(quaternion: Quaternion) -> Number
• Angle between two quaternions in degrees (0 - 180)
• conjugate() -> Quaternion
• Returns the conjugate of the quaternion (defined as (-x, -y, -z, w))
• distanceTo(quaternion: Quaternion) -> Number
• A notion to measure the similarity between two quaternions (quick)
• The return value varies between 0 and 1. Same quaternions return 0.
• dot(quaternion: Quaternion) -> Number
• Dot (inner) product of two quaternions
• equals(quaternion: Quaternion) -> Boolean
• Returns true if two quaternions are equal
• inverse() -> Quaternion
• Returns the inverse of the quaternion (inverse = conjugate)
• mul(quaternion: Quaternion) -> Quaternion
• Right multiplies the quaternion in the argument (this * quaternion)
• mulVector3(vector3: Vector3) -> Vector3
• Multiplies the quaternion with the vector (applies rotation)
• toString() -> String
• A string responding to the quaternion in form (x,y,z,w)

### Matrix4x4

A 4x4 matrix with some required functions for translation, rotation and scaling.

#### Static variables

• identity: 4x4 identity matrix.
• zero: Shorthand for writing Matrix4x4([]]).

#### Variables

• columns: An two-dimensional array containing the columns of a matrix (readonly)
• m11: first element of first row
• m12: second element of first row
• m13: third element of first row
• m14: fourth element of first row
• m21: first element of second row
• m22: second element of second row
• m23: third element of second row
• m24: fourth element of second row
• m31: first element of third row
• m32: second element of third row
• m33: third element of third row
• m34: fourth element of third row
• m41: first element of fourth row
• m42: second element of fourth row
• m43: third element of fourth row
• m44: fourth element of fourth row
• rows: An two-dimensional array containing the rows of a matrix (readonly)
• size: Size (number of rows and columns) of a matrix in form {rows: Number, columns: Number} (readonly)
• values: A one-dimensional array containing the elements of the matrix (rows first) (readonly)

#### Constructors

• Matrix4x4(data: Array)
• Creates a 4x4 matrix with the given number array
• If the length of the array is smaller, the rest is filled with zeros
• Matrix4x4.FlipMatrix(flipX: Boolean, flipY: Boolean, flipZ: Boolean)
• Creates a matrix that changes the direction of the axii that are chosen to be flipped
• Matrix4x4.ScaleMatrix(scale: Number|Vector3)
• Creates a scaling matrix with the given scale factor
• Scale factor can also be given as a number, a uniform vector of it will be created automatically
• Matrix4x4.RotationMatrix(quaternion: Quaternion)
• Creates a rotation matrix for the given quaternion
• Matrix4x4.TranslationMatrix(translation: Vector3)
• Creates a translation matrix from the given vector
• Matrix4x4.TRS(translation: Vector3, rotation: Quaternion, scale: Number|Vector3)
• Creates translation-rotation-scale matrix
• Matrix4x4.LocalToWorldMatrix(position: Vector3, rotation: Quaternion, scale: Number|Vector3)
• Creates a matrix that transforms from a local space to the world space
• The local coordinate system is at /position/ with /rotation/ according to the world space
• /scale/ is defined by (local space scale) / (world space scale)
• Matrix4x4.WorldToLocalMatrix(position: Vector3, rotation: Quaternion, scale: Number|Vector3)
• Creates a matrix that transforms from world space to a local space
• The local coordinate system is at /position/ with /rotation/ according to the world space
• /scale/ is defined by (local space scale) / (world space scale)

#### Public functions

• determinant() -> Number
• Determinant of the matrix
• inverse() -> Matrix4x4|undefined
• Inverse of the matrix, undefined if it is not unique
• negate() -> Matrix4x4
• The negative matrix computed by multiplying the matrix by -1
• transpose() -> Matrix4x4
• Transpose of the matrix
• Returns the sum of two matrices
• sub(matrix4x4: Matrix4x4) -> Matrix4x4
• Subtracts one matrix from another (this - matrix4x4)
• mul(matrix4x4: Matrix4x4) -> Matrix4x4
• Right multiplies with the given matrix (this * matrix4x4)
• mulScalar(scalar: Number) -> Matrix4x4
• Multiplies the matrix with a scalar
• mulVector3(vector3: Vector3) -> Vector3
• Multiplies the matrix with the given vector
• Uses the homogeneous vector representation for the multiplication

### Transform

A class to contain the position and the rotation of an object and create an object hierarchy.

#### Static variables

• Space: An enumeration to decide in which coordinate system to operate
• Self: Applies transformation relative to the local coordinate system
• World: Applies transformation relative to the world coordinate system

#### Variables

• forward: Forward vector in world coordinate system (readonly)
• localPosition: Position in local coordinate system
• localRotation: Rotation in local coordinate system
• localToWorldMatrix: A matrix to transform points from local space to world space (readonly)
• name: Name of the object (default: "object")
• parent: Parent transform of the object (undefined if none)
• position: Position in world coordinate system
• right: Right vector in world coordinate system (readonly)
• root The topmost transform in the hierarchy (readonly)
• rotation: Rotation in world coordinate system
• up: Up vector in world coordinate system (readonly)
• worldToLocalMatrix: A matrix to transform points from world space to local space (readonly)

#### Constructors

• Transform([position: Vector3], [rotation: Quaternion])
• Creates a transform object at the given position and rotation
• Parameters are optional with default values Vector3.zero and Quaternion.identity respectively

#### Public functions

• inverseTransformPosition(position: Vector3) -> Vector3
• Transforms position from world space to local space
• removeChild(child: Transform)
• Removes a child transform
• transformPosition(position: Vector3) -> Vector3
• Transforms position from local space to world space
• translate(translation: Vector3, [relativeTo: Transform.Space]) -> Transform
• Translates by /translation/ relative to /relativeTo/
• /relativeTo/ is optional with default value Transform.Space.Self
• rotate(x: Number, y: Number, z: Number, [relativeTo: Transform.Space]) -> Transform
• Rotates /z/ degrees around z-axis, /x/ degrees around x axis and /y/ degrees around y-axis relative to /relativeTo/ in that exact order
• /relativeTo/ is optional with default value Transform.Space.Self

## Keywords

### install

`npm i math3d`

52

0.2.2

MIT

github