Parses vector components from arguments.

1vector().toString();         // -> "(0, 0, 0)"
2vector(1).toString();        // -> "(1, 0, 0)"
3vector(1, 2).toString();     // -> "(1, 2, 0)"
4vector(1, 2, 3).toString();  // -> "(1, 2, 3)"

Parses the given input from Cartesian object and returns a new Vector instance.

1/**
2* Vector state defined in Cartesian coordinate system.
3*/
4interface Cartesian {
5	x?: number;
6	y?: number;
7	z?: number;
8}
9
10vector({ x: 1 }).toString();               // -> "(1, 0, 0)"
11vector({ x: 1, y: 2 }).toString();         // -> "(1, 2, 0)"
12vector({ x: 1, y: 2, z: 3 }).toString();   // -> "(1, 2, 3)"

The Cartesian object is considered valid if it is contains at least one of coordinate components: x, y, or z. All missed components defaults to zero, extra data are simply ignored.

1vector({ x: 1, data: "hello!" }).toString();               // -> "(1, 0, 0)"
2vector({ x: 1, y: 2, z: 3, data: "hello!" }).toString();   // -> "(1, 2, 3)"

Parses the given input from CartesianTuple and returns a new Vector instance.

1/**
2* Tuple defining vector state defined in Cartesian coordinate system.
3*/
4type CartesianTuple = readonly [ x: number, y?: number, z?: number ];
5
6vector([ 1 ]).toString();         // -> "(1, 0, 0)"
7vector([ 1, 2 ]).toString();      // -> "(0, 2, 0)"
8vector([ 1, 2, 3 ]).toString();   // -> "(0, 0, 3)"

Parses the Polar input representing the vector in polar coordinates and returns a new Vector instance:

1/**
2* Vector state defined in Polar coordinate system:
3*/
4interface Polar {
5	degrees?: boolean = false;
6	magnitude?: number = 1;
7	phi: number;
8	theta?: number = Math.PI / 2;
9}
10
11vector({ phi: 0 }).toString()    // -> "(1, 0, 0)"
12
13vector({ phi: Math.PI / 2 }));   // -> "(0, 1, 0)";
14
15vector({
16	phi: Math.PI / 2,
17	theta: Math.PI / 2,
18	magnitude: 2
19})                               // -> "(0, 2, 0)";

By default angles input require radians. To use degrees, pass a degrees boolean argument:

1vector({ degrees: true, phi: 0 })                              // -> "(1, 0, 0)");
2vector({ degrees: true, phi: 90 })                             // -> "(0, 1, 0)");
3vector({ degrees: true, phi: 90, theta: 0, magnitude: 2 })     // -> "(0, 0, 2)");
4vector({ degrees: true, phi: 90, theta: 90, magnitude: 2 })    // -> "(0, 2, 0)");

The Polar object is considered valid if it is contains at least one of angle properties: phi or theta. The magnitude defaults to a unit length.

Parses the given input from Cylindrical representing the vector in cylindrical coordinate system and returns a new Vector instance:

1/**
2* Vector state defined in Cylindrical coordinate system:
3*/
4interface Cylindrical {
5	degrees?: boolean = false;
6	p: number = 1;
7	phi: number = 0;
8	z: number = 0;
9}
10
11vector({ p: Math.SQRT2, phi: Math.PI / 4, z: 5 }))    // -> "(1, 1, 5)"
12vector({ p: 7.0711, phi: -Math.PI / 4, z: 12 }))      // -> "(5, -5, 12)"

By default angles input require radians. To use degrees, pass a degrees boolean argument:

1vector({ degrees: true, p: Math.SQRT2, phi: 45, z: 5 }))  // -> "(1, 1, 5)"
2vector({ degrees: true, p: 7.0711, phi: -45, z: 12 }))    // -> "(5, -5, 12)"

The Cylindrical object is considered valid if it is contains all the properties: p, phi, and z. Only degrees property is optional.

Performs the addition and returns the sum as new Vector instance.

1vector(1, 2).add(3, 4).toString();  // -> "(4, 6, 0)"

Adds the another Vector instance or a valid vector input to this vector.

