npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

math3d

v0.2.2

Published

A nodejs library for 3D transformations similar to Unity3D containing necessary classes and functions for matrices, vectors, quaternions and transforms.

Downloads

5,462

Readme

#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