vector2js

Vector2js

A simple 2D Vectors for JS.

Read the docs

Full docs can be found here.

Install

You can install via npm:

npm install vector2js

Or bower:

bower install vector2js

Or simply download the js files from /dist/ in this repo.

Usage

If you are using nodejs or browserify, you can use Vector2js like this:

// include vector2js
var Vector = require('vector2js');
 
// create a new vector
var vec = new Vector(10, 10);

If you include the JavaScript from /dist/ directly into your web pages, you will have 'Vector' in global scope and you can create new vectors like this:

// create a new vector
var vec = new Vector(10, 10);

Basic usage example:

Here's a basic usage example - adding two vectors and print the result length:

var v1 = new Vector(5, 10);
var v2 = new Vector(1, 1);
console.log(v1.add(v2).length())
> 12.529964086141668

Tests & Browser support

Vector2js is fully testes on Node.js, IE6 & above, Edge, Chrome, FireFox and Opera, and have coverage of 100%.

Test in browsers

To test in browsers just open the file /tests/test.html with your browser of choice.

Test in Node.js

To test in nodejs first install qunit-cli:

npm install qunit-cli

Then you can run the following command from the project root:

qunit-cli tests/test.js

API

The following are all the API functions the vector class has:

.clone ()
    [chainable][clone]
    Clone the vector and return the cloned instance.
    Return: Cloned Vector.
 
.equals (vector)
    Get if equal to another vector
    Param vector - other vector to compare with.
    Return: If Vectors Are Equal.
 
.copy (vector)
    [chainable][changeSelf]
    Set values from another vector. this changes value of self.
    Param vector - other vector to get values from.
    Return: Self.
 
.copyX (vector)
    [chainable][changeSelf]
    Set only the x component from another vector.
    Return: Self.
 
.copyY (vector)
    [chainable][changeSelf]
    Set only the y component from another vector.
    Return: Self.
 
.toDict ()
    Convert to a dictionary with {x, y}.
    Return: A Dictionary Representation Of The Vector.
 
.toArray ()
    Convert to array with x, y.
    Return: An Array Representation Of The Vector.
 
.set (x, y)
    [chainable][changeSelf]
    Set values from x, y.
    Param x - optional x component to set.
    Param y - optional y component to set.
    Return: Self.
 
.flipXY ()
    [chainable][clone]
    Clone and flip between x and y values.
    Return: Cloned Vector With Flipped X And Y Components.
 
.flipXYSelf ()
    [chainable][changeSelf]
    Flip between x and y values.
    Return: Self.
 
.invert ()
    [chainable][clone]
    Clone and invert x and y values (like multiply with -1, eg x, y => -x, -y)
    Return: Cloned Vector With Inverted Values.
 
.invertSelf ()
    [chainable][changeSelf]
    Invert x and y values (like multiply with -1, eg x, y => -x, -y)
    Return: Self.
 
.distanceFrom (other)
    Get the distance from another vector.
    Param other - vector to get distance from.
    Return: Distance Between Vectors.
 
.radiansTo (other)
    Get angle from another vector in radians.
    Return: Angle In Radians From This To Other.
 
.degreesTo (other)
    Get degrees from another vector in degrees.
    Return: Angle In Degrees From This To Other.
 
.toRadians (other)
    Convert this vector to a radian angle.
    This is equivalent to doing vector.zero.radiansto(this).
    Return: Angle In Radians.
 
.toDegrees (other)
    Convert this vector to degree.
    This is equivalent to doing vector.zero.degreeto(this).
    Return: Angle In Degrees (0-360).
 
.rotateDegreesSelf (degrees)
    [chainable][changeSelf]
    Rotate this vector by a given degree.
    Param degrees - degrees to rotate this vector by (can be positive or negative).
    Return: Self.
 
.rotateDegrees (degrees)
    [chainable]
    Clone and rotate the vector by a given degree.
    Param degrees - degree to rotate this vector by (can be positive or negative).
    Return: Cloned Rotated Vector.
 
.rotateRadiansSelf (radians)
    [chainable][changeSelf]
    Rotate this vector by a given radian.
    Param radians - radians to rotate this vector by (can be positive or negative).
    Return: Self.
 
.rotateRadians (radians)
    [chainable]
    Clone and rotate the vector by a given degree.
    Param radians - radians to rotate this vector by (can be positive or negative).
    Return: Cloned Rotated Vector.
 
.length ()
    Calculate the length of this vector (aka magnitude).
    Return: Vector Length.
 
.normalizeSelf ()
    [chainable][changeSelf]
    Normalize this vector, eg make length equal 1.
    Return: Self.
 
.normalize ()
    [chainable][clone]
    Clone and normalize the vector.
    Return: Normalized Vector.
 
.addSelf (other)
    [chainable][changeSelf]
    Add other vector to self.
    For example, v(10, 11) + v(5, 6) = v(15, 17).
    Param other - vector to add components to self.
    Return: Self.
 
.subSelf (other)
    [chainable][changeSelf]
    Subtract other vector from self.
    For example, v(10, 10) - v(2, 3) = v(8, 7).
    Param other - vector to subtract components from self.
    Return: Self.
 
.divSelf (other)
    [chainable][changeSelf]
    Divide self by other vector.
    For example, v(10, 20) / v(2, 5) = v(5, 4).
    Param other - vector to divide components from self.
    Return: Self.
 
.mulSelf (other)
    [chainable][changeSelf]
    Multiply self vector by other vector.
    For example, v(2, 3) * v(3, 4) = v(6, 12).
    Param other - vector to multiply components with self.
    Return: Self.
 
