Package org.apache.commons.geometry.euclidean.threed

Class Vector3D.Unit

java.lang.Object

org.apache.commons.geometry.euclidean.EuclideanVector<V>

org.apache.commons.geometry.euclidean.MultiDimensionalEuclideanVector<Vector3D>

org.apache.commons.geometry.euclidean.threed.Vector3D

org.apache.commons.geometry.euclidean.threed.Vector3D.Unit

All Implemented Interfaces:

Point<Vector3D>, Spatial, Vector<Vector3D>

Enclosing class:

Vector3D

public static final class Vector3D.Unit
extends 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

Fields

Modifier and Type	Field	Description
static Vector3D.Unit	MINUS_X	Negation of unit vector (coordinates: -1, 0, 0).
static Vector3D.Unit	MINUS_Y	Negation of unit vector (coordinates: 0, -1, 0).
static Vector3D.Unit	MINUS_Z	Negation of unit vector (coordinates: 0, 0, -1).
static Vector3D.Unit	PLUS_X	Unit vector (coordinates: 1, 0, 0).
static Vector3D.Unit	PLUS_Y	Unit vector (coordinates: 0, 1, 0).
static Vector3D.Unit	PLUS_Z	Unit vector (coordinates: 0, 0, 1).
private static double	SCALE_DOWN_FACTOR	Factor used to scale down coordinate values in order to produce normalized coordinates without overflow or underflow.
private static double	SCALE_UP_FACTOR	Factor used to scale up coordinate values in order to produce normalized coordinates without overflow or underflow.
private static double	UNSCALED_MAX	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

Modifier	Constructor	Description
private	Unit(double x, double y, double z)	Simple constructor.

Method Summary

Modifier and Type	Method	Description
static Vector3D.Unit	from(double x, double y, double z)	Create a normalized vector.
static Vector3D.Unit	from(Vector3D v)	Create a normalized vector.
Vector3D.Unit	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.
private static Vector3D.Unit	tryCreateNormalized(double x, double y, double z, boolean throwOnFailure)	Attempt to create a normalized vector from the given coordinate values.
Vector3D	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

Methods inherited from class java.lang.Object

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

Field Detail

PLUS_X

public static final Vector3D.Unit PLUS_X

Unit vector (coordinates: 1, 0, 0).

MINUS_X

public static final Vector3D.Unit MINUS_X

Negation of unit vector (coordinates: -1, 0, 0).

PLUS_Y

public static final Vector3D.Unit PLUS_Y

Unit vector (coordinates: 0, 1, 0).

MINUS_Y

public static final Vector3D.Unit MINUS_Y

Negation of unit vector (coordinates: 0, -1, 0).

PLUS_Z

public static final Vector3D.Unit PLUS_Z

Unit vector (coordinates: 0, 0, 1).

MINUS_Z

public static final Vector3D.Unit MINUS_Z

Negation of unit vector (coordinates: 0, 0, -1).

UNSCALED_MAX

private static final double UNSCALED_MAX

Maximum coordinate value for computing normalized vectors with raw, unscaled values.

See Also:

Constant Field Values

SCALE_UP_FACTOR

private static final double SCALE_UP_FACTOR

Factor used to scale up coordinate values in order to produce normalized coordinates without overflow or underflow.

See Also:

Constant Field Values

SCALE_DOWN_FACTOR

private static final double SCALE_DOWN_FACTOR

Factor used to scale down coordinate values in order to produce normalized coordinates without overflow or underflow.

See Also:

Constant Field Values

Constructor Detail

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 value

y - x coordinate value

z - x coordinate value

Method Detail

norm

public double norm()

Get the L₂ 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.

Specified by:

norm in interface Vector<Vector3D>

Overrides:

norm in class Vector3D

Returns:

L₂ norm for the vector

See Also:

L2 Norm

normSq

public double normSq()

Get the square of the L₂ norm (also known as the Euclidean norm) for the vector. This is equal to the sum of the squares of all vector components.

Specified by:

normSq in interface Vector<Vector3D>

Overrides:

normSq in class Vector3D

Returns:

square of the L₂ norm for the vector

See Also:

Vector.norm()

normalize

public Vector3D.Unit normalize()

Get a normalized vector aligned with the instance. The returned vector has a magnitude of 1.

Specified by:

normalize in interface Vector<Vector3D>

Overrides:

normalize in class Vector3D

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.

Specified by:

normalizeOrNull in interface Vector<Vector3D>

Overrides:

normalizeOrNull in class Vector3D

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()

withNorm

public Vector3D withNorm(double mag)

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.

Specified by:

withNorm in interface Vector<Vector3D>

Overrides:

withNorm in class Vector3D

Parameters:

mag - The vector norm

Returns:

a vector with the same direction as the current instance but the given norm

negate

public Vector3D.Unit negate()

Get the negation of the instance.

Specified by:

negate in interface Vector<Vector3D>

Overrides:

negate in class Vector3D

Returns:

a new vector which is the negation of the instance

from

public static Vector3D.Unit from(double x,
                                 double y,
                                 double z)

Create a normalized vector.

Parameters:

x - Vector coordinate.

y - Vector coordinate.

z - Vector coordinate.

Returns:

a vector whose norm is 1.

Throws:

java.lang.IllegalArgumentException - if the norm of the given value is zero, NaN, or infinite

from

public static Vector3D.Unit from(Vector3D v)

Create a normalized vector.

Parameters:

v - Vector.

Returns:

a vector whose norm is 1.

Throws:

java.lang.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. If throwOnFailure is true, an exception is thrown if a normalized vector cannot be created. Otherwise, null is returned.

Parameters:

x - x coordinate

y - y coordinate

z - z coordinate

throwOnFailure - 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:

java.lang.IllegalArgumentException - if the computed norm is zero, NaN, or infinite