org.apache.commons.geometry.euclidean

Class EuclideanVector<V extends EuclideanVector<V>>

java.lang.Object

org.apache.commons.geometry.euclidean.EuclideanVector<V>

Type Parameters:

V - Vector implementation type

All Implemented Interfaces:

Point<V>, Spatial, Vector<V>

Direct Known Subclasses:

MultiDimensionalEuclideanVector, Vector1D

public abstract class EuclideanVector<V extends EuclideanVector<V>>
extends Object
implements Vector<V>, Point<V>

Abstract base class for Euclidean vectors and points. See here for a discussion of the combination of point and vector functionality into a single class hierarchy.

Constructor Summary

Constructors

Constructor and Description
EuclideanVector()

Method Summary

Modifier and Type	Method and Description
abstract V	directionTo(V v) Return the unit vector representing the direction of displacement from this vector to the given vector.
abstract boolean	eq(V v, DoublePrecisionContext precision) Return true if the current instance and given vector are considered equal as evaluated by the given precision context.
protected double	getCheckedNorm() Return the vector norm value, throwing an IllegalArgumentException if the value is not real (ie, NaN or infinite) or zero.
boolean	isZero(DoublePrecisionContext precision) Return true if the current instance is considered equal to the zero vector as evaluated by the given precision context.
abstract V	lerp(V v, double t) Get a vector constructed by linearly interpolating between this vector and the given vector.
abstract V	vectorTo(V v) Return the vector representing the displacement from this vector to the given vector.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.commons.geometry.core.Vector

add, add, angle, distance, distanceSq, dot, getZero, multiply, negate, norm, normalize, normSq, subtract, subtract, withNorm

Methods inherited from interface org.apache.commons.geometry.core.Point

distance

Methods inherited from interface org.apache.commons.geometry.core.Spatial

getDimension, isFinite, isInfinite, isNaN

Constructor Detail

EuclideanVector

public EuclideanVector()

Method Detail

vectorTo

public abstract V vectorTo(V v)

Return the vector representing the displacement from this vector to the given vector. This is exactly equivalent to v.subtract(thisVector) but with a method name that is much easier to visualize.

Parameters:

v - the vector that the returned vector will be directed toward

Returns:

vector representing the displacement from this vector to the given vector

directionTo

public abstract V directionTo(V v)

Return the unit vector representing the direction of displacement from this vector to the given vector. This is exactly equivalent to v.subtract(thisVector).normalize() but without the intermediate vector instance.

Parameters:

v - the vector that the returned vector will be directed toward

Returns:

unit vector representing the direction of displacement from this vector to the given vector

Throws:

IllegalArgumentException - if the norm of the vector pointing from this instance to v is zero, NaN, or infinite

lerp

public abstract V lerp(V v,
                       double t)

Get a vector constructed by linearly interpolating between this vector and the given vector. The vector coordinates are generated by the equation V = (1 - t)*A + t*B, where A is the current vector and B is the given vector. This means that if t = 0, a vector equal to the current vector will be returned. If t = 1, a vector equal to the argument will be returned. The t parameter is not constrained to the range [0, 1], meaning that linear extrapolation can also be performed with this method.

Parameters:

v - other vector

t - interpolation parameter

Returns:

interpolated or extrapolated vector

eq

public abstract boolean eq(V v,
                           DoublePrecisionContext precision)

Return true if the current instance and given vector are considered equal as evaluated by the given precision context.

Equality is determined by comparing each pair of components in turn from the two vectors. If all components evaluate as equal, then the vectors are considered equal. If any are not equal, then the vectors are not considered equal. Note that this approach means that the calculated distance between two "equal" vectors may be as much as √(n * eps2), where n is the number of components in the vector and eps is the maximum epsilon value allowed by the precision context.

Parameters:

v - vector to check for equality

precision - precision context used to determine floating point equality

Returns:

true if the current instance is considered equal to the given vector when using the given precision context; otherwise false

isZero

public boolean isZero(DoublePrecisionContext precision)

Return true if the current instance is considered equal to the zero vector as evaluated by the given precision context. This is a convenience method equivalent to vec.equals(vec.getZero(), precision).

Parameters:

precision - precision context used to determine floating point equality

Returns:

true if the current instance is considered equal to the zero vector when using the given precision context; otherwise false

See Also:

eq(EuclideanVector, DoublePrecisionContext)

getCheckedNorm

protected double getCheckedNorm()

Return the vector norm value, throwing an IllegalArgumentException if the value is not real (ie, NaN or infinite) or zero.

Returns:

the vector norm value, guaranteed to be real and non-zero

Throws:

IllegalArgumentException - if the vector norm is zero, NaN, or infinite