.addScalarSelf (val)
    [chainable][changeSelf]
    Add scalar value to self.
    For example, v(2, 3) + 5 = v(7, 8).
    Param val - value to add to components.
    Return: Self.
 
.subScalarSelf (val)
    [chainable][changeSelf]
    Subtract scalar from self.
    For example, v(7, 9) - 5 = v(3, 4).
    Param val - value to subtract from components.
    Return: Self.
 
.divScalarSelf (val)
    [chainable][changeSelf]
    Divide self by scalar.
    For example, v(6, 8) / 5 = v(3, 4).
    Param val - value to divide components by.
    Return: Self.
 
.mulScalarSelf (val)
    [chainable][changeSelf]
    Multiply self by scalar.
    For example, v(2, 3) * 2 = v(4, 6).
    Param val - value to multiply components with.
    Return: Self.
 
.add (other)
    [chainable][clone]
    Clone self and add other vector to it.
    Param other - vector to add with.
    Return: Cloned Vector.
 
.sub (other)
    [chainable][clone]
    Clone self and subtract other vector from it.
    Param other - vector to subtract with.
    Return: Cloned Vector.
 
.mul (other)
    [chainable][clone]
    Clone self and multiply by other vector.
    Param other - vector to multiply with.
    Return: Cloned Vector.
 
.div (other)
    [chainable][clone]
    Clone self and divide by other vector.
    Param other - vector to divide with.
    Param scalar - value to divide by.
    Return: Cloned Vector.
 
.addScalar (scalar)
    [chainable][clone]
    Clone self and add scalar to it.
    Param scalar - value to add.
    Return: Cloned Vector.
 
.subScalar (scalar)
    [chainable][clone]
    Clone self and substract scalar from it.
    Param scalar - value to subtract.
    Return: Cloned Vector.
 
.mulScalar (scalar)
    [chainable][clone]
    Clone self and multiply by scalar.
    Param scalar - value to multiply with.
    Return: Cloned Vector.
 
.divScalar (scalar)
    [chainable][clone]
    Clone self and divide by scalar.
    Param scalar - value to divide by.
    Return: Cloned Vector.
 
.clampSelf (min, max)
    [chainable][changeSelf]
    Clamp vector values into range.
    Note: this function does not validate that min < max.
    Param min - min value for x, y components.
    Param max - max value for x, y components.
    Return: Self.
 
.clamp (min, max)
    [chainable][clone]
    Clone vector and clamp its values.
    Note: this function does not validate that min < max.
    Param min - min value for x, y components.
    Param max - max value for x, y components.
    Return: Cloned Vector In Range.
 
.applySelf (func)
    [chainable][changeSelf]
    Apply a function on x and y components of the vector.
    For example, you can use math.round to round the vector x, y values.
    Param func - function to apply on components.
    Return: Self.
 
.apply (func)
    [chainable][clone]
    Clone self and apply a function on x and y components of the clone vector.
    For example, you can use math.round to round the vector x, y values.
    Param func - function to apply on components.
    Return: Cloned Vector.
 
.absSelf ()
    [chainable][changeSelf]
    Turn self to absolute values (eg turn x, y positive).
    Return: Self.
 
.abs ()
    [chainable][clone]
    Clone and turn to absolute values (eg turn x, y positive).
    Return: Cloned Vector.
 
.roundSelf ()
    [chainable][changeSelf]
    Turn self to round values (eg turn x, y positive).
    Return: Self.
 
.round ()
    [chainable][clone]
    Clone and turn to round values (eg turn x, y positive).
    Return: Cloned Vector.
 
.dot (other)
    Calculate dot-product of this vector with another vector.
    Param other - other vector to calculate dot-product with.
    Return: Dot Product.
 
.cross (other)
    Calculate cross-product of this vector with another vector.
    Param other - other vector to calculate cross-product with.
    Return: Dot Product.
 
.repairSelf (x, y)
    [chainable][changeSelf]
    If any of the components of this vector are nan, null, undefined, etc. set them to defaults.
    Note: 0's are considered to be a valid number and will not be replaced with a default value.
    Param x - default value for x if undefined (0 if not defined).
    Param y - default value for y if undefined (0 if not defined).
    Return: Self.
 
.repair (x, y)
    [chainable][clone]
    Create a clone and if any of the components of the vector are nan, null, undefined, etc. set them to default.
    Note: 0's are considered to be a valid number and will not be replaced with a default value.
    Param x - default value for x if undefined (0 if not defined).
    Param y - default value for y if undefined (0 if not defined).
    Return: Repaired Clone.
 
.toString ()
    Convert to string in the form of "x,y".
    Return: String Representation Of The Vector.
 
.format (format)
    Convert to a string with a given format.
    Param format - a string in which %x and %y will be replaced with the vector values.
    Return: Formatted String Representing The Vector.

Consts

Vector2js comes with few useful constant vectors you can use:

Vector.zero = new Vector(0, 0); 
Vector.one = new Vector(1, 1); 
Vector.up = new Vector(0, -1); 
Vector.down = new Vector(0, 1); 
Vector.left = new Vector(-1, 0); 
Vector.right = new Vector(1, 0); 
Vector.upLeft = new Vector(-1, -1); 
Vector.downLeft = new Vector(-1, 1); 
Vector.upRight = new Vector(1, -1); 
Vector.downRight = new Vector(1, 1); 

License

Vector2js is distributed under the MIT license and is free for any personal or commercial purpose.