Class Vector3D

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Vector3D.Sum
      Class used to create high-accuracy sums of vectors.
      static class  Vector3D.Unit
      Represents unit vectors.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Comparator<Vector3D> COORDINATE_ASCENDING_ORDER
      Comparator that sorts vectors in component-wise ascending order.
      static Vector3D NaN
      A vector with all coordinates set to NaN.
      static Vector3D NEGATIVE_INFINITY
      A vector with all coordinates set to negative infinity.
      static Vector3D POSITIVE_INFINITY
      A vector with all coordinates set to positive infinity.
      private double x
      X coordinate value (abscissa).
      private double y
      Y coordinate value (ordinate).
      private double z
      Z coordinate value (height).
      static Vector3D ZERO
      Zero (null) vector (coordinates: 0, 0, 0).
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Vector3D​(double x, double y, double z)
      Simple constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Vector3D add​(double factor, Vector3D v)
      Add a scaled vector to the instance.
      Vector3D add​(Vector3D v)
      Add a vector to the instance.
      double angle​(Vector3D v)
      Compute the angular separation between two vectors in radians.
      static Vector3D centroid​(java.lang.Iterable<Vector3D> pts)
      Compute the centroid of the given points.
      static Vector3D centroid​(Vector3D first, Vector3D... more)
      Compute the centroid of the given points.
      private static Vector3D computeCentroid​(Vector3D first, java.util.Iterator<? extends Vector3D> more)
      Internal method for computing the centroid of a set of points.
      private static Vector3D computeMax​(Vector3D first, java.util.Iterator<? extends Vector3D> more)
      Internal method for computing a max vector.
      private static Vector3D computeMin​(Vector3D first, java.util.Iterator<? extends Vector3D> more)
      Internal method for computing a min vector.
      Vector3D cross​(Vector3D v)
      Compute the cross-product of the instance with another vector.
      Vector3D.Unit directionTo​(Vector3D v)
      Return the unit vector representing the direction of displacement from this vector to the given vector.
      double distance​(Vector3D v)
      Compute the distance between the instance and another vector.
      double distanceSq​(Vector3D v)
      Compute the square of the distance between the instance and another vector.
      double dot​(Vector3D v)
      Compute the dot-product of the instance and another vector.
      boolean eq​(Vector3D vec, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Return true if the current instance and given vector are considered equal as evaluated by the given precision context.
      boolean equals​(java.lang.Object other)
      d Test for the equality of two vector instances.
      private <V extends Vector3D>
      V
      getComponent​(Vector3D base, boolean reject, DoubleFunction3N<V> factory)
      Returns a component of the current instance relative to the given base vector.
      int getDimension()
      Returns the number of dimensions in the space that this element belongs to.
      double getX()
      Return the x coordinate value (abscissa) of the instance.
      double getY()
      Return the y coordinate value (ordinate) of the instance.
      double getZ()
      Returns the z coordinate value (height) of the instance.
      Vector3D getZero()
      Get the zero (null) vector of the space.
      int hashCode()
      Get a hashCode for the vector.
      boolean isFinite()
      Returns true if all values in this element are finite, meaning they are not NaN or infinite.
      boolean isInfinite()
      Returns true if any value in this element is infinite and none are NaN; otherwise, returns false.
      boolean isNaN()
      Returns true if any value in this element is NaN; otherwise returns false.
      Vector3D lerp​(Vector3D p, double t)
      Get a vector constructed by linearly interpolating between this vector and the given vector.
      static Vector3D max​(java.lang.Iterable<Vector3D> vecs)
      Return a vector containing the maximum component values from all input vectors.
      static Vector3D max​(Vector3D first, Vector3D... more)
      Return a vector containing the maximum component values from all input vectors.
      static Vector3D min​(java.lang.Iterable<Vector3D> vecs)
      Return a vector containing the minimum component values from all input vectors.
      static Vector3D min​(Vector3D first, Vector3D... more)
      Return a vector containing the minimum component values from all input vectors.
      Vector3D multiply​(double a)
      Multiply the instance by a scalar.
      Vector3D negate()
      Get the negation of the instance.
      double norm()
      Get the L2 norm (commonly known as the Euclidean norm) for the vector.
      Vector3D.Unit normalize()
      Get a normalized vector aligned with the instance.
      Vector3D.Unit 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.
      static Vector3D of​(double[] v)
      Creates a vector from the coordinates in the given 3-element array.
      static Vector3D of​(double x, double y, double z)
      Returns a vector with the given coordinate values.
      Vector3D.Unit orthogonal()
      Get a unit vector orthogonal to the instance.
      Vector3D.Unit orthogonal​(Vector3D dir)
      Get a unit vector orthogonal to the current vector and pointing in the direction of dir.
      static Vector3D parse​(java.lang.String str)
      Parses the given string and returns a new vector instance.
      Vector3D project​(Vector3D base)
      Get the projection of the instance onto the given base vector.
      Vector3D reject​(Vector3D base)
      Get the rejection of the instance from the given base vector.
      Vector3D subtract​(double factor, Vector3D v)
      Subtract a scaled vector from the instance.
      Vector3D subtract​(Vector3D v)
      Subtract a vector from the instance.
      double[] toArray()
      Get the coordinates for this instance as a dimension 3 array.
      java.lang.String toString()
      Vector3D transform​(java.util.function.UnaryOperator<Vector3D> fn)
      Convenience method to apply a function to this vector.
      Vector3D vectorTo​(Vector3D v)
      Return the vector representing the displacement from this vector to the given vector.
      Vector3D withNorm​(double magnitude)
      Returns a vector with the same direction but with the given norm.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • ZERO

        public static final Vector3D ZERO
        Zero (null) vector (coordinates: 0, 0, 0).
      • NaN

        public static final Vector3D NaN
        A vector with all coordinates set to NaN.
      • POSITIVE_INFINITY

        public static final Vector3D POSITIVE_INFINITY
        A vector with all coordinates set to positive infinity.
      • NEGATIVE_INFINITY

        public static final Vector3D NEGATIVE_INFINITY
        A vector with all coordinates set to negative infinity.
      • COORDINATE_ASCENDING_ORDER

        public static final java.util.Comparator<Vector3D> COORDINATE_ASCENDING_ORDER
        Comparator that sorts vectors in component-wise ascending order. Vectors are only considered equal if their coordinates match exactly. Null arguments are evaluated as being greater than non-null arguments.
      • x

        private final double x
        X coordinate value (abscissa).
      • y

        private final double y
        Y coordinate value (ordinate).
      • z

        private final double z
        Z coordinate value (height).
    • Constructor Detail

      • Vector3D

        private Vector3D​(double x,
                         double y,
                         double z)
        Simple constructor. Build a vector from its coordinates
        Parameters:
        x - x coordinate value
        y - y coordinate value
        z - z coordinate value
    • Method Detail

      • getX

        public double getX()
        Return the x coordinate value (abscissa) of the instance.
        Returns:
        the x coordinate value
      • getY

        public double getY()
        Return the y coordinate value (ordinate) of the instance.
        Returns:
        the y coordinate value
      • getZ

        public double getZ()
        Returns the z coordinate value (height) of the instance.
        Returns:
        the z coordinate value
      • toArray

        public double[] toArray()
        Get the coordinates for this instance as a dimension 3 array.
        Returns:
        the coordinates for this instance
      • getDimension

        public int getDimension()
        Returns the number of dimensions in the space that this element belongs to.
        Returns:
        the number of dimensions in the element's space
      • isNaN

        public boolean isNaN()
        Returns true if any value in this element is NaN; otherwise returns false.
        Returns:
        true if any value in this element is NaN
      • isInfinite

        public boolean isInfinite()
        Returns true if any value in this element is infinite and none are NaN; otherwise, returns false.
        Returns:
        true if any value in this element is infinite and none are NaN
      • isFinite

        public boolean isFinite()
        Returns true if all values in this element are finite, meaning they are not NaN or infinite.
        Returns:
        true if all values in this element are finite
      • getZero

        public Vector3D getZero()
        Get the zero (null) vector of the space.
        Returns:
        zero vector of the space
      • vectorTo

        public Vector3D vectorTo​(Vector3D 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.
        Specified by:
        vectorTo in class EuclideanVector<Vector3D>
        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 Vector3D.Unit directionTo​(Vector3D 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.
        Specified by:
        directionTo in class EuclideanVector<Vector3D>
        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
      • lerp

        public Vector3D lerp​(Vector3D p,
                             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.
        Specified by:
        lerp in class EuclideanVector<Vector3D>
        Parameters:
        p - other vector
        t - interpolation parameter
        Returns:
        interpolated or extrapolated vector
      • norm

        public 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

        public 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:
        Vector.norm()
      • withNorm

        public Vector3D withNorm​(double magnitude)
        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:
        magnitude - The vector norm
        Returns:
        a vector with the same direction as the current instance but the given norm
      • add

        public Vector3D add​(Vector3D v)
        Add a vector to the instance.
        Parameters:
        v - vector to add
        Returns:
        a new vector
      • add

        public Vector3D add​(double factor,
                            Vector3D 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

        public Vector3D subtract​(Vector3D v)
        Subtract a vector from the instance.
        Parameters:
        v - vector to subtract
        Returns:
        a new vector
      • subtract

        public Vector3D subtract​(double factor,
                                 Vector3D 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

        public Vector3D negate()
        Get the negation of the instance.
        Returns:
        a new vector which is the negation of the instance
      • normalize

        public Vector3D.Unit normalize()
        Get a normalized vector aligned with the instance. The returned vector has a magnitude of 1.
        Returns:
        normalized vector
        See Also:
        Vector.normalizeOrNull()
      • normalizeOrNull

        public Vector3D.Unit 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 Vector.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:
        Vector.normalize()
      • multiply

        public Vector3D multiply​(double a)
        Multiply the instance by a scalar.
        Parameters:
        a - scalar
        Returns:
        a new vector
      • distance

        public double distance​(Vector3D v)
        Compute the distance between the instance and another vector.
        Parameters:
        v - second vector
        Returns:
        the distance between the instance and v
      • distanceSq

        public double distanceSq​(Vector3D 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:
        Vector.normSq()
      • dot

        public double dot​(Vector3D v)
        Compute the dot-product of the instance and another vector.

        The implementation uses specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects. It should be very accurate even for nearly orthogonal vectors.

        Parameters:
        v - second vector
        Returns:
        the dot product (this · v)
        See Also:
        Sum
      • angle

        public double angle​(Vector3D v)
        Compute the angular separation between two vectors in radians.

        This method computes the angular separation between two vectors using the dot product for well separated vectors and the cross product for almost aligned vectors. This allows to have a good accuracy in all cases, even for vectors very close to each other.

        Parameters:
        v - other vector
        Returns:
        angular separation between this instance and v in radians
      • orthogonal

        public Vector3D.Unit orthogonal()
        Get a unit vector orthogonal to the instance.

        There are an infinite number of normalized vectors orthogonal to the instance. This method picks up one of them almost arbitrarily. It is useful when one needs to compute a reference frame with one of the axes in a predefined direction. The following example shows how to build a frame having the k axis aligned with the known vector u :

        
           Vector3D k = u.normalize();
           Vector3D i = k.orthogonal();
           Vector3D j = k.cross(i);
         
        Specified by:
        orthogonal in class MultiDimensionalEuclideanVector<Vector3D>
        Returns:
        a unit vector orthogonal to the instance
        Throws:
        java.lang.IllegalArgumentException - if the norm of the instance is zero, NaN, or infinite
      • orthogonal

        public Vector3D.Unit orthogonal​(Vector3D dir)
        Get a unit vector orthogonal to the current vector and pointing in the direction of dir. This method is equivalent to calling dir.reject(vec).normalize() except that no intermediate vector object is produced.
        Specified by:
        orthogonal in class MultiDimensionalEuclideanVector<Vector3D>
        Parameters:
        dir - the direction to use for generating the orthogonal vector
        Returns:
        unit vector orthogonal to the current vector and pointing in the direction of dir that does not lie along the current vector
      • cross

        public Vector3D cross​(Vector3D v)
        Compute the cross-product of the instance with another vector.
        Parameters:
        v - other vector
        Returns:
        the cross product this ^ v as a new Vector3D
      • transform

        public Vector3D transform​(java.util.function.UnaryOperator<Vector3D> fn)
        Convenience method to apply a function to this vector. This can be used to transform the vector inline with other methods.
        Parameters:
        fn - the function to apply
        Returns:
        the transformed vector
      • eq

        public boolean eq​(Vector3D vec,
                          org.apache.commons.numbers.core.Precision.DoubleEquivalence 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.

        Specified by:
        eq in class EuclideanVector<Vector3D>
        Parameters:
        vec - 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
      • hashCode

        public int hashCode()
        Get a hashCode for the vector.

        All NaN values have the same hash code.

        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hash code value for this object
      • equals

        public boolean equals​(java.lang.Object other)
        d Test for the equality of two vector instances.

        If all coordinates of two vectors are exactly the same, and none are Double.NaN, the two instances are considered to be equal.

        NaN coordinates are considered to globally affect the vector and be equal to each other - i.e, if either (or all) coordinates of the vector are equal to Double.NaN, the vector is equal to NaN.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - Object to test for equality to this
        Returns:
        true if two Vector3D objects are equal, false if object is null, not an instance of Vector3D, or not equal to this Vector3D instance
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • getComponent

        private <V extends Vector3D> V getComponent​(Vector3D base,
                                                    boolean reject,
                                                    DoubleFunction3N<V> factory)
        Returns a component of the current instance relative to the given base vector. If reject is true, the vector rejection is returned; otherwise, the projection is returned.
        Type Parameters:
        V - Vector implementation type
        Parameters:
        base - The base vector
        reject - If true, the rejection of this instance from base is returned. If false, the projection of this instance onto base is returned.
        factory - factory function used to build the final vector
        Returns:
        The projection or rejection of this instance relative to base, depending on the value of reject.
        Throws:
        java.lang.IllegalArgumentException - if base has a zero, NaN, or infinite norm
      • of

        public static Vector3D of​(double x,
                                  double y,
                                  double z)
        Returns a vector with the given coordinate values.
        Parameters:
        x - x coordinate value
        y - y coordinate value
        z - z coordinate value
        Returns:
        vector instance
      • of

        public static Vector3D of​(double[] v)
        Creates a vector from the coordinates in the given 3-element array.
        Parameters:
        v - coordinates array
        Returns:
        new vector
        Throws:
        java.lang.IllegalArgumentException - if the array does not have 3 elements
      • parse

        public static Vector3D parse​(java.lang.String str)
        Parses the given string and returns a new vector instance. The expected string format is the same as that returned by toString().
        Parameters:
        str - the string to parse
        Returns:
        vector instance represented by the string
        Throws:
        java.lang.IllegalArgumentException - if the given string has an invalid format
      • max

        public static Vector3D max​(Vector3D first,
                                   Vector3D... more)
        Return a vector containing the maximum component values from all input vectors.
        Parameters:
        first - first vector
        more - additional vectors
        Returns:
        a vector containing the maximum component values from all input vectors
      • max

        public static Vector3D max​(java.lang.Iterable<Vector3D> vecs)
        Return a vector containing the maximum component values from all input vectors.
        Parameters:
        vecs - input vectors
        Returns:
        a vector containing the maximum component values from all input vectors
        Throws:
        java.lang.IllegalArgumentException - if the argument does not contain any vectors
      • computeMax

        private static Vector3D computeMax​(Vector3D first,
                                           java.util.Iterator<? extends Vector3D> more)
        Internal method for computing a max vector.
        Parameters:
        first - first vector
        more - iterator with additional vectors
        Returns:
        vector containing the maximum component values of all input vectors
      • min

        public static Vector3D min​(Vector3D first,
                                   Vector3D... more)
        Return a vector containing the minimum component values from all input vectors.
        Parameters:
        first - first vector
        more - additional vectors
        Returns:
        a vector containing the minimum component values from all input vectors
      • min

        public static Vector3D min​(java.lang.Iterable<Vector3D> vecs)
        Return a vector containing the minimum component values from all input vectors.
        Parameters:
        vecs - input vectors
        Returns:
        a vector containing the minimum component values from all input vectors
        Throws:
        java.lang.IllegalArgumentException - if the argument does not contain any vectors
      • computeMin

        private static Vector3D computeMin​(Vector3D first,
                                           java.util.Iterator<? extends Vector3D> more)
        Internal method for computing a min vector.
        Parameters:
        first - first vector
        more - iterator with additional vectors
        Returns:
        vector containing the minimum component values of all input vectors
      • centroid

        public static Vector3D centroid​(Vector3D first,
                                        Vector3D... more)
        Compute the centroid of the given points. The centroid is the arithmetic mean position of a set of points.
        Parameters:
        first - first point
        more - additional points
        Returns:
        the centroid of the given points
      • centroid

        public static Vector3D centroid​(java.lang.Iterable<Vector3D> pts)
        Compute the centroid of the given points. The centroid is the arithmetic mean position of a set of points.
        Parameters:
        pts - the points to compute the centroid of
        Returns:
        the centroid of the given points
        Throws:
        java.lang.IllegalArgumentException - if the argument contains no points
      • computeCentroid

        private static Vector3D computeCentroid​(Vector3D first,
                                                java.util.Iterator<? extends Vector3D> more)
        Internal method for computing the centroid of a set of points.
        Parameters:
        first - first point
        more - iterator with additional points
        Returns:
        the centroid of the point set