1const v1 = vector(1, 2, 3).addSelf(1, 2, 3);
2const v2 = vector(1, 2, 3);
3
4v1.addSelf(v2);
5v1.toString(); // ->  "(2, 4, 6)"

Calculates the angle between the vector instance and another valid vector input. The angle can be signed if signed boolean argument is passed.

1vector(1, 2, 3).angle(4, 5, 6) // -> 0.22573
2vector(1, 2, 3).angle(4, 5, 6, true) // -> -0.22573
3vector(1, 2, 3).angle(4, 5, 6, true, true) // -> -12.93315

Note: this method do not accept simple arguments input.

Rounds this vector's components values to the next upper bound with defined precision.

1vector(1.12345, 2.45678, 3.78921).ceilSelf().toString()          // -> "(2, 3, 4)");
2vector(Math.SQRT2, Math.PI, 2 * Math.PI).ceilSelf(3).toString()  // -> "(1.415, 3.142, 6.284)");

Clamps this vector's component values between an upper and lower bound.

1vector(1.2, -1).clamp().toString()        // -> "(1, 0, 0)");
2vector(5, 10, -2).clamp(2, 8).toString()  // -> "(5, 8, 2)");

Returns a copy of the vector instance.

1const a = vector(1, 2, 3);
2const b = a.copy();
3
4b.toString(); // -> "(1, 2, 3)"

Calculates the cross product between the instance and another valid vector input and returns a new Vector instance.

1vector(1, 2, 3).cross(4, 5, 6)         // -> (-3, 6, -3)

Sets this vector to the cross product between the original vector and another valid input.

1vector(1, 2, 3).crossSelf(4, 5, 6)         // -> (-3, 6, -3)

Calculates the Euclidean distance between the vector and another valid vector input, considering a point as a vector.

1vector(1, 2, 3).distance(4, 5, 6) // -> 5.19615

Calculates the squared Euclidean distance between the vector and another valid vector input, considering a point as a vector. Slightly more efficient to calculate, useful to comparing.

1vector(1, 2, 3).distanceSq(4, 5, 6) // -> 27

Calculates the dot product of the vector and another valid vector input.

1vector(1, 2, 3).dot(4, 5, 6)   // -> 32

Performs an equality check against another valid vector input.

1vector(1, 2, 3).equals(1, 2, 3);                  // -> true
2vector({ x: 1, y: 2 }).equals([ 1, 2 ]);          // -> true
3vector({ x: -1, y: -2 }).equals({ x: -1, y: 2});  // -> false

Rounds this vector's components values to the next lower bound with defined precision.

1vector(1.12345, 2.45678, 3.78921).floorSelf(4).toString()         // -> "(1.1234, 2.4567, 3.7892)");
2vector(Math.SQRT2, Math.PI, 2 * Math.PI).floorSelf(3).toString()  // -> "(1.414, 3.141, 6.283)");

Calculates vector's azimuthal angle.

1vector(3, 4).getPhi();         // -> 0.927295
2vector(1, -2, 3).getPhi(true); // -> 53.130102

Calculates vector's elevation angle.

1vector(3, 4, 5).getTheta();     // -> 0.785398
2vector(3, 4, 5).getTheta(true); // -> 45

Returns an inverted Vector instance.

1vector(-1, 2).inverted;  // -> "(1, -2, 0)"

Linearly interpolate the vector to another vector.

1const a = vector([ 4, 8, 16 ]);
2const b = vector([ 8, 24, 48 ]);
3
4a.lerp(b)         // ->  "(4, 8, 16)"
5a.lerp(b, -0.5)   // ->  "(4, 8, 16)"
6a.lerp(b, 0.25)   // ->  "(5, 12, 24)"
7a.lerp(b, 0.5)    // ->  "(6, 16, 32)"
8a.lerp(b, 0.75)   // ->  "(7, 20, 40)"
9a.lerp(b, 1)      // ->  "(8, 24, 48)"
10a.lerp(b, 1.5)    // ->  "(8, 24, 48)"

Note: this method do not accept simple arguments input.

Limits the magnitude of the vector and returns the result as new Vector instance.

