Package org.apache.commons.geometry.core
Interface Vector<V extends Vector<V>>
-
- Type Parameters:
V
- Vector implementation type
- All Superinterfaces:
Spatial
- All Known Implementing Classes:
EuclideanVector
,MultiDimensionalEuclideanVector
,Vector1D
,Vector1D.Unit
,Vector2D
,Vector2D.Unit
,Vector3D
,Vector3D.Unit
public interface Vector<V extends Vector<V>> extends Spatial
Interface representing a vector in a vector space or displacement vectors in an affine space.This interface uses self-referencing generic parameters to ensure that implementations are only used with instances of their own type. This removes the need for casting inside of methods in order to access implementation-specific data, such as coordinate values.
- See Also:
- Vector space, Affine space
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description V
add(double factor, V v)
Add a scaled vector to the instance.V
add(V v)
Add a vector to the instance.double
angle(V v)
Compute the angular separation between two vectors in radians.double
distance(V v)
Compute the distance between the instance and another vector.double
distanceSq(V v)
Compute the square of the distance between the instance and another vector.double
dot(V v)
Compute the dot-product of the instance and another vector.V
getZero()
Get the zero (null) vector of the space.V
multiply(double a)
Multiply the instance by a scalar.V
negate()
Get the negation of the instance.double
norm()
Get the L2 norm (commonly known as the Euclidean norm) for the vector.V
normalize()
Get a normalized vector aligned with the instance.V
normalizeOrNull()
Attempt to compute a normalized vector aligned with the instance, returning null if such a vector cannot be computed.double
normSq()
Get the square of the L2 norm (also known as the Euclidean norm) for the vector.V
subtract(double factor, V v)
Subtract a scaled vector from the instance.V
subtract(V v)
Subtract a vector from the instance.V
withNorm(double norm)
Returns a vector with the same direction but with the given norm.-
Methods inherited from interface org.apache.commons.geometry.core.Spatial
getDimension, isFinite, isInfinite, isNaN
-
-
-
-
Method Detail
-
getZero
V getZero()
Get the zero (null) vector of the space.- Returns:
- zero vector of the space
-
norm
double norm()
Get the L2 norm (commonly known as the Euclidean norm) for the vector. This corresponds to the common notion of vector magnitude or length and is defined as the square root of the sum of the squares of all vector components.- Returns:
- L2 norm for the vector
- See Also:
- L2 Norm
-
normSq
double normSq()
Get the square of the L2 norm (also known as the Euclidean norm) for the vector. This is equal to the sum of the squares of all vector components.- Returns:
- square of the L2 norm for the vector
- See Also:
norm()
-
withNorm
V withNorm(double norm)
Returns a vector with the same direction but with the given norm. This is equivalent to callingvec.normalize().scalarMultiply(mag)
but without the intermediate vector.- Parameters:
norm
- The vector norm- Returns:
- a vector with the same direction as the current instance but the given norm
-
add
V add(double factor, V v)
Add a scaled vector to the instance.- Parameters:
factor
- scale factor to apply to v before adding itv
- vector to add- Returns:
- a new vector
-
subtract
V subtract(V v)
Subtract a vector from the instance.- Parameters:
v
- vector to subtract- Returns:
- a new vector
-
subtract
V subtract(double factor, V v)
Subtract a scaled vector from the instance.- Parameters:
factor
- scale factor to apply to v before subtracting itv
- vector to subtract- Returns:
- a new vector
-
negate
V negate()
Get the negation of the instance.- Returns:
- a new vector which is the negation of the instance
-
normalize
V normalize()
Get a normalized vector aligned with the instance. The returned vector has a magnitude of 1.- Returns:
- normalized vector
- Throws:
java.lang.IllegalArgumentException
- if the norm is zero, NaN, or infinite- See Also:
normalizeOrNull()
-
normalizeOrNull
V normalizeOrNull()
Attempt to compute a normalized vector aligned with the instance, returning null if such a vector cannot be computed. This method is equivalent tonormalize()
but returns null instead of throwing an exception on failure.- Returns:
- normalized vector or null if such a vector cannot be computed, i.e. if the norm is zero, NaN, or infinite
- See Also:
normalize()
-
multiply
V multiply(double a)
Multiply the instance by a scalar.- Parameters:
a
- scalar- Returns:
- a new vector
-
distance
double distance(V v)
Compute the distance between the instance and another vector.- Parameters:
v
- second vector- Returns:
- the distance between the instance and v
-
distanceSq
double distanceSq(V v)
Compute the square of the distance between the instance and another vector.Calling this method is equivalent to calling:
q.subtract(p).getNormSq()
except that no intermediate vector is built- Parameters:
v
- second vector- Returns:
- the square of the distance between the instance and p
- See Also:
normSq()
-
dot
double dot(V v)
Compute the dot-product of the instance and another vector.- Parameters:
v
- second vector- Returns:
- the dot product (this · v)
-
angle
double angle(V v)
Compute the angular separation between two vectors in radians.- Parameters:
v
- other vector- Returns:
- angular separation between this instance and v in radians
- Throws:
java.lang.IllegalArgumentException
- if either vector has a zero, NaN, or infinite norm
-
-