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:
  • Method Summary

    Modifier and Type
    Method
    Description
    add(double factor, V v)
    Add a scaled vector to the instance.
    add(V v)
    Add a vector to the instance.
    double
    angle(V v)
    Compute the angular separation between two vectors in radians.
    double
    Compute the distance between the instance and another vector.
    double
    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.
    Get the zero (null) vector of the space.
    multiply(double a)
    Multiply the instance by a scalar.
    Get the negation of the instance.
    double
    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
    Get the square of the L2 norm (also known as the Euclidean norm) for the vector.
    subtract(double factor, V v)
    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

      V withNorm(double norm)
      Returns a vector with the same direction but with the given norm. This is equivalent to calling vec.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(V v)
      Add a vector to the instance.
      Parameters:
      v - vector to add
      Returns:
      a new vector
    • add

      V add(double factor, V v)
      Add a scaled vector to the instance.
      Parameters:
      factor - scale factor to apply to v before adding it
      v - 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 it
      v - 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 to normalize() 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

      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:
    • 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:
      IllegalArgumentException - if either vector has a zero, NaN, or infinite norm