Class Vector2D
- Direct Known Subclasses:
Vector2D.Unit
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Class used to create high-accuracy sums of vectors.static final class
Represents unit vectors. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final Comparator
<Vector2D> Comparator that sorts vectors in component-wise ascending order.static final Vector2D
A vector with all coordinates set to NaN.static final Vector2D
A vector with all coordinates set to negative infinity.static final Vector2D
A vector with all coordinates set to positive infinity.private final double
Abscissa (first coordinate).private final double
Ordinate (second coordinate).static final Vector2D
Zero vector (coordinates: 0, 0). -
Constructor Summary
Constructors -
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.static Vector2D
Compute the centroid of the given points.static Vector2D
Compute the centroid of the given points.private static Vector2D
computeCentroid
(Vector2D first, Iterator<? extends Vector2D> more) Internal method for computing the centroid of a set of points.private static Vector2D
computeMax
(Vector2D first, Iterator<? extends Vector2D> more) Internal method for computing a max vector.private static Vector2D
computeMin
(Vector2D first, Iterator<? extends Vector2D> more) Internal method for computing a min vector.Return the unit vector representing the direction of displacement from this vector to the given vector.double
Compute the distance between the instance and another vector.double
Compute the square of the distance between the instance and another vector.double
Compute the dot-product of the instance and another vector.boolean
Return true if the current instance and given vector are considered equal as evaluated by the given precision context.boolean
Test for the equality of two vector instances.private <T extends Vector2D>
TgetComponent
(Vector2D base, boolean reject, DoubleFunction2N<T> factory) Returns a component of the current instance relative to the given base vector.int
Returns the number of dimensions in the space that this element belongs to.double
getX()
Returns the abscissa (first coordinate value) of the instance.double
getY()
Returns the ordinate (second coordinate value) of the instance.getZero()
Get the zero (null) vector of the space.int
hashCode()
Get a hashCode for the 2D coordinates.boolean
isFinite()
Returns true if all values in this element are finite, meaning they are not NaN or infinite.boolean
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.Get a vector constructed by linearly interpolating between this vector and the given vector.static Vector2D
Return a vector containing the maximum component values from all input vectors.static Vector2D
Return a vector containing the maximum component values from all input vectors.static Vector2D
Return a vector containing the minimum component values from all input vectors.static Vector2D
Return a vector containing the minimum component values from all input vectors.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.static Vector2D
of
(double[] v) Creates a vector from the coordinates in the given 2-element array.static Vector2D
of
(double x, double y) Returns a vector with the given coordinate values.Get a unit vector orthogonal to the instance.orthogonal
(Vector2D dir) Get a unit vector orthogonal to the current vector and pointing in the direction ofdir
.static Vector2D
Parses the given string and returns a new vector instance.Get the projection of the instance onto the given base vector.Get the rejection of the instance from the given base vector.double
Compute the signed area of the parallelogram with sides formed by this instance and the given vector.Subtract a scaled vector from the instance.Subtract a vector from the instance.double[]
toArray()
Get the coordinates for this instance as a dimension 2 array.toString()
Convenience method to apply a function to this vector.Return the vector representing the displacement from this vector to the given vector.withNorm
(double magnitude) Returns a vector with the same direction but with the given norm.Methods inherited from class org.apache.commons.geometry.euclidean.EuclideanVector
getCheckedNorm, isZero
-
Field Details
-
ZERO
Zero vector (coordinates: 0, 0). -
NaN
A vector with all coordinates set to NaN. -
POSITIVE_INFINITY
A vector with all coordinates set to positive infinity. -
NEGATIVE_INFINITY
A vector with all coordinates set to negative infinity. -
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 xAbscissa (first coordinate). -
y
private final double yOrdinate (second coordinate).
-
-
Constructor Details
-
Vector2D
private Vector2D(double x, double y) Simple constructor.- Parameters:
x
- abscissa (first coordinate)y
- ordinate (second coordinate)
-
-
Method Details
-
getX
public double getX()Returns the abscissa (first coordinate value) of the instance.- Returns:
- the abscissa
-
getY
public double getY()Returns the ordinate (second coordinate value) of the instance.- Returns:
- the ordinate
-
toArray
public double[] toArray()Get the coordinates for this instance as a dimension 2 array.- Returns:
- 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
-
vectorTo
Return the vector representing the displacement from this vector to the given vector. This is exactly equivalent tov.subtract(thisVector)
but with a method name that is much easier to visualize.- Specified by:
vectorTo
in classEuclideanVector<Vector2D>
- 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
Return the unit vector representing the direction of displacement from this vector to the given vector. This is exactly equivalent tov.subtract(thisVector).normalize()
but without the intermediate vector instance.- Specified by:
directionTo
in classEuclideanVector<Vector2D>
- 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
Get a vector constructed by linearly interpolating between this vector and the given vector. The vector coordinates are generated by the equationV = (1 - t)*A + t*B
, whereA
is the current vector andB
is the given vector. This means that ift = 0
, a vector equal to the current vector will be returned. Ift = 1
, a vector equal to the argument will be returned. Thet
parameter is not constrained to the range[0, 1]
, meaning that linear extrapolation can also be performed with this method.- Specified by:
lerp
in classEuclideanVector<Vector2D>
- Parameters:
p
- other vectort
- interpolation parameter- Returns:
- interpolated or extrapolated vector
-
getZero
Get the zero (null) vector of the space.- Returns:
- zero vector of the space
-
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:
-
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:
-
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:
magnitude
- 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
Get the negation of the instance.- Returns:
- a new vector which is the negation of the instance
-
normalize
Get a normalized vector aligned with the instance. The returned vector has a magnitude of 1.- Returns:
- normalized vector
- See Also:
-
normalizeOrNull
Attempt to compute a normalized vector aligned with the instance, returning null if such a vector cannot be computed. This method is equivalent toVector.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
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.This method computes the angular separation between the 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
-
project
Get the projection of the instance onto the given base vector. The returned vector is parallel tobase
. Vector projection and rejection onto a given base are related by the equationv = vprojection + vrejection
- Specified by:
project
in classMultiDimensionalEuclideanVector<Vector2D>
- Parameters:
base
- base vector- Returns:
- the vector projection of the instance onto
base
- See Also:
-
reject
Get the rejection of the instance from the given base vector. The returned vector is orthogonal tobase
. This operation can be interpreted as returning the orthogonal projection of the instance onto the hyperplane orthogonal tobase
. Vector projection and rejection onto a given base are related by the equationv = vprojection + vrejection
- Specified by:
reject
in classMultiDimensionalEuclideanVector<Vector2D>
- Parameters:
base
- base vector- Returns:
- the vector rejection of the instance from
base
- See Also:
-
orthogonal
Get a unit vector orthogonal to the instance. The returned vector is computed by rotating the current instancepi/2
radians counterclockwise around the origin and normalizing. For example, if this method is called on a vector pointing along the positive x-axis, then a unit vector representing the positive y-axis is returned.- Specified by:
orthogonal
in classMultiDimensionalEuclideanVector<Vector2D>
- Returns:
- a unit vector orthogonal to the current instance
- Throws:
IllegalArgumentException
- if the norm of the current instance is zero, NaN, or infinite
-
orthogonal
Get a unit vector orthogonal to the current vector and pointing in the direction ofdir
. This method is equivalent to callingdir.reject(vec).normalize()
except that no intermediate vector object is produced.- Specified by:
orthogonal
in classMultiDimensionalEuclideanVector<Vector2D>
- 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
-
signedArea
Compute the signed area of the parallelogram with sides formed by this instance and the given vector.The parallelogram in question can be visualized by taking the current instance as the first side and placing
v
at the end of it to create the second. The other sides are formed by lines parallel to these two vectors. Ifv
points to the left of the current instance (ie, the parallelogram is wound counter-clockwise), then the returned area is positive. Ifv
points to the right of the current instance, (ie, the parallelogram is wound clockwise), then the returned area is negative. If the vectors are collinear (ie, they lie on the same line), then 0 is returned. The area of the triangle formed by the two vectors is exactly half of the returned value.- Parameters:
v
- vector representing the second side of the constructed parallelogram- Returns:
- the signed area of the parallelogram formed by this instance and the given vector
-
transform
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(Vector2D 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)
, wheren
is the number of components in the vector andeps
is the maximum epsilon value allowed by the precision context.- Specified by:
eq
in classEuclideanVector<Vector2D>
- Parameters:
vec
- vector to check for equalityprecision
- 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 2D coordinates.All NaN values have the same hash code.
-
equals
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 toDouble.NaN
, the vector is equal toNaN
. -
toString
-
getComponent
private <T extends Vector2D> T getComponent(Vector2D base, boolean reject, DoubleFunction2N<T> factory) Returns a component of the current instance relative to the given base vector. Ifreject
is true, the vector rejection is returned; otherwise, the projection is returned.- Type Parameters:
T
- Vector implementation type- Parameters:
base
- The base vectorreject
- If true, the rejection of this instance frombase
is returned. If false, the projection of this instance ontobase
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 ofreject
. - Throws:
IllegalArgumentException
- ifbase
has a zero, NaN, or infinite norm
-
of
Returns a vector with the given coordinate values.- Parameters:
x
- abscissa (first coordinate value)y
- abscissa (second coordinate value)- Returns:
- vector instance
-
of
Creates a vector from the coordinates in the given 2-element array.- Parameters:
v
- coordinates array- Returns:
- new vector
- Throws:
IllegalArgumentException
- if the array does not have 2 elements
-
parse
Parses the given string and returns a new vector instance. The expected string format is the same as that returned bytoString()
.- Parameters:
str
- the string to parse- Returns:
- vector instance represented by the string
- Throws:
IllegalArgumentException
- if the given string has an invalid format
-
max
Return a vector containing the maximum component values from all input vectors.- Parameters:
first
- first vectormore
- additional vectors- Returns:
- a vector containing the maximum component values from all input vectors
-
max
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:
IllegalArgumentException
- if the argument does not contain any vectors
-
computeMax
Internal method for computing a max vector.- Parameters:
first
- first vectormore
- iterator with additional vectors- Returns:
- vector containing the maximum component values of all input vectors
-
min
Return a vector containing the minimum component values from all input vectors.- Parameters:
first
- first vectormore
- more vectors- Returns:
- a vector containing the minimum component values from all input vectors
-
min
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:
IllegalArgumentException
- if the argument does not contain any vectors
-
computeMin
Internal method for computing a min vector.- Parameters:
first
- first vectormore
- iterator with additional vectors- Returns:
- vector containing the minimum component values of all input vectors
-
centroid
Compute the centroid of the given points. The centroid is the arithmetic mean position of a set of points.- Parameters:
first
- first pointmore
- additional points- Returns:
- the centroid of the given points
-
centroid
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:
IllegalArgumentException
- if the argument contains no points
-
computeCentroid
Internal method for computing the centroid of a set of points.- Parameters:
first
- first pointmore
- iterator with additional points- Returns:
- the centroid of the point set
-