com.kuka.math.geometry
Class Vector3D

java.lang.Object
  com.kuka.math.geometry.Vector3D

All Implemented Interfaces:

Serializable

public final class Vector3D
extends Object
implements Serializable

Immutable representation of a 3-element vector consisting of x, y and z elements. The class Vector represents a difference vector, which describes the displacement between two points. To quote Murray, R. et al — A mathematical Introduction to Robotic Manipulation, Section 3.1 the following propositions are hold:

1. Sum and difference of vectors are vectors
2. The sum of a vector and a point is a point
3. The difference between two points is a vector
4. The sum of two points is meaningless

Concerning transformations the following properties are enforced on vectors

• ITransformation.applyTo(Vector3D) results in a (displacement) vector represented in the new coordinate system. From numerical point of view the rotational part of the transformation is applied to the three components of the vector, but the translational part of the transformation will not be applied to the vector

The Robotics API always assumes the translation vector to be given in [mm].

To create a new Vector object use the static factory method of(double, double, double).

See Also:

Serialized Form

Field Summary

static Vector3D	UNIT_X Immutable Vector3D instance representing the X unit vector.
static Vector3D	UNIT_Y Immutable Vector3D instance representing the Y unit vector.
static Vector3D	UNIT_Z Immutable Vector3D instance representing the Z unit vector.
static Vector3D	ZERO Immutable Vector3D instance representing a zero vector.

Method Summary

Vector3D	add(Vector3D other) Adds the given vector to the values of this vector.
double	angleRad(Vector3D other) Calculates the smallest angle between this and the other vector.
Vector3D	crossProduct(Vector3D other) Returns the vector that is the cross product between this vector and the other vector.
double	dotProduct(Vector3D other) Returns the dot (inner/scalar) product between this vector and the other vector.
boolean	equals(Object obj) Compares the specified object for equality with this vector.
double	get(int index) Gets a value of the vector at the specified index, where 0 denotes the x, 1 the y and 2 the z element of the vector.
double	getX() Returns the x element of the vector.
double	getY() Returns the y element of the vector.
double	getZ() Returns the z element of the vector.
int	hashCode() Returns the hash code for this vector.
Vector3D	invert() Returns an inverted vector, i.e. a vector with element wise negated values.
double	length() Returns the length of the vector.
Vector3D	multiply(double factor) Returns a vector that has the values of this vector scaled by the given factor.
Vector3D	normalize() Returns a vector that points in the same direction as this vector, scaled to unit length (1).
static Vector3D	of(double x, double y, double z) Returns an immutable Vector3D instance constructed from its cartesian X, Y and Z elements.
Vector3D	subtract(Vector3D other) Subtracts the given vector from the values of this vector.
double[]	toArray() Converts the Vector into an array with 3 values.
String	toString() Returns the vector value formatted as a column vector in a way compatible with popular scientific numerical computing applications.
String	toString(NumberFormat fmt) Returns the vector value formatted as a column vector in a way similar to popular scientific numerical computing applications.
Vector3D	withX(double value) Returns a new instance (copy) of the vector, with the x element replaced by the new value.
Vector3D	withY(double value) Returns a new instance (copy) of the vector, with the y element replaced by the new value.
Vector3D	withZ(double value) Returns a new instance (copy) of the vector, with the z element replaced by the new value.

Methods inherited from class java.lang.Object

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

Field Detail

ZERO

public static final Vector3D ZERO

Immutable Vector3D instance representing a zero vector.

UNIT_X

public static final Vector3D UNIT_X

Immutable Vector3D instance representing the X unit vector.

UNIT_Y

public static final Vector3D UNIT_Y

Immutable Vector3D instance representing the Y unit vector.

UNIT_Z

public static final Vector3D UNIT_Z

Immutable Vector3D instance representing the Z unit vector.

Method Detail

of

public static Vector3D of(double x,
                          double y,
                          double z)

Returns an immutable Vector3D instance constructed from its cartesian X, Y and Z elements.

Parameters:

x - the cartesian X element of the vector

y - the cartesian Y element of the vector

z - the cartesian Z element of the vector

Returns:

an immutable Vector3D instance

getX

public double getX()

Returns the x element of the vector.

Returns:

The x element of the vector.

See Also:

getY(), getZ(), get(int)

getY

public double getY()

Returns the y element of the vector.

Returns:

The y element of the vector.

