org.gicentre.utils.network.traer.physics

## Class Vector3D

- java.lang.Object
- - org.gicentre.utils.network.traer.physics.Vector3D

- All Implemented Interfaces:
    Locatable

      public class Vector3D
      extends java.lang.Object
      implements Locatable

  Represents 3D vectors and the operations on them. Most operations change the underlying Vector3D. So if v1 = (1,1,1) = v2, after adding (0,0,1) to v1 via `add(float, float, float)`, v1 != v2. The one exception is the `cross(Vector3D)` method, which always returns a new Vector3D. Also, none of the operations alter their parameters, except in self-referential conditions (e.g., `Vector3D.add(v1,v2,v1)` modifies v1). The methods in the class are designed to allow "chaining"; given a Vector3D v1, it could be used as:
  `v1.add(1,2,3);
  v1.add(3,2,1);
  v1.multiplyBy(2);`
  However, because the class is designed to allow chaining, those operations can also be done as:
  `v1.add(1,2,3).add(3,2,1).multiplyBy(2);`
  Standard mathematical order-of-operations applies, so
  `v1.add(1,2,3).add(3,2,1).multiplyBy(2) == v1.add(3,2,1).add(1,2,3).multiplyBy(2)
  v1.add(1,2,3).add(3,2,1).multiplyBy(2) != v1.multiplyBy(2).add(1,2,3).add(3,2,1)`
  Finally, most of the methods throw NullPointerException if provided a null argument instead of Vector3D argument.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jeffrey Traer Bernstein, Carl Pearson and minor modifications by Jo Wood.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Vector3D()` Creates a (0,0,0) Vector3D.
    `Vector3D(float x, float y, float z)` Creates a 3D vector with the given x, y, z components.
    `Vector3D(processing.core.PVector location)` Creates a 3D vector from the location defined in the given pVector.
    `Vector3D(Vector3D p)` Creates a new cloned 3D vector copied from the components of the given vector.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Vector3D` | `add(float x, float y, float z)` Adds the arguments to this vector's components.
    `Vector3D` | `add(Vector3D p)` Adds the argument Vector3D's components to this Vector3D's components.
    `static Vector3D` | `add(Vector3D v1, Vector3D v2)` Creates a new Vector3D from v1+v2.
    `static Vector3D` | `add(Vector3D v1, Vector3D v2, Vector3D target)` Returns v1+v2 in target, or a new Vector3D if target is null
    `void` | `clear()` Resets this vector back to (0,0,0).
    `Vector3D` | `copy()` Provides a copy of this Vector3D.
    `static Vector3D` | `copy(Vector3D from)` Copies the provided Vector3D.
    `Vector3D` | `cross(Vector3D v)` Creates a new Vector3D from this and the cross product with the given vector.
    `float` | `distanceSquaredTo(Vector3D v)` Like `distanceTo(Vector3D)`, only squared
    `float` | `distanceTo(float x, float y, float z)` Calculates the distance between this vector and that represented by the three given components.
    `float` | `distanceTo(Vector3D v)` Calculates the distance between the tip of this Vector3D and that of p.
    `float` | `dot(Vector3D p)` Calculates the dot product between this Vector3D and another - this.x*p.x + this.y*p.y + this.y*p.y
    `boolean` | `equals(java.lang.Object other)`
    `protected boolean` | `equals(Vector3D other)` Determines if the components of this vector match those of the given one.
    `Vector3D` | `floor(float f)` The opposite of `limit(float)`: puts a lower bound on the length of `f`.
    `processing.core.PVector` | `getLocation()` Reports the location represented by this vector.
    `float` | `getX()` Reports the x component of this vector.
    `float` | `getY()` Reports the y component of this vector.
    `float` | `getZ()` Reports the the z component of this vector.
    `int` | `hashCode()` Returns a unique hash code that represents the content of this vector.
    `boolean` | `isZero()` Indicates whether or not this Vector3D is the zero vector
    `float` | `length()` Reports the length of this vector.
    `Vector3D` | `length(float f)` Reports the normalised length of this vector scaled by the given scale factor.
    `float` | `lengthSquared()` Reports the squared length of this vector.
    `Vector3D` | `limit(float f)` Limits the length of this Vector3D to `f`.
    `Vector3D` | `multiplyBy(float f)` Multiplies each component by `f`.
    `static Vector3D` | `multiplyBy(Vector3D v, float f)` Creates a new Vector3D from v, by copying it and multiplying each of its components by f.
    `static Vector3D` | `multiplyBy(Vector3D v, float f, Vector3D target)` Returns the result of v*f in target, or creates a new Vector3D if target==null.
    `Vector3D` | `normalize()` Sets this Vector3Ds length to one by appropriately scaling x, y, and z.
    `static Vector3D` | `of()` Creates a 'zero' vector.
    `static Vector3D` | `of(float x, float y, float z)` Static constructor; convenience method for chaining calls.
    `Vector3D` | `projectOnto(Vector3D p)` Projects this Vector3D onto another Vector3D.
    `Vector3D` | `set(float x, float y, float z)` Sets all the components.
    `Vector3D` | `set(Vector3D p)` Sets this Vector3D components to those of another Vector3D.
    `Vector3D` | `setX(float x)` Sets the x component and return this Vector3D after modification.
    `Vector3D` | `setY(float y)` Sets the y component and return this Vector3D after modification.
    `Vector3D` | `setZ(float z)` Sets the z component and return this Vector3D after modification.
    `Vector3D` | `subtract(float x, float y, float z)` Subtracts the arguments from this vector's components.
    `Vector3D` | `subtract(Vector3D p)` Subtracts the argument from this vector.
    `static Vector3D` | `subtract(Vector3D v1, Vector3D v2)` Returns a new Vector3D, v1 - v2.
    `static Vector3D` | `subtract(Vector3D v1, Vector3D v2, Vector3D target)` Returns v1-v2 in target, or a new Vector3D if target is null.
    `static Vector3D` | `thrower(java.lang.String message)` Throws a NullPointerException with the provided message.
    `java.lang.String` | `toString()` Provides a textual representation of this vector.
    `float` | `x()` Reports the x component of this vector, but consider using getX() instead to follow standard accessor notation.
    `float` | `y()` Reports the y component of this vector, but consider using getY() instead to follow standard accessor notation.
    `float` | `z()` Reports the the z component of this vector, but consider using getZ() instead to follow standard accessor notation.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Vector3D

          public Vector3D()

      Creates a (0,0,0) Vector3D.

    - #### Vector3D

          public Vector3D(processing.core.PVector location)

      Creates a 3D vector from the location defined in the given pVector.
      Parameters:
        `location` - Location information used to create this 3d vector.

    - #### Vector3D

          public Vector3D(float x,
                          float y,
                          float z)

      Creates a 3D vector with the given x, y, z components.
      Parameters:
        `x` - the x component of the vector.
        `y` - the y component of the vector.
        `z` - the z component of the vector.

    - #### Vector3D

          public Vector3D(Vector3D p)
                   throws java.lang.NullPointerException

      Creates a new cloned 3D vector copied from the components of the given vector.
      Parameters:
        `p` - the source Vector3D.
      Throws:
        `java.lang.NullPointerException` - if p is null

  - ### Method Detail

    - #### of

          public static final Vector3D of(float x,
                                          float y,
                                          float z)

      Static constructor; convenience method for chaining calls. Replaces `Vector3D v2 = (new Vector3D(x,y,z)).add(v1)...` with `Vector3D v2 = Vector3D.of(x,y,z).add(v1)...`
      Parameters:
        `x` - the x component of the vector.
        `y` - the y component of the vector.
        `z` - the z component of the vector.
      Returns:
        A new Vector3D, with the appropriate components

    - #### of

          public static final Vector3D of()

      Creates a 'zero' vector.
      Returns:
        a new Vector3D (0,0,0)

    - #### copy

          public static final Vector3D copy(Vector3D from)

      Copies the provided Vector3D.
      Parameters:
        `from` - the source Vector3D.
      Returns:
        a new Vector3D with identical components to from.
      Throws:
        `java.lang.NullPointerException` - if the from vector is null.

    - #### copy

          public final Vector3D copy()

      Provides a copy of this Vector3D.
      Returns:
        a new Vector3D with identical components to this one

    - #### thrower

          public static final Vector3D thrower(java.lang.String message)
                                        throws java.lang.NullPointerException

      Throws a NullPointerException with the provided message.
      Parameters:
        `message` - the message
      Returns:
        convenience return type for use with ? : ; operator
      Throws:
        `java.lang.NullPointerException` - Null pointer exception.

    - #### subtract

          public final Vector3D subtract(float x,
                                         float y,
                                         float z)

      Subtracts the arguments from this vector's components.
      Parameters:
        `x` - the x component of the vector.
        `y` - the y component of the vector.
        `z` - the z component of the vector.
      Returns:
        this, modified by subtraction

    - #### subtract

          public final Vector3D subtract(Vector3D p)
                                  throws java.lang.NullPointerException

      Subtracts the argument from this vector.
      Parameters:
        `p` - the vector to subtract from this one; p is unmodified by this call
      Returns:
        this, modified by subtraction
      Throws:
        `java.lang.NullPointerException` - if p is null

    - #### subtract

          public static final Vector3D subtract(Vector3D v1,
                                                Vector3D v2)
                                         throws java.lang.NullPointerException

      Returns a new Vector3D, v1 - v2.
      Parameters:
        `v1` - the first vector; not modified by this operation.
        `v2` - the second vector; not modified by this operation.
      Returns:
        a new Vector3D, v1-v2.
      Throws:
        `java.lang.NullPointerException` - if either of v1 or v2 is null

    - #### subtract

          public static final Vector3D subtract(Vector3D v1,
                                                Vector3D v2,
                                                Vector3D target)
                                         throws java.lang.NullPointerException

      Returns v1-v2 in target, or a new Vector3D if target is null.
      Parameters:
        `v1` - the first vector; unmodified by this operation
        `v2` - the second vector; unmodified by this operation
        `target` - the target vector, may be null
      Returns:
        target, or a new Vector3D
      Throws:
        `java.lang.NullPointerException` - if either of v1 or v2 is null

    - #### add

          public final Vector3D add(float x,
                                    float y,
                                    float z)

      Adds the arguments to this vector's components.
      Parameters:
        `x` - the x component of the vector.
        `y` - the y component of the vector.
        `z` - the z component of the vector.
      Returns:
        this, modified by addition.

    - #### add

          public final Vector3D add(Vector3D p)
                             throws java.lang.NullPointerException

      Adds the argument Vector3D's components to this Vector3D's components.
      Parameters:
        `p` - the Vector3D to be added to this one; unmodified by this operation
      Returns:
        this Vector3D, after modification
      Throws:
        `java.lang.NullPointerException` - if p==null

    - #### add

          public static Vector3D add(Vector3D v1,
                                     Vector3D v2)
                              throws java.lang.NullPointerException

      Creates a new Vector3D from v1+v2.
      Parameters:
        `v1` - one Vector3D, unmodified by this operation
        `v2` - the other Vector3D, unmodified by this operation
      Returns:
        a new Vector3D, v1+v2
      Throws:
        `java.lang.NullPointerException` - if either v1 or v2 is null

    - #### add

          public static Vector3D add(Vector3D v1,
                                     Vector3D v2,
                                     Vector3D target)
                              throws java.lang.NullPointerException

      Returns v1+v2 in target, or a new Vector3D if target is null
      Parameters:
        `v1` - the first vector; unmodified by this operation (unless also the target)
        `v2` - the second vector; unmodified by this operation (unless also the target)
        `target` - the target vector, may be null
      Returns:
        target, or a new Vector3D
      Throws:
        `java.lang.NullPointerException` - if either of v1 or v2 is null

    - #### x

          public final float x()

      Reports the x component of this vector, but consider using getX() instead to follow standard accessor notation.
      Returns:
        the x component of this vector.

    - #### y

          public final float y()

      Reports the y component of this vector, but consider using getY() instead to follow standard accessor notation.
      Returns:
        the y component of this vector.

    - #### z

          public final float z()

      Reports the the z component of this vector, but consider using getZ() instead to follow standard accessor notation.
      Returns:
        the z component of this vector.

    - #### getX

          public final float getX()

      Reports the x component of this vector.
      Returns:
        the x component of this vector.

    - #### getY

          public final float getY()

      Reports the y component of this vector.
      Returns:
        the y component of this vector.

    - #### getZ

          public final float getZ()

      Reports the the z component of this vector.
      Returns:
        the z component of this vector.

    - #### getLocation

          public processing.core.PVector getLocation()

      Reports the location represented by this vector.
      Specified by:
        `getLocation` in interface `Locatable`
      Returns:
        Location represented by this vector.

    - #### setX

          public final Vector3D setX(float x)

      Sets the x component and return this Vector3D after modification.
      Parameters:
        `x` - the new x component of this vector.
      Returns:
        this Vector3D, after modification

    - #### setY

          public final Vector3D setY(float y)

      Sets the y component and return this Vector3D after modification.
      Parameters:
        `y` - the new y component of this vector.
      Returns:
        this Vector3D, after modification

    - #### setZ

          public final Vector3D setZ(float z)

      Sets the z component and return this Vector3D after modification.
      Parameters:
        `z` - the new z component of this vector.
      Returns:
        this Vector3D, after modification

    - #### set

          public final Vector3D set(float x,
                                    float y,
                                    float z)

      Sets all the components.
      Parameters:
        `x` - the desired x component of this vector.
        `y` - the desired y component of this vector.
        `z` - the desired z component of this vector.
      Returns:
        this Vector3D, after modification.

    - #### set

          public final Vector3D set(Vector3D p)
                             throws java.lang.NullPointerException

      Sets this Vector3D components to those of another Vector3D.
      Parameters:
        `p` - the other Vector3D of this vector.
      Returns:
        this Vector3D, modified.
      Throws:
        `java.lang.NullPointerException` - if p is null

    - #### multiplyBy

          public final Vector3D multiplyBy(float f)

      Multiplies each component by `f`.
      Parameters:
        `f` - the scaling factor.
      Returns:
        this Vector3D, modified

    - #### multiplyBy

          public static final Vector3D multiplyBy(Vector3D v,
                                                  float f)
                                           throws java.lang.NullPointerException

      Creates a new Vector3D from v, by copying it and multiplying each of its components by f.
      Parameters:
        `v` - the original Vector3D; unmodified by this operation.
        `f` - the scaling factor.
      Returns:
        a new Vector3D, v*f.
      Throws:
        `java.lang.NullPointerException` - if v==null.

    - #### multiplyBy

          public static final Vector3D multiplyBy(Vector3D v,
                                                  float f,
                                                  Vector3D target)
                                           throws java.lang.NullPointerException

      Returns the result of v*f in target, or creates a new Vector3D if target==null.
      Parameters:
        `v` - the source Vector3D; unmodified by this operation.
        `f` - the scaling factor.
        `target` - the target Vector3D; modified by this operation, may be null.
      Returns:
        target, modified, or a new Vector3D.
      Throws:
        `java.lang.NullPointerException` - if v==null.

    - #### limit

          public final Vector3D limit(float f)

      Limits the length of this Vector3D to `f`. Calling this with f less than or equal to 0 sets length to 0.
      Parameters:
        `f` - the desired limit.
      Returns:
        this Vector3D, appropriately modified

    - #### floor

          public final Vector3D floor(float f)

      The opposite of `limit(float)`: puts a lower bound on the length of `f`. Calling this with f less than or equal to 0 is a no-op.
      Parameters:
        `f` - the desired minimum length
      Returns:
        this Vector3D, appropriately modified

    - #### normalize

          public final Vector3D normalize()
                                   throws java.lang.ArithmeticException

      Sets this Vector3Ds length to one by appropriately scaling x, y, and z.
      Returns:
        this Vector3D, modified.
      Throws:
        `java.lang.ArithmeticException` - if this is a zero vector.

    - #### distanceTo

          public final float distanceTo(Vector3D v)
                                 throws java.lang.NullPointerException

      Calculates the distance between the tip of this Vector3D and that of p. Relies on `subtract(Vector3D, Vector3D)` and `length()`.
      Parameters:
        `v` - the other Vector3D; unmodified by this operation
      Returns:
        the distance between this and p
      Throws:
        `java.lang.NullPointerException` - if p==null

    - #### distanceSquaredTo

          public final float distanceSquaredTo(Vector3D v)
                                        throws java.lang.NullPointerException

      Like `distanceTo(Vector3D)`, only squared
      Parameters:
        `v` - the other Vector3D; unmodified by this operation
      Returns:
        the distance between this and p, squared
      Throws:
        `java.lang.NullPointerException` - if p==null

    - #### distanceTo

          public final float distanceTo(float x,
                                        float y,
                                        float z)

      Calculates the distance between this vector and that represented by the three given components.
      Parameters:
        `x` - The x component of the vector.
        `y` - The y component of the vector.
        `z` - The z component of the vector.
      Returns:
        Shortest Distance between the two vectors.

    - #### projectOnto

          public final Vector3D projectOnto(Vector3D p)

      Projects this Vector3D onto another Vector3D.
      Parameters:
        `p` - the other Vector3D
      Returns:
        this Vector3D, after projection onto p

    - #### dot

          public final float dot(Vector3D p)
                          throws java.lang.NullPointerException

      Calculates the dot product between this Vector3D and another - this.x*p.x + this.y*p.y + this.y*p.y
      Parameters:
        `p` - the other Vector3D
      Returns:
        the dot product; always >=0
      Throws:
        `java.lang.NullPointerException` - if p==null

    - #### length

          public final float length()

      Reports the length of this vector.
      Returns:
        Length of this vector.

    - #### length

          public final Vector3D length(float f)

      Reports the normalised length of this vector scaled by the given scale factor.
      Parameters:
        `f` - Scale factor.
      Returns:
        Normalised length.

    - #### lengthSquared

          public final float lengthSquared()

      Reports the squared length of this vector.
      Returns:
        Squared length of this vector.

    - #### clear

          public final void clear()

      Resets this vector back to (0,0,0).

    - #### toString

          public final java.lang.String toString()

      Provides a textual representation of this vector.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        Text representation of this vector.

    - #### cross

          public final Vector3D cross(Vector3D v)
                               throws java.lang.NullPointerException

      Creates a new Vector3D from this and the cross product with the given vector.
      Parameters:
        `v` - the other Vector3D in the cross-product.
      Returns:
        a new Vector3D, this x v.
      Throws:
        `java.lang.NullPointerException` - if v is null.

    - #### isZero

          public boolean isZero()

      Indicates whether or not this Vector3D is the zero vector
      Returns:
        true if all components are zero.

    - #### equals

          public boolean equals(java.lang.Object other)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Returns a unique hash code that represents the content of this vector. Two vectors with identical components will generate the same hash code, even if they are two separate objects. This is consistent with the behaviour of equals().
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          protected boolean equals(Vector3D other)

      Determines if the components of this vector match those of the given one.
      Parameters:
        `other` - the other Vector3D.
      Returns:
        true if all of the components are equal.