Reference p5.Vector

p5.Vector

A class to describe a two or three-dimensional vector.

A vector can be thought of in different ways. In one view, a vector is like an arrow pointing in space. Vectors have both magnitude (length) and direction.

p5.Vector objects are often used to program motion because they simplify the math. For example, a moving ball has a position and a velocity. Position describes where the ball is in space. The ball's position vector extends from the origin to the ball's center. Velocity describes the ball's speed and the direction it's moving. If the ball is moving straight up, its velocity vector points straight up. Adding the ball's velocity vector to its position vector moves it, as in pos.add(vel). Vector math relies on methods inside the p5.Vector class.

Note: createVector() is the recommended way to make an instance of this class.

Examples

Syntax

p5.Vector([x], [y], [z])

Parameters

x
Number:

x component of the vector.

y
Number:

y component of the vector.

z
Number:

z component of the vector.

Fields

x

The x component of the vector

y

The y component of the vector

z

The z component of the vector

Methods

toString

Returns a string representation of a vector.

Calling toString() is useful for printing vectors to the console while debugging.

set

Sets the vector's x, y, and z components.

set() can use separate numbers, as in v.set(1, 2, 3), a p5.Vector object, as in v.set(v2), or an array of numbers, as in v.set([1, 2, 3]).

If a value isn't provided for a component, it will be set to 0. For example, v.set(4, 5) sets v.x to 4, v.y to 5, and v.z to 0. Calling set() with no arguments, as in v.set(), sets all the vector's components to 0.

copy

Returns a copy of the p5.Vector object.

add

Adds to a vector's x, y, and z components.

add() can use separate numbers, as in v.add(1, 2, 3), another p5.Vector object, as in v.add(v2), or an array of numbers, as in v.add([1, 2, 3]).

If a value isn't provided for a component, it won't change. For example, v.add(4, 5) adds 4 to v.x, 5 to v.y, and 0 to v.z. Calling add() with no arguments, as in v.add(), has no effect.

The static version of add(), as in p5.Vector.add(v2, v1), returns a new p5.Vector object and doesn't change the originals.

rem

Performs modulo (remainder) division with a vector's x, y, and z components.

rem() can use separate numbers, as in v.rem(1, 2, 3), another p5.Vector object, as in v.rem(v2), or an array of numbers, as in v.rem([1, 2, 3]).

If only one value is provided, as in v.rem(2), then all the components will be set to their values modulo 2. If two values are provided, as in v.rem(2, 3), then v.z won't change. Calling rem() with no arguments, as in v.rem(), has no effect.

The static version of rem(), as in p5.Vector.rem(v2, v1), returns a new p5.Vector object and doesn't change the originals.

sub

Subtracts from a vector's x, y, and z components.

sub() can use separate numbers, as in v.sub(1, 2, 3), another p5.Vector object, as in v.sub(v2), or an array of numbers, as in v.sub([1, 2, 3]).

If a value isn't provided for a component, it won't change. For example, v.sub(4, 5) subtracts 4 from v.x, 5 from v.y, and 0 from v.z. Calling sub() with no arguments, as in v.sub(), has no effect.

The static version of sub(), as in p5.Vector.sub(v2, v1), returns a new p5.Vector object and doesn't change the originals.

mult

Multiplies a vector's x, y, and z components.

mult() can use separate numbers, as in v.mult(1, 2, 3), another p5.Vector object, as in v.mult(v2), or an array of numbers, as in v.mult([1, 2, 3]).

If only one value is provided, as in v.mult(2), then all the components will be multiplied by 2. If a value isn't provided for a component, it won't change. For example, v.mult(4, 5) multiplies v.x by, v.y by 5, and v.z by 1. Calling mult() with no arguments, as in v.mult(), has no effect.

The static version of mult(), as in p5.Vector.mult(v, 2), returns a new p5.Vector object and doesn't change the originals.

div

Divides a vector's x, y, and z components.

div() can use separate numbers, as in v.div(1, 2, 3), another p5.Vector object, as in v.div(v2), or an array of numbers, as in v.div([1, 2, 3]).

If only one value is provided, as in v.div(2), then all the components will be divided by 2. If a value isn't provided for a component, it won't change. For example, v.div(4, 5) divides v.x by, v.y by 5, and v.z by 1. Calling div() with no arguments, as in v.div(), has no effect.

The static version of div(), as in p5.Vector.div(v, 2), returns a new p5.Vector object and doesn't change the originals.

mag

Calculates the magnitude (length) of the vector.

Use mag() to calculate the magnitude of a 2D vector using components as in mag(x, y).

magSq

Calculates the magnitude (length) of the vector squared.

dot

Calculates the dot product of two vectors.

The dot product is a number that describes the overlap between two vectors. Visually, the dot product can be thought of as the "shadow" one vector casts on another. The dot product's magnitude is largest when two vectors point in the same or opposite directions. Its magnitude is 0 when two vectors form a right angle.

The version of dot() with one parameter interprets it as another p5.Vector object.

