Class Vector3D.Unit
java.lang.Object
org.apache.commons.geometry.euclidean.EuclideanVector<Vector3D>
org.apache.commons.geometry.euclidean.MultiDimensionalEuclideanVector<Vector3D>
org.apache.commons.geometry.euclidean.threed.Vector3D
org.apache.commons.geometry.euclidean.threed.Vector3D.Unit
- Enclosing class:
Vector3D
Represents unit vectors.
This allows optimizations for certain operations.
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.commons.geometry.euclidean.threed.Vector3D
Vector3D.Sum, Vector3D.Unit
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final Vector3D.Unit
Negation of unit vector (coordinates: -1, 0, 0).static final Vector3D.Unit
Negation of unit vector (coordinates: 0, -1, 0).static final Vector3D.Unit
Negation of unit vector (coordinates: 0, 0, -1).static final Vector3D.Unit
Unit vector (coordinates: 1, 0, 0).static final Vector3D.Unit
Unit vector (coordinates: 0, 1, 0).static final Vector3D.Unit
Unit vector (coordinates: 0, 0, 1).private static final double
Factor used to scale down coordinate values in order to produce normalized coordinates without overflow or underflow.private static final double
Factor used to scale up coordinate values in order to produce normalized coordinates without overflow or underflow.private static final double
Maximum coordinate value for computing normalized vectors with raw, unscaled values.Fields inherited from class org.apache.commons.geometry.euclidean.threed.Vector3D
COORDINATE_ASCENDING_ORDER, NaN, NEGATIVE_INFINITY, POSITIVE_INFINITY, ZERO
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic Vector3D.Unit
from
(double x, double y, double z) Create a normalized vector.static Vector3D.Unit
Create a normalized vector.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.private static Vector3D.Unit
tryCreateNormalized
(double x, double y, double z, boolean throwOnFailure) Attempt to create a normalized vector from the given coordinate values.withNorm
(double mag) Returns a vector with the same direction but with the given norm.Methods inherited from class org.apache.commons.geometry.euclidean.threed.Vector3D
add, add, angle, centroid, centroid, cross, directionTo, distance, distanceSq, dot, eq, equals, getDimension, getX, getY, getZ, getZero, hashCode, isFinite, isInfinite, isNaN, lerp, max, max, min, min, multiply, of, of, orthogonal, orthogonal, parse, project, reject, subtract, subtract, toArray, toString, transform, vectorTo
Methods inherited from class org.apache.commons.geometry.euclidean.EuclideanVector
getCheckedNorm, isZero
-
Field Details
-
PLUS_X
Unit vector (coordinates: 1, 0, 0). -
MINUS_X
Negation of unit vector (coordinates: -1, 0, 0). -
PLUS_Y
Unit vector (coordinates: 0, 1, 0). -
MINUS_Y
Negation of unit vector (coordinates: 0, -1, 0). -
PLUS_Z
Unit vector (coordinates: 0, 0, 1). -
MINUS_Z
Negation of unit vector (coordinates: 0, 0, -1). -
UNSCALED_MAX
private static final double UNSCALED_MAXMaximum coordinate value for computing normalized vectors with raw, unscaled values.- See Also:
-
SCALE_UP_FACTOR
private static final double SCALE_UP_FACTORFactor used to scale up coordinate values in order to produce normalized coordinates without overflow or underflow.- See Also:
-
SCALE_DOWN_FACTOR
private static final double SCALE_DOWN_FACTORFactor used to scale down coordinate values in order to produce normalized coordinates without overflow or underflow.- See Also:
-
-
Constructor Details
-
Unit
private Unit(double x, double y, double z) Simple constructor. Callers are responsible for ensuring that the given values represent a normalized vector.- Parameters:
x
- x coordinate valuey
- x coordinate valuez
- x coordinate value
-
-
Method Details
-
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. -
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. -
normalize
Get a normalized vector aligned with the instance. The returned vector has a magnitude of 1. -
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.- Specified by:
normalizeOrNull
in interfaceVector<Vector3D>
- Overrides:
normalizeOrNull
in classVector3D
- Returns:
- normalized vector or null if such a vector cannot be computed, i.e. if the norm is zero, NaN, or infinite
- 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. -
negate
Get the negation of the instance. -
from
Create a normalized vector.- Parameters:
x
- Vector coordinate.y
- Vector coordinate.z
- Vector coordinate.- Returns:
- a vector whose norm is 1.
- Throws:
IllegalArgumentException
- if the norm of the given value is zero, NaN, or infinite
-
from
Create a normalized vector.- Parameters:
v
- Vector.- Returns:
- a vector whose norm is 1.
- Throws:
IllegalArgumentException
- if the norm of the given value is zero, NaN, or infinite
-
tryCreateNormalized
private static Vector3D.Unit tryCreateNormalized(double x, double y, double z, boolean throwOnFailure) Attempt to create a normalized vector from the given coordinate values. IfthrowOnFailure
is true, an exception is thrown if a normalized vector cannot be created. Otherwise, null is returned.- Parameters:
x
- x coordinatey
- y coordinatez
- z coordinatethrowOnFailure
- if true, an exception will be thrown if a normalized vector cannot be created- Returns:
- normalized vector or null if one cannot be created and
throwOnFailure
is false - Throws:
IllegalArgumentException
- if the computed norm is zero, NaN, or infinite
-