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
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:
-
Method Summary
Modifier and TypeMethodDescriptionAdd a scaled vector to the instance.Add a vector to the instance.double
Compute the angular separation between two vectors in radians.double
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
Compute the dot-product of the instance and another vector.getZero()
Get the zero (null) vector of the space.multiply
(double a) Multiply the instance by a scalar.negate()
Get the negation of the instance.double
norm()
Get the L2 norm (commonly known as the Euclidean norm) for the vector.Get a normalized vector aligned with the instance.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.Subtract a scaled vector from the instance.Subtract a vector from the instance.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 Details
-
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:
-
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:
-
withNorm
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
Add a vector to the instance.- Parameters:
v
- vector to add- Returns:
- a new vector
-
add
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
Subtract a vector from the instance.- Parameters:
v
- vector to subtract- Returns:
- a new vector
-
subtract
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:
IllegalArgumentException
- if the norm is zero, NaN, or infinite- See Also:
-
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:
-
multiply
Multiply the instance by a scalar.- Parameters:
a
- scalar- Returns:
- a new vector
-
distance
Compute the distance between the instance and another vector.- Parameters:
v
- second vector- Returns:
- the distance between the instance and v
-
distanceSq
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:
-
dot
Compute the dot-product of the instance and another vector.- Parameters:
v
- second vector- Returns:
- the dot product (this · v)
-
angle
Compute the angular separation between two vectors in radians.- Parameters:
v
- other vector- Returns:
- angular separation between this instance and v in radians
- Throws:
IllegalArgumentException
- if either vector has a zero, NaN, or infinite norm
-