Math3d

#math3d

Vectors, Matrices and Quaternions for Node.js

Table Of Contents:

• Features
• Installation
• API
  • About Classes
  • Coordinate System
  • Vector3
    • Static variables
    • Variables
    • Constructors
    • Public functions
  • Vector4
    • Static variables
    • Variables
    • Constructors
    • Public functions
  • Quaternion
    • Static variables
    • Variables
    • Constructors
    • Public functions
  • Matrix4x4
    • Static variables
    • Variables
    • Constructors
    • Public functions
  • Transform
    • Static variables
    • Variables
    • Constructors
    • Public functions

Features

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

Installation

With npm:

npm install math3d

API

About Classes

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.

var Vector3 = math3d.Vector3;

var v1 = new Vector3(42, 42, 42);
v1.add(Vector3.up); // Vector3(42, 43, 42);

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

• add(vector3: Vector3) -> Vector3
  • 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.

var Vector3 = math3d.Vector3;
var Vector4 = math3d.Vector4;

var v1 = new Vector4(42, 42);     // v1 = Vector4(42, 42, 0, 1)
var v2 = Vector3.fromVector4(v1); // v2 = Vector3(42, 42, 0)
var v3 = v2.vector4;              // v3 = Vector4(42, 42, 0, 0)
var v4 = v2.homogeneous;          // v4 = Vector4(42, 42, 0, 1)
v4.sub(v3).equals(new Vector4())  // false

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

• add(vector4: Vector4) -> Vector4
  • 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.

var Vector3 = math3d.Vector3;

var v1 = Vector3.forward;         // v1 = Vector3(0, 0, 1)
var q1 = Quaternion.Euler(0, 90, 0);
q1.mulVector3(v1);                // (0, 0, -1) <- v1 rotated 90 degrees in y-Axis
q1.angleAxis;                     // {axis: Vector3(0, 1, 0), angle: 90}

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.

var Vector3 = math3d.Vector3;
var Matrix4x4 = math3d.Matrix4x4;

var v1 = new Vector3(3, 4, 5);
var m1 = Matrix4x4.scaleMatrix(v1);   // m1 = |3 0 0 0|
                                      //      |0 4 0 0|
                                      //      |0 0 5 0|
                                      //      |0 0 0 1|
m1.mulVector3(Vector3.up);            // Vector3(0, 4, 0)

Static variables

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

Variables

• columns