Package processing.core

Class PVector

java.lang.Object
processing.core.PVector
All Implemented Interfaces:
Serializable
public class PVector extends Object implements Serializable
A class to describe a two or three dimensional vector, specifically a Euclidean (also known as geometric) vector. A vector is an entity that has both magnitude and direction. The datatype, however, stores the components of the vector (x,y for 2D, and x,y,z for 3D). The magnitude and direction can be accessed via the methods mag() and heading().

In many of the Processing examples, you will see PVector used to describe a position, velocity, or acceleration. For example, if you consider a rectangle moving across the screen, at any given instant it has a position (a vector that points from the origin to its location), a velocity (the rate at which the object's position changes per time unit, expressed as a vector), and acceleration (the rate at which the object's velocity changes per time unit, expressed as a vector). Since vectors represent groupings of values, we cannot simply use traditional addition/multiplication/etc. Instead, we'll need to do some "vector" math, which is made easy by the methods inside the PVector class.

Advanced

A class to describe a two or three dimensional vector.

The result of all functions are applied to the vector itself, with the exception of cross(), which returns a new PVector (or writes to a specified 'target' PVector). That is, add() will add the contents of one vector to this one. Using add() with additional parameters allows you to put the result into a new PVector. Functions that act on multiple vectors also include static versions. Because creating new objects can be computationally expensive, most functions include an optional 'target' PVector, so that a new PVector object is not created with each operation.

