Module org.praxislive.code
Package org.praxislive.code.userapi

Class PVector

  • All Implemented Interfaces:
    Serializable, DataObject
    public class PVector
extends Object
implements Serializable, DataObject
    ( begin auto-generated from PVector.xml ) A class to describe a two or three dimensional vector. This datatype stores two or three variables that are commonly used as a position, velocity, and/or acceleration. Technically, position is a point and velocity and acceleration are vectors, but this is often simplified to consider all three as vectors. For example, if you consider a rectangle moving across the screen, at any given instant it has a position (the object's location, expressed as a point.), 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.

    The methods for this class are extensive. For a complete list, visit the developer's reference. ( end auto-generated ) 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:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected double[] array
      Array so that this can be temporarily used in an array context
      double x
      ( begin auto-generated from PVector_x.xml ) The x component of the vector.
      double y
      ( begin auto-generated from PVector_y.xml ) The y component of the vector.
      double z
      ( begin auto-generated from PVector_z.xml ) 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​(double x, double y)
      Constructor for a 2D vector: z coordinate is set to 0.
      PVector​(double x, double y, double z)
      Constructor for a 3D vector.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      PVector add​(double x, double y)  
      PVector add​(double x, double y, double z)  
      PVector add​(PVector v)
      ( begin auto-generated from PVector_add.xml ) 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 double angleBetween​(PVector v1, PVector v2)
      ( begin auto-generated from PVector_angleBetween.xml ) Calculates and returns the angle (in radians) between two vectors.
      double[] array()
      ( begin auto-generated from PVector_array.xml ) Return a representation of this vector as a double array.
      PVector copy()
      ( begin auto-generated from PVector_copy.xml ) Gets a copy of the vector, returns a PVector object.
      PVector cross​(PVector v)
      ( begin auto-generated from PVector_cross.xml ) 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)  
      double dist​(PVector v)
      ( begin auto-generated from PVector_dist.xml ) Calculates the Euclidean distance between two points (considering a point as a vector object).
      static double dist​(PVector v1, PVector v2)  
      PVector div​(double n)
      ( begin auto-generated from PVector_div.xml ) Divides a vector by a scalar or divides one vector by another.
      static PVector div​(PVector v, double n)
      Divide a vector by a scalar and return the result in a new vector.
      static PVector div​(PVector v, double n, PVector target)
      Divide a vector by a scalar and store the result in another vector.
      double dot​(double x, double y, double z)  
      double dot​(PVector v)
      ( begin auto-generated from PVector_dot.xml ) Calculates the dot product of two vectors.
      static double dot​(PVector v1, PVector v2)  
      boolean equals​(Object obj)  
      static PVector fromAngle​(double angle)
      ( begin auto-generated from PVector_sub.xml ) Make a new 2D unit vector from an angle.
      static PVector fromAngle​(double angle, PVector target)
      Make a new 2D unit vector from an angle
      double[] get​(double[] target)  
      int hashCode()  
      double heading()
      ( begin auto-generated from PVector_setMag.xml ) Calculate the angle of rotation for this vector (only 2D vectors) ( end auto-generated )
      PVector lerp​(double x, double y, double z, double amt)
      Linear interpolate the vector to x,y,z values
      PVector lerp​(PVector v, double amt)
      ( begin auto-generated from PVector_rotate.xml ) Linear interpolate the vector to another vector ( end auto-generated )
      static PVector lerp​(PVector v1, PVector v2, double amt)
      Linear interpolate between two vectors (returns a new PVector object)
      PVector limit​(double max)
      ( begin auto-generated from PVector_limit.xml ) Limit the magnitude of this vector to the value used for the max parameter.
      double mag()
      ( begin auto-generated from PVector_mag.xml ) Calculates the magnitude (length) of the vector and returns the result as a double (this is simply the equation sqrt(x*x + y*y + z*z).) ( end auto-generated )
      double magSq()
      ( begin auto-generated from PVector_mag.xml ) Calculates the squared magnitude of the vector and returns the result as a double (this is simply the equation (x*x + y*y + z*z).) Faster if the real length is not required in the case of comparing vectors, etc.
      PVector mult​(double n)
      ( begin auto-generated from PVector_mult.xml ) Multiplies a vector by a scalar or multiplies one vector by another.
      static PVector mult​(PVector v, double n)  
      static PVector mult​(PVector v, double n, PVector target)
      Multiply a vector by a scalar, and write the result into a target PVector.
      PVector normalize()
      ( begin auto-generated from PVector_normalize.xml ) Normalize the vector to length 1 (make it a unit vector).
      PVector normalize​(PVector target)  
      static PVector random2D()
      ( begin auto-generated from PVector_random2D.xml ) Make a new 2D unit vector with a random direction.
      static PVector random2D​(PVector target)
      Set a 2D vector to a random unit vector with a random direction
      static PVector random3D()
      ( begin auto-generated from PVector_random3D.xml ) Make a new 3D unit vector with a random direction.
      static PVector random3D​(PVector target)
      Set a 3D vector to a random unit vector with a random direction
      void readFrom​(DataInput in)  
      PVector rotate​(double theta)
      ( begin auto-generated from PVector_rotate.xml ) Rotate the vector by an angle (only 2D vectors), magnitude remains the same ( end auto-generated )
      PVector set​(double[] source)
      Set the x, y (and maybe z) coordinates using a double[] array as the source.
      PVector set​(double x, double y)  
      PVector set​(double x, double y, double z)
      ( begin auto-generated from PVector_set.xml ) 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 double array.
      PVector set​(PVector v)  
      PVector setMag​(double len)
      ( begin auto-generated from PVector_setMag.xml ) Set the magnitude of this vector to the value used for the len parameter.
      PVector setMag​(PVector target, double len)
      Sets the magnitude of this vector, storing the result in another vector.
      OptionalInt size()  
      PVector sub​(double x, double y)  
      PVector sub​(double x, double y, double z)  
      PVector sub​(PVector v)
      ( begin auto-generated from PVector_sub.xml ) 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()  
      void writeTo​(DataOutput out)  

    • Field Detail

      • x

        public double x
        ( begin auto-generated from PVector_x.xml ) The x component of the vector. This field (variable) can be used to both get and set the value (see above example.) ( end auto-generated )

      • y

        public double y
        ( begin auto-generated from PVector_y.xml ) The y component of the vector. This field (variable) can be used to both get and set the value (see above example.) ( end auto-generated )

      • z

        public double z
        ( begin auto-generated from PVector_z.xml ) The z component of the vector. This field (variable) can be used to both get and set the value (see above example.) ( end auto-generated )

      • array

        protected transient double[] array
        Array so that this can be temporarily used in an array context

    • Constructor Detail

      • PVector

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

      • PVector

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

      • PVector

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

    • Method Detail

      • set

        public PVector set​(double x,
                   double y,
                   double z)
        ( begin auto-generated from PVector_set.xml ) 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 double array. ( end auto-generated )
        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​(double x,
                   double 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​(double[] source)
        Set the x, y (and maybe z) coordinates using a double[] array as the source.
        Parameters:
        source - array to copy from

      • random2D

        public static PVector random2D()
        ( begin auto-generated from PVector_random2D.xml ) Make 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. You can also pass in a target PVector to fill.
        Returns:
        the random PVector
        See Also:
        random3D()

      • 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

      • random3D

        public static PVector random3D()
        ( begin auto-generated from PVector_random3D.xml ) Make 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. You can also pass in a target PVector to fill.
        Returns:
        the random PVector
        See Also:
        random2D()

      • 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

      • fromAngle

        public static PVector fromAngle​(double angle)
        ( begin auto-generated from PVector_sub.xml ) Make a new 2D unit vector from an angle. ( end auto-generated )
        Parameters:
        angle - the angle in radians
        Returns:
        the new unit PVector

      • fromAngle

        public static PVector fromAngle​(double 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()
        ( begin auto-generated from PVector_copy.xml ) Gets a copy of the vector, returns a PVector object. ( end auto-generated )

      • get

        public double[] get​(double[] target)
        Parameters:
        target -

      • mag

        public double mag()
        ( begin auto-generated from PVector_mag.xml ) Calculates the magnitude (length) of the vector and returns the result as a double (this is simply the equation sqrt(x*x + y*y + z*z).) ( end auto-generated )
        Returns:
        magnitude (length) of the vector
        See Also:
        magSq()

      • magSq

        public double magSq()
        ( begin auto-generated from PVector_mag.xml ) Calculates the squared magnitude of the vector and returns the result as a double (this is simply the equation (x*x + y*y + z*z).) Faster if the real length is not required in the case of comparing vectors, etc. ( end auto-generated )
        Returns:
        squared magnitude of the vector
        See Also:
        mag()

      • add

        public PVector add​(PVector v)
        ( begin auto-generated from PVector_add.xml ) 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 PVector, the others have no return value -- they act directly on the vector. See the examples for more context. ( end auto-generated )
        Parameters:
        v - the vector to be added

      • add

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

      • add

        public PVector add​(double x,
                   double y,
                   double 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)
        ( begin auto-generated from PVector_sub.xml ) 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 subtracts two vectors is a static method and returns a PVector, the others have no return value -- they act directly on the vector. See the examples for more context. ( end auto-generated )
        Parameters:
        v - any variable of type PVector

      • sub

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

      • sub

        public PVector sub​(double x,
                   double y,
                   double 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​(double n)
        ( begin auto-generated from PVector_mult.xml ) Multiplies a vector by a scalar or multiplies one vector by another. ( end auto-generated )
        Parameters:
        n - the number to multiply with the vector

      • mult

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

      • mult

        public static PVector mult​(PVector v,
                           double 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​(double n)
        ( begin auto-generated from PVector_div.xml ) Divides a vector by a scalar or divides one vector by another. ( end auto-generated )
        Parameters:
        n - the number by which to divide the vector

      • div

        public static PVector div​(PVector v,
                          double 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,
                          double 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 double dist​(PVector v)
        ( begin auto-generated from PVector_dist.xml ) Calculates the Euclidean distance between two points (considering a point as a vector object). ( end auto-generated )
        Parameters:
        v - the x, y, and z coordinates of a PVector

      • dist

        public static double 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 double dot​(PVector v)
        ( begin auto-generated from PVector_dot.xml ) Calculates the dot product of two vectors. ( end auto-generated )
        Parameters:
        v - any variable of type PVector
        Returns:
        the dot product

      • dot

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

      • dot

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

      • cross

        public PVector cross​(PVector v)
        ( begin auto-generated from PVector_cross.xml ) Calculates and returns a vector composed of the cross product between two vectors. ( end auto-generated )
        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()
        ( begin auto-generated from PVector_normalize.xml ) Normalize the vector to length 1 (make it a unit vector). ( end auto-generated )

      • 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​(double max)
        ( begin auto-generated from PVector_limit.xml ) Limit the magnitude of this vector to the value used for the max parameter. ( end auto-generated )
        Parameters:
        max - the maximum magnitude for the vector

      • setMag

        public PVector setMag​(double len)
        ( begin auto-generated from PVector_setMag.xml ) Set the magnitude of this vector to the value used for the len parameter. ( end auto-generated )
        Parameters:
        len - the new length for this vector

      • setMag

        public PVector setMag​(PVector target,
                      double 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 double heading()
        ( begin auto-generated from PVector_setMag.xml ) Calculate the angle of rotation for this vector (only 2D vectors) ( end auto-generated )
        Returns:
        the angle of rotation

      • rotate

        public PVector rotate​(double theta)
        ( begin auto-generated from PVector_rotate.xml ) Rotate the vector by an angle (only 2D vectors), magnitude remains the same ( end auto-generated )
        Parameters:
        theta - the angle of rotation

      • lerp

        public PVector lerp​(PVector v,
                    double amt)
        ( begin auto-generated from PVector_rotate.xml ) Linear interpolate the vector to another vector ( end auto-generated )
        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:
        PApplet#lerp(double, double, double)

      • lerp

        public static PVector lerp​(PVector v1,
                           PVector v2,
                           double 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​(double x,
                    double y,
                    double z,
                    double 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 double angleBetween​(PVector v1,
                                  PVector v2)
        ( begin auto-generated from PVector_angleBetween.xml ) Calculates and returns the angle (in radians) between two vectors. ( end auto-generated )
        Parameters:
        v1 - the x, y, and z components of a PVector
        v2 - the x, y, and z components of a PVector

      • array

        public double[] array()
        ( begin auto-generated from PVector_array.xml ) Return a representation of this vector as a double array. This is only for temporary use. If used in any other fashion, the contents should be copied by using the PVector.get() method to copy into your own array. ( end auto-generated )

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object