com.kuka.roboticsAPI.geometricModel.math
Class Vector

java.lang.Object
  com.kuka.roboticsAPI.geometricModel.math.Vector

All Implemented Interfaces:

Serializable

public final class Vector
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(Vector) 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 Vector	UNIT_X Immutable Vector instance representing the X unit vector.
static Vector	UNIT_Y Immutable Vector instance representing the Y unit vector.
static Vector	UNIT_Z Immutable Vector instance representing the Z unit vector.
static Vector	ZERO Immutable Vector instance representing a zero vector.

Method Summary

Vector	add(Vector other) Adds the given vector to the values of this vector.
double	angleRad(Vector other) Calculates the smallest angle between this and the other vector.
Vector	crossProduct(Vector other) Returns the vector that is the cross product between this vector and the other vector.
double	dotProduct(Vector 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.
Vector	invert() Returns an inverted vector, i.e. a vector with element wise negated values.
double	length() Returns the length of the vector.
Vector	multiply(double factor) Returns a vector that has the values of this vector scaled by the given factor.
Vector	normalize() Returns a vector that points in the same direction as this vector, scaled to unit length (1).
static Vector	of(double x, double y, double z) Returns an immutable Vector instance constructed from its cartesian X, Y and Z elements.
Vector	subtract(Vector 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 a textual description of the vector.
Vector	withX(double value) Returns a new instance (copy) of the vector, with the x element replaced by the new value.
Vector	withY(double value) Returns a new instance (copy) of the vector, with the y element replaced by the new value.
Vector	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 Vector ZERO

Immutable Vector instance representing a zero vector.

UNIT_X

public static final Vector UNIT_X

Immutable Vector instance representing the X unit vector.

UNIT_Y

public static final Vector UNIT_Y

Immutable Vector instance representing the Y unit vector.

UNIT_Z

public static final Vector UNIT_Z

Immutable Vector instance representing the Z unit vector.

Method Detail

of

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

Returns an immutable Vector 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 Vector 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 Vector 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 Vector 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 Vector 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 Vector 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 Vector 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(Vector 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 Vector crossProduct(Vector 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(Vector 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 Vector 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 Vector add(Vector 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 Vector subtract(Vector 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 a textual description of the vector. The representation is subject to change. The following string can be regarded as typical:

"[1.23, 300.00, -20.20]"

Overrides:

toString in class Object

Returns:

a brief description 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.