Initially based on the Vector3D class by Dan Shiffman.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    float
    x
    The x component of the vector.
    float
    y
    The y component of the vector.
    float
    z
    The z component of the vector.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PVector()
    Constructor for an empty vector: x, y, and z are set to 0.
    PVector(float x, float y)
    Constructor for a 2D vector: z coordinate is set to 0.
    PVector(float x, float y, float z)
    Constructor for a 3D vector.

  • Method Summary

    Modifier and Type
    Method
    Description
    PVector
    add(float x, float y)
     
    PVector
    add(float x, float y, float z)
     
    PVector
    add(PVector v)
    Adds x, y, and z components to a vector, adds one vector to another, or adds two independent vectors together.
    static PVector
    add(PVector v1, PVector v2)
    Add two vectors
    static PVector
    add(PVector v1, PVector v2, PVector target)
    Add two vectors into a target vector
    static float
    angleBetween(PVector v1, PVector v2)
    Calculates and returns the angle (in radians) between two vectors.
    float[]
    array()
    Return a representation of this vector as a float array.
    PVector
    copy()
    Copies the components of the vector and returns the result as a PVector.
    PVector
    cross(PVector v)
    Calculates and returns a vector composed of the cross product between two vectors.
    PVector
    cross(PVector v, PVector target)
     
    static PVector
    cross(PVector v1, PVector v2, PVector target)
     
    float
    dist(PVector v)
    Calculates the Euclidean distance between two points (considering a point as a vector object).
    static float
    dist(PVector v1, PVector v2)
     
    PVector
    div(float n)
    Divides a vector by a scalar.
    static PVector
    div(PVector v, float n)
    Divide a vector by a scalar and return the result in a new vector.
    static PVector
    div(PVector v, float n, PVector target)
    Divide a vector by a scalar and store the result in another vector.
    float
    dot(float x, float y, float z)
     
    float
    dot(PVector v)
    Calculates the dot product of two vectors.
    static float
    dot(PVector v1, PVector v2)
     
    boolean
    equals(Object obj)
     
    static PVector
    fromAngle(float angle)
    Calculates and returns a new 2D unit vector from the specified angle value (in radians).
    static PVector
    fromAngle(float angle, PVector target)
    Make a new 2D unit vector from an angle
    PVector
    get()
    Deprecated.
    float[]
    get(float[] target)
     
    int
    hashCode()
     
    float
    heading()
    Calculate the angle of rotation for this vector (only 2D vectors)
    float
    heading2D()
    Deprecated.
    PVector
    lerp(float x, float y, float z, float amt)
    Linear interpolate the vector to x,y,z values
    PVector
    lerp(PVector v, float amt)
    Calculates linear interpolation from one vector to another vector.
    static PVector
    lerp(PVector v1, PVector v2, float amt)
    Linear interpolate between two vectors (returns a new PVector object)
    PVector
    limit(float max)
    Limit the magnitude of this vector to the value used for the max parameter.
    float
    mag()
    Calculates the magnitude (length) of the vector and returns the result as a float (this is simply the equation sqrt(x*x + y*y + z*z).)
    float
    magSq()
    Calculates the magnitude (length) of the vector, squared.
    PVector
    mult(float n)
    Multiplies a vector by a scalar.
    static PVector
    mult(PVector v, float n)
     
    static PVector
    mult(PVector v, float n, PVector target)
    Multiply a vector by a scalar, and write the result into a target PVector.
    PVector
    normalize()
    Normalize the vector to length 1 (make it a unit vector).
    PVector
    normalize(PVector target)
     
    static PVector
    random2D()
    Returns a new 2D unit vector with a random direction.
    static PVector
    random2D(PApplet parent)
    Make a new 2D unit vector with a random direction using Processing's current random number generator
    static PVector
    random2D(PVector target)
    Set a 2D vector to a random unit vector with a random direction
    static PVector
    random2D(PVector target, PApplet parent)
    Make a new 2D unit vector with a random direction.
    static PVector
    random3D()
    Returns a new 3D unit vector with a random direction.
    static PVector
    random3D(PApplet parent)
    Make a new 3D unit vector with a random direction using Processing's current random number generator
    static PVector
    random3D(PVector target)
    Set a 3D vector to a random unit vector with a random direction
    static PVector
    random3D(PVector target, PApplet parent)
    Make a new 3D unit vector with a random direction
    PVector
    rotate(float theta)
    Rotate the vector by an angle (only 2D vectors), magnitude remains the same
    PVector
    set(float[] source)
    Set the x, y (and maybe z) coordinates using a float[] array as the source.
    PVector
    set(float x, float y)
     
    PVector
    set(float x, float y, float z)
    Sets the x, y, and z component of the vector using two or three separate variables, the data from a PVector, or the values from a float array.
    PVector
    set(PVector v)
     
    PVector
    setHeading(float angle)
     
    PVector
    setMag(float len)
    Set the magnitude of this vector to the value used for the len parameter.
    PVector
    setMag(PVector target, float len)
    Sets the magnitude of this vector, storing the result in another vector.
    PVector
    sub(float x, float y)
     
    PVector
    sub(float x, float y, float z)
     
    PVector
    sub(PVector v)
    Subtracts x, y, and z components from a vector, subtracts one vector from another, or subtracts two independent vectors.
    static PVector
    sub(PVector v1, PVector v2)
    Subtract one vector from another
    static PVector
    sub(PVector v1, PVector v2, PVector target)
    Subtract one vector from another and store in another vector
    String
    toString()
     

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • x

      public float x
      The x component of the vector. This field (variable) can be used to both get and set the value (see above example.)
      Usage:
      web_application

    • y

      public float y
      The y component of the vector. This field (variable) can be used to both get and set the value (see above example.)
      Usage:
      web_application

    • z

      public float z
      The z component of the vector. This field (variable) can be used to both get and set the value (see above example.)
      Usage:
      web_application

  • Constructor Details

    • PVector

      public PVector()
      Constructor for an empty vector: x, y, and z are set to 0.

    • PVector

      public PVector(float x, float y, float z)
      Constructor for a 3D vector.
      Parameters:
      x - the x coordinate.
      y - the y coordinate.
      z - the z coordinate.

    • PVector

      public PVector(float x, float y)
      Constructor for a 2D vector: z coordinate is set to 0.

  • Method Details

    • set

      public PVector set(float x, float y, float z)
      Sets the x, y, and z component of the vector using two or three separate variables, the data from a PVector, or the values from a float array.
      Parameters:
      x - the x component of the vector
      y - the y component of the vector
      z - the z component of the vector

    • set

      public PVector set(float x, float y)
      Parameters:
      x - the x component of the vector
      y - the y component of the vector

    • set

      public PVector set(PVector v)
      Parameters:
      v - any variable of type PVector

    • set

      public PVector set(float[] source)
      Set the x, y (and maybe z) coordinates using a float[] array as the source.
      Parameters:
      source - array to copy from

    • random2D

      public static PVector random2D()
      Returns a new 2D unit vector with a random direction. If you pass in this as an argument, it will use the PApplet's random number generator.
      Returns:
      the random PVector
      See Also:
      Usage:
      web_application

    • random2D

      public static PVector random2D(PApplet parent)
      Make a new 2D unit vector with a random direction using Processing's current random number generator
      Parameters:
      parent - current PApplet instance
      Returns:
      the random PVector

    • random2D

      public static PVector random2D(PVector target)
      Set a 2D vector to a random unit vector with a random direction
      Parameters:
      target - the target vector (if null, a new vector will be created)
      Returns:
      the random PVector

    • random2D

      public static PVector random2D(PVector target, PApplet parent)
      Make a new 2D unit vector with a random direction. Pass in the parent PApplet if you want randomSeed() to work (and be predictable). Or leave it null and be... random.
      Returns:
      the random PVector

    • random3D

      public static PVector random3D()
      Returns a new 3D unit vector with a random direction. If you pass in this as an argument, it will use the PApplet's random number generator.
      Returns:
      the random PVector
      See Also:
      Usage:
      web_application

    • random3D

      public static PVector random3D(PApplet parent)
      Make a new 3D unit vector with a random direction using Processing's current random number generator
      Parameters:
      parent - current PApplet instance
      Returns:
      the random PVector

    • random3D

      public static PVector random3D(PVector target)
      Set a 3D vector to a random unit vector with a random direction
      Parameters:
      target - the target vector (if null, a new vector will be created)
      Returns:
      the random PVector

    • random3D

      public static PVector random3D(PVector target, PApplet parent)
      Make a new 3D unit vector with a random direction
      Returns:
      the random PVector

    • fromAngle

      public static PVector fromAngle(float angle)
      Calculates and returns a new 2D unit vector from the specified angle value (in radians).
      Parameters:
      angle - the angle in radians
      Returns:
      the new unit PVector
      Usage:
      web_application

    • fromAngle

      public static PVector fromAngle(float angle, PVector target)
      Make a new 2D unit vector from an angle
      Parameters:
      target - the target vector (if null, a new vector will be created)
      Returns:
      the PVector

    • copy

      public PVector copy()
      Copies the components of the vector and returns the result as a PVector.
      Usage:
      web_application

    • get

      @Deprecated public PVector get()
      Deprecated.

    • get

      public float[] get(float[] target)
      Parameters:
      target -

    • mag

      public float mag()
      Calculates the magnitude (length) of the vector and returns the result as a float (this is simply the equation sqrt(x*x + y*y + z*z).)
      Returns:
      magnitude (length) of the vector
      See Also:
      Usage:
      web_application

    • magSq

      public float magSq()
      Calculates the magnitude (length) of the vector, squared. This method is often used to improve performance since, unlike mag(), it does not require a sqrt() operation.
      Returns:
      squared magnitude of the vector
      See Also:
      Usage:
      web_application

    • add

      public PVector add(PVector v)
      Adds x, y, and z components to a vector, adds one vector to another, or adds two independent vectors together. The version of the method that adds two vectors together is a static method and returns a new PVector, the others act directly on the vector itself. See the examples for more context.
      Parameters:
      v - the vector to be added
      Usage:
      web_application

    • add

      public PVector add(float x, float y)
      Parameters:
      x - x component of the vector
      y - y component of the vector

    • add

      public PVector add(float x, float y, float z)
      Parameters:
      z - z component of the vector

    • add

      public static PVector add(PVector v1, PVector v2)
      Add two vectors
      Parameters:
      v1 - a vector
      v2 - another vector

    • add

      public static PVector add(PVector v1, PVector v2, PVector target)
      Add two vectors into a target vector
      Parameters:
      target - the target vector (if null, a new vector will be created)

    • sub

      public PVector sub(PVector v)
      Subtracts x, y, and z components from a vector, subtracts one vector from another, or subtracts two independent vectors. The version of the method that substracts two vectors is a static method and returns a PVector, the others act directly on the vector. See the examples for more context. In all cases, the second vector (v2) is subtracted from the first (v1), resulting in v1-v2.
      Parameters:
      v - any variable of type PVector
      Usage:
      web_application

    • sub

      public PVector sub(float x, float y)
      Parameters:
      x - the x component of the vector
      y - the y component of the vector

    • sub

      public PVector sub(float x, float y, float z)
      Parameters:
      z - the z component of the vector

    • sub

      public static PVector sub(PVector v1, PVector v2)
      Subtract one vector from another
      Parameters:
      v1 - the x, y, and z components of a PVector object
      v2 - the x, y, and z components of a PVector object

    • sub

      public static PVector sub(PVector v1, PVector v2, PVector target)
      Subtract one vector from another and store in another vector
      Parameters:
      target - PVector in which to store the result

    • mult

      public PVector mult(float n)
      Multiplies a vector by a scalar. The version of the method that uses a float acts directly on the vector upon which it is called (as in the first example above). The versions that receive both a PVector and a float as arguments are static methods, and each returns a new PVector that is the result of the multiplication operation. Both examples above produce the same visual output.
      Parameters:
      n - the number to multiply with the vector
      Usage:
      web_application

    • mult

      public static PVector mult(PVector v, float n)
      Parameters:
      v - the vector to multiply by the scalar

    • mult

      public static PVector mult(PVector v, float n, PVector target)
      Multiply a vector by a scalar, and write the result into a target PVector.
      Parameters:
      target - PVector in which to store the result

    • div

      public PVector div(float n)
      Divides a vector by a scalar. The version of the method that uses a float acts directly on the vector upon which it is called (as in the first example above). The version that receives both a PVector and a float as arguments is a static methods, and returns a new PVector that is the result of the division operation. Both examples above produce the same visual output.
      Parameters:
      n - the number by which to divide the vector
      Usage:
      web_application

    • div

      public static PVector div(PVector v, float n)
      Divide a vector by a scalar and return the result in a new vector.
      Parameters:
      v - the vector to divide by the scalar
      Returns:
      a new vector that is v1 / n

    • div

      public static PVector div(PVector v, float n, PVector target)
      Divide a vector by a scalar and store the result in another vector.
      Parameters:
      target - PVector in which to store the result

    • dist

      public float dist(PVector v)
      Calculates the Euclidean distance between two points (considering a point as a vector object).
      Parameters:
      v - the x, y, and z coordinates of a PVector
      Usage:
      web_application

    • dist

      public static float dist(PVector v1, PVector v2)
      Parameters:
      v1 - any variable of type PVector
      v2 - any variable of type PVector
      Returns:
      the Euclidean distance between v1 and v2

    • dot

      public float dot(PVector v)
      Calculates the dot product of two vectors.
      Parameters:
      v - any variable of type PVector
      Returns:
      the dot product
      Usage:
      web_application

    • dot

      public float dot(float x, float y, float z)
      Parameters:
      x - x component of the vector
      y - y component of the vector
      z - z component of the vector

    • dot

      public static float dot(PVector v1, PVector v2)
      Parameters:
      v1 - any variable of type PVector
      v2 - any variable of type PVector

    • cross

      public PVector cross(PVector v)
      Calculates and returns a vector composed of the cross product between two vectors.
      Parameters:
      v - the vector to calculate the cross product

    • cross

      public PVector cross(PVector v, PVector target)
      Parameters:
      v - any variable of type PVector
      target - PVector to store the result

    • cross

      public static PVector cross(PVector v1, PVector v2, PVector target)
      Parameters:
      v1 - any variable of type PVector
      v2 - any variable of type PVector
      target - PVector to store the result

    • normalize

      public PVector normalize()
      Normalize the vector to length 1 (make it a unit vector).
      Usage:
      web_application

    • normalize

      public PVector normalize(PVector target)
      Parameters:
      target - Set to null to create a new vector
      Returns:
      a new vector (if target was null), or target

    • limit

      public PVector limit(float max)
      Limit the magnitude of this vector to the value used for the max parameter.
      Parameters:
      max - the maximum magnitude for the vector
      Usage:
      web_application

    • setMag

      public PVector setMag(float len)
      Set the magnitude of this vector to the value used for the len parameter.
      Parameters:
      len - the new length for this vector
      Usage:
      web_application

    • setMag

      public PVector setMag(PVector target, float len)
      Sets the magnitude of this vector, storing the result in another vector.
      Parameters:
      target - Set to null to create a new vector
      len - the new length for the new vector
      Returns:
      a new vector (if target was null), or target

    • heading

      public float heading()
      Calculate the angle of rotation for this vector (only 2D vectors)
      Returns:
      the angle of rotation
      Usage:
      web_application

    • heading2D

      @Deprecated public float heading2D()
      Deprecated.

    • setHeading

      public PVector setHeading(float angle)

    • rotate

      public PVector rotate(float theta)
      Rotate the vector by an angle (only 2D vectors), magnitude remains the same
      Parameters:
      theta - the angle of rotation
      Usage:
      web_application

    • lerp

      public PVector lerp(PVector v, float amt)
      Calculates linear interpolation from one vector to another vector. (Just like regular lerp(), but for vectors.)

      Note that there is one static version of this method, and two non-static versions. The static version, lerp(v1, v2, amt) is given the two vectors to interpolate and returns a new PVector object. The static version is used by referencing the PVector class directly. (See the middle example above.) The non-static versions, lerp(v, amt) and lerp(x, y, z, amt), do not create a new PVector, but transform the values of the PVector on which they are called. These non-static versions perform the same operation, but the former takes another vector as input, while the latter takes three float values. (See the top and bottom examples above, respectively.)
      Parameters:
      v - the vector to lerp to
      amt - The amount of interpolation; some value between 0.0 (old vector) and 1.0 (new vector). 0.1 is very near the old vector; 0.5 is halfway in between.
      See Also:
      Usage:
      web_application

    • lerp

      public static PVector lerp(PVector v1, PVector v2, float amt)
      Linear interpolate between two vectors (returns a new PVector object)
      Parameters:
      v1 - the vector to start from
      v2 - the vector to lerp to

    • lerp

      public PVector lerp(float x, float y, float z, float amt)
      Linear interpolate the vector to x,y,z values
      Parameters:
      x - the x component to lerp to
      y - the y component to lerp to
      z - the z component to lerp to

    • angleBetween

      public static float angleBetween(PVector v1, PVector v2)
      Calculates and returns the angle (in radians) between two vectors.
      Parameters:
      v1 - the x, y, and z components of a PVector
      v2 - the x, y, and z components of a PVector
      Usage:
      web_application

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • array

      public float[] array()
      Return a representation of this vector as a float array. This is only for temporary use. If used in any other fashion, the contents should be copied by using the copy() method to copy into your own array.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object