1const v = vector(3, 4, 12); // magnitude is 13
2
3v.limit(15).magnitude  // -> 13
4v.limit(10).magnitude  // -> 10
5v.limit(13).magnitude  // -> 13

Limits the magnitude of this vector and returns itself.

1const v = vector(3, 4, 12); // magnitude is 13
2
3v.limitSelf(15).magnitude  // -> 13
4v.limitSelf(10).magnitude  // -> 10
5v.limitSelf(13).magnitude  // -> 13

Calculates the magnitude of the vector:

1vector(0).magnitude;         // -> 0
2vector(3, 4).magnitude;      // -> 5
3vector(3, 4, 12).magnitude;  // -> 13

Calls a defined callback on every vector component and returns a new Vector instance:

1vector(1, 2, 3)
2.map(value => value * 2)
3.toString() // -> "(2, 4, 6)"

Calls a defined callback on each of this vector component.

1const v = vector(1, 2, 3);
2v.mapSelf(value => value * 2);
3v.toString() // -> "(2, 4, 6)"

Calculates the squared magnitude of the vector. It may be useful and faster where the real value is not that important. For example, to compare two vectors' length.

1vector(0).magnitudeSq;         // -> 0
2vector(3, 4).magnitudeSq;      // -> 25
3vector(3, 4, 12).magnitudeSq;  // -> 169

Normalizes the vector and returns a new Vector instance as unit vector:

1vector().normalize().magnitude;       // -> 1
2vector(3, 4, 5).normalize().magnitude; // -> 1

Makes the current vector a unit vector.

1vector().normalizeSelf().magnitude;          // -> 0
2vector(3, 4, 12).normalizeSelf().magnitude;   // -> 13

Creates a random planar unit vector (OXY plane).

1vector().random2d().toString() // ->  "(0.23565, 0.75624, 0)"

Creates a random 3D unit vector.

Correct distribution thanks to wolfram.

1vector().random3d().toString() // ->  "(0.23565, 0.75624, -0.56571)"

Reflects the vector about a normal line for 2D vector, or about a normal to a plane in 3D.

Here, in an example the vector a can be viewed as the incident ray, the vector n as the normal, and the resulting vector should be the reflected ray.

1const a = vector([ 4, 6 ]);
2const n = vector([ 0, -1 ]);
3
4a.reflect(n).toString() // ->  "(4, -6, 0)"

Rotates the vector by an azimuthal angle (XOY plane) and returns a new Vector instance.

1vector(1, 2).rotate(Math.PI / 3);
2vector(1, 2).rotate(60, true);

Rotates the current vector by an azimuthal angle (XOY plane).

1vector(1, 2).rotateSelf(Math.PI / 3);
2vector(1, 2).rotateSelf(60, true);

Rotates the vector by an azimuthal and elevation angles and returns a new Vector instance.

1vector(1, 2, 3).rotate3d(Math.PI / 3, Math.PI / 6);
2vector(1, 2, 3).rotate3d(60, 30, true);

Rotates the current vector by an azimuthal and elevation angles.

1vector(1, 2, 3).rotateSelf3d(Math.PI / 3, Math.PI / 6);
2vector(1, 2, 3).rotateSelf3d(60, 30, true);

Rounds this vector's component values to the closest bound with defined precision.

1vector(1.12345, 2.45678, 3.78921).roundSelf(4).toString()         // -> "(1.1235, 2.4568, 3.7892)");
2vector(Math.SQRT2, Math.PI, 2 * Math.PI).roundSelf(3).toString()  // -> "(1.414, 3.142, 6.283)");

Performs the scalar vector multiplication and returns a new Vector instance:

1vector(1, 2).scale(2).toString();      // -> "(2, 4, 0)"
2vector(1, 2, 3).scale(-2).toString();  // -> "(-2, -4, -6)"

The second argument turns the passed value into reciprocal, in other words the division will be performed:

1vector(2, 4, 6).scale(2, true).toString(); // -> "(1, 2, 3)"

Although the same effect can be obtained just with .scale(0.5), it is useful when the variable may have zero value. In case of zero division the zero vector will be returned and marked as invalid.

