Package civitas.celestis.math.vector

Class Vector3

java.lang.Object
civitas.celestis.util.tuple.Double3
civitas.celestis.math.vector.Vector3
All Implemented Interfaces:
Vector<Vector3>, BaseTuple<Double>, DoubleTuple, Serializable
public class Vector3 extends Double3 implements Vector<Vector3>
An immutable three-dimensional vector which uses the type double.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Vector3
    NEGATIVE_X
    The negative X unit vector.
    static final Vector3
    NEGATIVE_Y
    The negative Y unit vector.
    static final Vector3
    NEGATIVE_Z
    The negative Z unit vector.
    static final Vector3
    POSITIVE_X
    The positive X unit vector.
    static final Vector3
    POSITIVE_Y
    The positive Y unit vector.
    static final Vector3
    POSITIVE_Z
    The positive Z unit vector.
    static final Vector3
    ZERO
    A vector of no direction or magnitude.

    Fields inherited from class civitas.celestis.util.tuple.Double3

    x, y, z

  • Constructor Summary

    Constructors
    Constructor
    Description
    Vector3(double[] components)
    Creates a new vector.
    Vector3(double x, double y, double z)
    Creates a new vector.
    Vector3(DoubleTuple t)
    Creates a new vector.

  • Method Summary

    Modifier and Type
    Method
    Description
    Vector3
    add(double s)
    Adds a scalar to this vector component-wise, then returns the resulting vector.
    Vector3
    add(Vector3 v)
    Adds another vector to this vector, then returns the resulting vector.
    Vector3
    clamp(Vector3 min, Vector3 max)
    Between this vector and the provided boundary vectors min and max, this returns a new vector whose components are clamped to respect the range of [min, max].
    Vector3
    cross(Vector3 v)
    Returns the cross product between this vector and the provided vector v.
    double
    distance(Vector3 v)
    Returns the Euclidean distance between this vector and the provided vector v.
    double
    distance2(Vector3 v)
    Returns the squared Euclidean distance between this vector and the provided vector v.
    double
    distanceManhattan(Vector3 v)
    Returns the Manhattan distance between this vector and the provided vector v.
    Vector3
    divide(double s)
    Divides this vector by a scalar component-wise, then returns the resulting vector.
    double
    dot(Vector3 v)
    Returns the dot product between this vector and the provided vector v.
    boolean
    equals(Vector3 v)
    Checks for equality between this vector and the provided vector v.
    Vector3
    map(DoubleUnaryOperator f)
    Applies the provided mapper function f to each component of this tuple, then returns a new tuple containing the return values of the function f.
    Vector3
    max(Vector3 v)
    Between this vector and the provided boundary vector v, this takes the maximum of each corresponding pair of components, then returns a new vector whose components are populated from that of the maximum values between each pair of components.
    Vector3
    merge(Vector3 v, BinaryOperator<Double> f)
    Between this vector and the provided vector v, this applies the merger function f to each corresponding pair of components, then returns a new vector whose components are populated from the return values of the function f.
    Vector3
    min(Vector3 v)
    Between this vector and the provided boundary vector v, this takes the minimum of each corresponding pair of components, then returns a new vector whose components are populated from that of the minimum values between each pair of components.
    Vector3
    multiply(double s)
    Multiplies this vector by a scalar component-wise, then returns the resulting vector.
    Vector3
    negate()
    Negates all components of this vector, then returns the resulting vector.
    double
    norm()
    Returns the Euclidean norm (the magnitude) of this vector.
    double
    norm2()
    Returns the squared Euclidean norm (the squared magnitude) of this vector.
    Vector3
    normalize()
    Normalizes this vector to have a Euclidean norm (magnitude) of 1.
    Vector3
    normalizeOrDefault(Vector3 v)
    Normalizes this vector to have a Euclidean norm (magnitude) of 1.
    Vector3
    normalizeOrZero()
    Normalizes this vector ot have a Euclidean norm (magnitude) of 1.
    double
    normManhattan()
    Returns the Manhattan norm of this vector.
    Quaternion
    quaternion()
    Converts this vector into a pure quaternion.
    Vector3
    rotate(Quaternion q)
    Rotates this vector by the provided rotation quaternion q.
    Vector3
    subtract(double s)
    Subtracts this vector by a scalar component-wise, then returns the resulting vector.
    Vector3
    subtract(Vector3 v)
    Subtracts another vector from this vector, then returns the resulting vector.

    Methods inherited from class civitas.celestis.util.tuple.Double3

    array, boxed, contains, containsAll, equals, get, hashCode, isFinite, isInfinite, isNaN, isZero, list, mapToObj, size, stream, toString, x, y, z

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface civitas.celestis.util.tuple.DoubleTuple

    array, boxed, contains, containsAll, doubleArray, equals, get, isFinite, isInfinite, isNaN, isZero, list, mapToObj, size, stream, toString

  • Field Details

    • ZERO

      public static final Vector3 ZERO
      A vector of no direction or magnitude. Represents origin.

    • POSITIVE_X

      public static final Vector3 POSITIVE_X
      The positive X unit vector.

    • POSITIVE_Y

      public static final Vector3 POSITIVE_Y
      The positive Y unit vector.

    • POSITIVE_Z

      public static final Vector3 POSITIVE_Z
      The positive Z unit vector.

    • NEGATIVE_X

      public static final Vector3 NEGATIVE_X
      The negative X unit vector.

    • NEGATIVE_Y

      public static final Vector3 NEGATIVE_Y
      The negative Y unit vector.

    • NEGATIVE_Z

      public static final Vector3 NEGATIVE_Z
      The negative Z unit vector.

  • Constructor Details

    • Vector3

      public Vector3(double x, double y, double z)
      Creates a new vector.
      Parameters:
      x - The X component of this vector
      y - The Y component of this vector
      z - The Z component of this vector

    • Vector3

      public Vector3(@Nonnull double[] components)
      Creates a new vector.
      Parameters:
      components - An array containing the components of this vector in XYZ order
      Throws:
      IllegalArgumentException - When the provided array's length is not 3

    • Vector3

      public Vector3(@Nonnull DoubleTuple t)
      Creates a new vector.
      Parameters:
      t - The tuple of which to copy component values from
      Throws:
      IllegalArgumentException - When the provided tuple t's size is not 3

  • Method Details

    • norm

      public double norm()
      Returns the Euclidean norm (the magnitude) of this vector.
      Specified by:
      norm in interface Vector<Vector3>
      Returns:
      The Euclidean norm of this vector

    • norm2

      public double norm2()
      Returns the squared Euclidean norm (the squared magnitude) of this vector.
      Specified by:
      norm2 in interface Vector<Vector3>
      Returns:
      The squared Euclidean norm of this vector

    • normManhattan

      public double normManhattan()
      Returns the Manhattan norm of this vector.
      Specified by:
      normManhattan in interface Vector<Vector3>
      Returns:
      The Manhattan norm of this vector

    • add

      @Nonnull public Vector3 add(double s)
      Adds a scalar to this vector component-wise, then returns the resulting vector.
      Specified by:
      add in interface Vector<Vector3>
      Parameters:
      s - The scalar of which to add to each component of this vector
      Returns:
      The resulting vector

    • subtract

      @Nonnull public Vector3 subtract(double s)
      Subtracts this vector by a scalar component-wise, then returns the resulting vector.
      Specified by:
      subtract in interface Vector<Vector3>
      Parameters:
      s - The scalar of which to subtract from each component of this vector
      Returns:
      The resulting vector

    • multiply

      @Nonnull public Vector3 multiply(double s)
      Multiplies this vector by a scalar component-wise, then returns the resulting vector.
      Specified by:
      multiply in interface Vector<Vector3>
      Parameters:
      s - The scalar of which to multiply each component of this vector by
      Returns:
      The resulting vector

    • divide

      @Nonnull public Vector3 divide(double s) throws ArithmeticException
      Divides this vector by a scalar component-wise, then returns the resulting vector.
      Specified by:
      divide in interface Vector<Vector3>
      Parameters:
      s - The scalar of which to divide each component of this vector by
      Returns:
      The resulting vector
      Throws:
      ArithmeticException - When the denominator s is zero

    • add

      @Nonnull public Vector3 add(@Nonnull Vector3 v)
      Adds another vector to this vector, then returns the resulting vector.
      Specified by:
      add in interface Vector<Vector3>
      Parameters:
      v - The vector of which to add to this vector
      Returns:
      The resulting vector

    • subtract

      @Nonnull public Vector3 subtract(@Nonnull Vector3 v)
      Subtracts another vector from this vector, then returns the resulting vector.
      Specified by:
      subtract in interface Vector<Vector3>
      Parameters:
      v - The vector of which to subtract from this vector
      Returns:
      The resulting vector

    • cross

      @Nonnull public Vector3 cross(@Nonnull Vector3 v)
      Returns the cross product between this vector and the provided vector v.
      Parameters:
      v - The vector of which to get the cross product between
      Returns:
      The cross product between the two vectors

    • dot

      public double dot(@Nonnull Vector3 v)
      Returns the dot product between this vector and the provided vector v.
      Specified by:
      dot in interface Vector<Vector3>
      Parameters:
      v - The vector of which to get the dot product between
      Returns:
      The dot product between the two vectors

    • normalize

      @Nonnull public Vector3 normalize() throws ArithmeticException
      Normalizes this vector to have a Euclidean norm (magnitude) of 1.
      Specified by:
      normalize in interface Vector<Vector3>
      Returns:
      The normalized vector of this vector
      Throws:
      ArithmeticException - When the Euclidean norm of this vector is zero

    • normalizeOrZero

      @Nonnull public Vector3 normalizeOrZero()
      Normalizes this vector ot have a Euclidean norm (magnitude) of 1. If this vector's Euclidean norm is zero, this will return itself. (which is guaranteed to be a vector where all components are zero, as only zero vectors have a Euclidean norm of zero)
      Specified by:
      normalizeOrZero in interface Vector<Vector3>
      Returns:
      The normalized vector of this vector if successful, zero otherwise

    • normalizeOrDefault

      @Nonnull public Vector3 normalizeOrDefault(@Nonnull Vector3 v)
      Normalizes this vector to have a Euclidean norm (magnitude) of 1. If this vector's Euclidean norm is zero, this will return the provided fallback value v.
      Specified by:
      normalizeOrDefault in interface Vector<Vector3>
      Parameters:
      v - The value of which to return in case of division by zero
      Returns:
      The normalized vector of this vector if successful, the fallback value v otherwise

    • negate

      @Nonnull public Vector3 negate()
      Negates all components of this vector, then returns the resulting vector.
      Specified by:
      negate in interface Vector<Vector3>
      Returns:
      The negation of this vector

    • min

      @Nonnull public Vector3 min(@Nonnull Vector3 v)
      Between this vector and the provided boundary vector v, this takes the minimum of each corresponding pair of components, then returns a new vector whose components are populated from that of the minimum values between each pair of components.
      Specified by:
      min in interface Vector<Vector3>
      Parameters:
      v - The boundary vector of which to compare to
      Returns:
      The minimum vector of the two vectors

    • max

      @Nonnull public Vector3 max(@Nonnull Vector3 v)
      Between this vector and the provided boundary vector v, this takes the maximum of each corresponding pair of components, then returns a new vector whose components are populated from that of the maximum values between each pair of components.
      Specified by:
      max in interface Vector<Vector3>
      Parameters:
      v - The boundary vector of which to compare to
      Returns:
      The maximum vector of the two vectors

    • clamp

      @Nonnull public Vector3 clamp(@Nonnull Vector3 min, @Nonnull Vector3 max)
      Between this vector and the provided boundary vectors min and max, this returns a new vector whose components are clamped to respect the range of [min, max]. This is the equivalent of clamping each component to the corresponding pair of minimum and maximum values.
      Specified by:
      clamp in interface Vector<Vector3>
      Parameters:
      min - The minimum boundary vector to compare to
      max - The maximum boundary vector to compare to
      Returns:
      The clamped vector which respects the boundaries of [min, max]

    • distance

      public double distance(@Nonnull Vector3 v)
      Returns the Euclidean distance between this vector and the provided vector v.
      Specified by:
      distance in interface Vector<Vector3>
      Parameters:
      v - The vector of which get the Euclidean distance between
      Returns:
      The Euclidean distance between the two vectors

    • distance2

      public double distance2(@Nonnull Vector3 v)
      Returns the squared Euclidean distance between this vector and the provided vector v.
      Specified by:
      distance2 in interface Vector<Vector3>
      Parameters:
      v - The vector of which to get the squared Euclidean distance between
      Returns:
      The squared Euclidean distance between the two vectors

    • distanceManhattan

      public double distanceManhattan(@Nonnull Vector3 v)
      Returns the Manhattan distance between this vector and the provided vector v.
      Specified by:
      distanceManhattan in interface Vector<Vector3>
      Parameters:
      v - The vector of which to get the Manhattan distance between
      Returns:
      The Manhattan distance between the two vectors

    • map

      @Nonnull public Vector3 map(@Nonnull DoubleUnaryOperator f)
      Applies the provided mapper function f to each component of this tuple, then returns a new tuple containing the return values of the function f.
      Specified by:
      map in interface DoubleTuple
      Specified by:
      map in interface Vector<Vector3>
      Overrides:
      map in class Double3
      Parameters:
      f - The function of which to apply to each component of this tuple
      Returns:
      The resulting tuple

    • merge

      @Nonnull public Vector3 merge(@Nonnull Vector3 v, @Nonnull BinaryOperator<Double> f)
      Between this vector and the provided vector v, this applies the merger function f to each corresponding pair of components, then returns a new vector whose components are populated from the return values of the function f.
      Specified by:
      merge in interface Vector<Vector3>
      Parameters:
      v - The vector of which to merge this vector with
      f - The merger function to handle the merging of the two vectors
      Returns:
      The resulting vector

    • quaternion

      @Nonnull public Quaternion quaternion()
      Converts this vector into a pure quaternion. (a quaternion whose scalar part is 0, and the vector part is populated from this vector's components)
      Returns:
      A pure quaternion constructed from this vector

    • rotate

      @Nonnull public Vector3 rotate(@Nonnull Quaternion q)
      Rotates this vector by the provided rotation quaternion q.
      Parameters:
      q - The rotation quaternion of which to apply to this vector
      Returns:
      The rotated vector

    • equals

      public boolean equals(@Nullable Vector3 v)
      Checks for equality between this vector and the provided vector v.
      Specified by:
      equals in interface Vector<Vector3>
      Parameters:
      v - The vector to compare to
      Returns:
      true if the component values are equal