org.gicentre.utils.network.traer.physics
Class Vector3D

java.lang.Object
  extended by 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.

Author:
Jeffrey Traer Bernstein, Carl Pearson and minor modifications by Jo Wood.

Constructor Summary
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
 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

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.


giCentre Utilities V.3.3, API documentation generated 6th April, 2013