The version of dot() with multiple parameters interprets them as the x, y, and z components of another vector.

The static version of dot(), as in p5.Vector.dot(v1, v2), is the same as calling v1.dot(v2).

cross

Calculates the cross product of two vectors.

The cross product is a vector that points straight out of the plane created by two vectors. The cross product's magnitude is the area of the parallelogram formed by the original two vectors.

The static version of cross(), as in p5.Vector.cross(v1, v2), is the same as calling v1.cross(v2).

dist

Calculates the distance between two points represented by vectors.

A point's coordinates can be represented by the components of a vector that extends from the origin to the point.

The static version of dist(), as in p5.Vector.dist(v1, v2), is the same as calling v1.dist(v2).

Use dist() to calculate the distance between points using coordinates as in dist(x1, y1, x2, y2).

normalize

Scales the components of a p5.Vector object so that its magnitude is 1.

The static version of normalize(), as in p5.Vector.normalize(v), returns a new p5.Vector object and doesn't change the original.

limit

Limits a vector's magnitude to a maximum value.

The static version of limit(), as in p5.Vector.limit(v, 5), returns a new p5.Vector object and doesn't change the original.

setMag

Sets a vector's magnitude to a given value.

The static version of setMag(), as in p5.Vector.setMag(v, 10), returns a new p5.Vector object and doesn't change the original.

heading

Calculates the angle a 2D vector makes with the positive x-axis.

By convention, the positive x-axis has an angle of 0. Angles increase in the clockwise direction.

If the vector was created with createVector(), heading() returns angles in the units of the current angleMode().

The static version of heading(), as in p5.Vector.heading(v), works the same way.

setHeading

Rotates a 2D vector to a specific angle without changing its magnitude.

By convention, the positive x-axis has an angle of 0. Angles increase in the clockwise direction.

If the vector was created with createVector(), setHeading() uses the units of the current angleMode().

rotate

Rotates a 2D vector by an angle without changing its magnitude.

By convention, the positive x-axis has an angle of 0. Angles increase in the clockwise direction.

If the vector was created with createVector(), rotate() uses the units of the current angleMode().

The static version of rotate(), as in p5.Vector.rotate(v, PI), returns a new p5.Vector object and doesn't change the original.

angleBetween

Calculates the angle between two vectors.

The angles returned are signed, which means that v1.angleBetween(v2) === -v2.angleBetween(v1).

If the vector was created with createVector(), angleBetween() returns angles in the units of the current angleMode().

lerp

Calculates new x, y, and z components that are proportionally the same distance between two vectors.

The amt parameter is the amount to interpolate between the old vector and the new vector. 0.0 keeps all components equal to the old vector's, 0.5 is halfway between, and 1.0 sets all components equal to the new vector's.

The static version of lerp(), as in p5.Vector.lerp(v0, v1, 0.5), returns a new p5.Vector object and doesn't change the original.

slerp

Calculates a new heading and magnitude that are between two vectors.

The amt parameter is the amount to interpolate between the old vector and the new vector. 0.0 keeps the heading and magnitude equal to the old vector's, 0.5 sets them halfway between, and 1.0 sets the heading and magnitude equal to the new vector's.

slerp() differs from lerp() because it interpolates magnitude. Calling v0.slerp(v1, 0.5) sets v0's magnitude to a value halfway between its original magnitude and v1's. Calling v0.lerp(v1, 0.5) makes no such guarantee.

The static version of slerp(), as in p5.Vector.slerp(v0, v1, 0.5), returns a new p5.Vector object and doesn't change the original.

reflect

Reflects a vector about a line in 2D or a plane in 3D.

The orientation of the line or plane is described by a normal vector that points away from the shape.

The static version of reflect(), as in p5.Vector.reflect(v, n), returns a new p5.Vector object and doesn't change the original.

array

Returns the vector's components as an array of numbers.

equals

Checks whether all the vector's components are equal to another vector's.

equals() returns true if the vector's components are all the same as another vector's and false if not.

The version of equals() with one parameter interprets it as another p5.Vector object.

The version of equals() with multiple parameters interprets them as the components of another vector. Any missing parameters are assigned the value 0.

The static version of equals(), as in p5.Vector.equals(v0, v1), interprets both parameters as p5.Vector objects.

fromAngle

Creates a new 2D vector from an angle.

fromAngles

Creates a new 3D vector from a pair of ISO spherical angles.

random2D

Creates a new 2D unit vector with a random heading.

random3D

Creates a new 3D unit vector with a random heading.

clampToZero

Replaces the components of a p5.Vector that are very close to zero with zero.

In computers, handling numbers with decimals can give slightly imprecise answers due to the way those numbers are represented. This can make it hard to check if a number is zero, as it may be close but not exactly zero. This method rounds very close numbers to zero to make those checks easier

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/EPSILON

Notice any errors or typos? Please let us know. Please feel free to edit src/math/p5.Vector.js and open a pull request!

Related References