1const v = vector(1, 2, 3).scale(0, true);
2
3v.valid      // -> false
4v.toString() // -> "(0, 0, 0)"

Scales this vector by a scalar value.

1const a = vector(-1, 2, 3).scaleSelf(5);
2
3a.toString() // -> "(-5, 10, 15)"

The second parameter turns the passed value into reciprocal, in other words the division will be performed:

1const v = vector(-12, -18, -24).scale(2, true);
2v.toString(); // -> "(-6, -9, -12)"

It is useful when the variable may have zero value. In this case the vector components won't change.

Set's the current vector state from another Vector instance or valid vector input.

1const v1 = vector(1, 2, 3);
2v1.setSelf(-1, -2, -3);
3
4v1.toString() // -> "(-1, -2, -3)"

Creates and returns a new Vector instance with modified component value.

1vector(1, 2, 3).setComponent("x", 2).toString(); // -> "(2, 2, 3)"
2vector(1, 2, 3).setComponent("y", 3).toString(); // -> "(1, 3, 3)"
3vector(1, 2, 3).setComponent("z", 4).toString(); // -> "(1, 2, 4)"

Sets the vector instance component value.

1const v = vector(1, 2, 3)
2	.setComponentSelf("x", 0)
3	.setComponentSelf("y", 0)
4	.setComponentSelf("z", 0)
5
6v.toString() // -> "(0, 0, 0)"

Sets the magnitude of the vector and returns a new Vector instance.

1vector(1).setMagnitude(5).magnitude        // -> 5;
2vector(1, 2, 3).setMagnitude(5).magnitude  // -> 5;

Sets the magnitude of this vector.

1vector(1).setMagnitudeSelf(5).magnitude         // -> 5;
2vector(1, 2, 3).setMagnitudeSelf(-5).magnitude  // -> 5;

Rotates the vector instance to a specific azimuthal angle (OXY plane) and returns a new Vector instance.

1vector(1, 2).setPhi(Math.PI / 3);
2vector(1, 2, 3).setPhi(60, true);

Rotates the vector instance to a specific azimuthal angle (OXY plane).

1vector(1, 2).setPhiSelf(Math.PI / 3);
2vector(1, 2, 3).setPhiSelf(60, true);

Rotates the vector instance to a specific elevation angle and returns a new Vector instance.

1vector(1, 2).setTheta(Math.PI / 3);
2vector(1, 2, 3).setTheta(60, true);

Rotates the vector instance to a specific elevation angle.

1vector(1, 2).setThetaSelf(Math.PI / 3);
2vector(1, 2, 3).setThetaSelf(60, true);

Performs the subtraction and returns the result as new Vector instance.

1vector(1, 2, 3).sub(2, 3, 4).toString()  // -> "(-1, -1, -1)"

Subtracts another Vector instance or valid vector input from this vector.

1const v1 = vector(1, 2, 3);
2const v2 = vector(2, 1, 5);
3
4v1.subSelf(v2);
5v1.toString(); // -> "(-1, 1, -2)"

Returns vector's components packed into array.

1vector(1).toArray();        // -> [ 1, 0, 0 ]
2vector(1, 2).toArray();     // -> [ 1, 2, 0 ]
3vector(1, 2, 3).toArray();  // -> [ 1, 2, 3 ]

Returns a Vector string representation.

1vector(1).toString();        // -> "(1, 0, 0)"
2vector(1, 2).toString();     // -> "(1, 2, 0)"
3vector(1, 2, 3).toString();  // -> "(1, 2, 3)"

Passing an invalid input does not throw error. Getter returns a boolean indicating whether user input was valid or not.

Invalid input defaults to zero vector.

1vector([ 1, 2 ]).valid;        // -> true
2vector([ NaN ]).valid;         // -> false
3vector({ x: 1, y: 2 }).valid;  // -> true
4vector({ a: 1, b: 2 }).valid;  // -> false

Converts the vector instance to primitive value - it's magnitude. May be useful when using type coercion.

1const a = vector(3, 4);
2const b = vector(6, 8);
3
4a + b // -> 15