See Also:

getX(), getZ(), get(int)

getZ

public double getZ()

Returns the z element of the vector.

Returns:

The z element of the vector.

See Also:

getX(), getY(), get(int)

get

public double get(int index)

Gets a value of the vector at the specified index, where 0 denotes the x, 1 the y and 2 the z element of the vector.

Parameters:

index - The index of the element, must be between 0 and 2.

Returns:

The value at the specified index.

Throws:

IndexOutOfBoundsException - illegal index

See Also:

getX(), getY(), getZ()

withX

public Vector3D withX(double value)

Returns a new instance (copy) of the vector, with the x element replaced by the new value.

Parameters:

value - The x element of the vector.

Returns:

a new instance of the class

withY

public Vector3D withY(double value)

Returns a new instance (copy) of the vector, with the y element replaced by the new value.

Parameters:

value - The y element of the vector.

Returns:

a new instance of the class

withZ

public Vector3D withZ(double value)

Returns a new instance (copy) of the vector, with the z element replaced by the new value.

Parameters:

value - The z element of the vector.

Returns:

a new instance of the class

invert

public Vector3D invert()

Returns an inverted vector, i.e. a vector with element wise negated values.

Returns:

The inverted vector.

length

public double length()

Returns the length of the vector.

Returns:

the length of the vector.

normalize

public Vector3D normalize()

Returns a vector that points in the same direction as this vector, scaled to unit length (1).

Returns:

the resulting vector.

dotProduct

public double dotProduct(Vector3D other)

Returns the dot (inner/scalar) product between this vector and the other vector.

Parameters:

other - another vector.

Returns:

the dot (inner/scalar) product.

crossProduct

public Vector3D crossProduct(Vector3D other)

Returns the vector that is the cross product between this vector and the other vector.

Parameters:

other - another vector.

Returns:

the cross product.

angleRad

public double angleRad(Vector3D other)

Calculates the smallest angle between this and the other vector. Angle is in rad.

Parameters:

other - a vector

Returns:

The angle between this and the other vector in radian (between 0 and PI).

Throws:

ArithmeticException - if this or the other vector has a approximate zero length

multiply

public Vector3D multiply(double factor)

Returns a vector that has the values of this vector scaled by the given factor.

Parameters:

factor - The factor with which this vector should be multiplied.

Returns:

The resulting vector.

Throws:

ArithmeticException - factor is infinite or NaN

add

public Vector3D add(Vector3D other)

Adds the given vector to the values of this vector.

Parameters:

other - The vector which will be added to the values of this vector.

Returns:

The resulting vector.

subtract

public Vector3D subtract(Vector3D other)

Subtracts the given vector from the values of this vector.

Parameters:

other - The vector which will be subtracted from the values of this vector.

Returns:

The resulting vector.

toString

public String toString()

Returns the vector value formatted as a column vector in a way compatible with popular scientific numerical computing applications. The numerical values will be printed with the default format as returned by MathUtils.getDefaultNumberFormat().

The following string can be regarded as typical:

[1.234; 300.0; -20.2]

Overrides:

toString in class Object

Returns:

a textual representation of the vector

toString

public String toString(NumberFormat fmt)

Returns the vector value formatted as a column vector in a way similar to popular scientific numerical computing applications. The numerical values will be printed using the NumberFormat.format(double) method of the given formatter.

Example: The following code snippet, used on a given Vector3D vec

 NumberFormat fmt = NumberFormat.getNumberInstance(Locale.US);
 fmt.setMinimumFractionDigits(1);
 fmt.setMaximumFractionDigits(3);
 System.out.println(vec.toString(fmt));

might give the following output:

 [-1.234; 1.414; 20.0]

Parameters:

fmt - the NumberFormat used to format the number values

Returns:

a textual representation of the vector

toArray

public double[] toArray()

Converts the Vector into an array with 3 values.

Returns:

array representation of the vector.

hashCode

public int hashCode()

Returns the hash code for this vector. The hash code is computed by a combination of all the data elements defined by this interface.

Overrides:

hashCode in class Object

Returns:

hash code for this vector.

equals

public boolean equals(Object obj)

Compares the specified object for equality with this vector. Vectors are equal if all data elements returned by this interface are equal.

Overrides:

equals in class Object

Parameters:

obj - Object to be compared with this vector.

Returns:

true if the object is equal to this vector.