Narrating Prophetic Monks
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    math3dpublic

    math3d

    Vectors, Matrices and Quaternions for Node.js

    Table Of Contents:

    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: 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
    • add(matrix4x4: Matrix4x4) -> Matrix4x4
      • 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.

    var Vector3 = math3d.Vector3;
    var Quaternion = math3d.Quaternion;
    var Transform = math3d.Transform;
     
    var t1 = new Transform(Vector3.zero, Quaternion.Euler(90, 0, 0));
    var t2 = new Transform();
     
    t2.parent = t1;
    t2.translate(new Vector3(3,4,5));
    t2.rotate(15, 20, 90, Transform.Space.World);

    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

    • addChild(child: Transform)
      • Adds a child transform
    • 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

    install

    npm i math3d

    Downloadsweekly downloads

    52

    version

    0.2.2

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar