Class Quaternion
- java.lang.Object
-
- org.apache.commons.numbers.quaternion.Quaternion
-
- All Implemented Interfaces:
java.io.Serializable
public final class Quaternion extends java.lang.Object implements java.io.Serializable
This class implements quaternions (Hamilton's hypercomplex numbers).Wherever quaternion components are listed in sequence, this class follows the convention of placing the scalar (
w
) component first, e.g. [w, x, y, z
]. Other libraries and textbooks may place thew
component last.Instances of this class are guaranteed to be immutable.
- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Quaternion.QuaternionParsingException
Seeparse(String)
.private static class
Quaternion.Type
For enabling optimized implementations.
-
Field Summary
Fields Modifier and Type Field Description private static java.lang.String
FORMAT_END
private static java.lang.String
FORMAT_SEP
private static java.lang.String
FORMAT_START
static Quaternion
I
i.private static java.lang.String
ILLEGAL_NORM_MSG
Error message.static Quaternion
J
j.static Quaternion
K
k.private static int
NUMBER_OF_PARTS
The number of parts when parsing a text representation of the quaternion.static Quaternion
ONE
Identity quaternion.private static long
serialVersionUID
Serializable version identifier.private Quaternion.Type
type
For enabling specialized method implementations.private static int
VECTOR_DIMENSIONS
The number of dimensions for the vector part of the quaternion.private double
w
First component (scalar part).private double
x
Second component (first vector part).private double
y
Third component (second vector part).private double
z
Fourth component (third vector part).static Quaternion
ZERO
Zero quaternion.
-
Constructor Summary
Constructors Modifier Constructor Description private
Quaternion(Quaternion.Type type, double w, double x, double y, double z)
Builds a quaternion from its components.private
Quaternion(Quaternion.Type type, Quaternion q)
Copies the given quaternion, but change itsQuaternion.Type
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Quaternion
add(Quaternion q)
Computes the sum of the instance and another quaternion.static Quaternion
add(Quaternion q1, Quaternion q2)
Computes the sum of two quaternions.Quaternion
conjugate()
Returns the conjugate of this quaternion number.Quaternion
divide(double alpha)
Divides the instance by a scalar.double
dot(Quaternion q)
Computes the dot-product of the instance by a quaternion.static double
dot(Quaternion q1, Quaternion q2)
Computes the dot-product of two quaternions.boolean
equals(java.lang.Object other)
boolean
equals(Quaternion q, double eps)
Checks whether this instance is equal to another quaternion within a given tolerance.double
getScalarPart()
Gets the scalar part of the quaternion.double[]
getVectorPart()
Gets the three components of the vector part of the quaternion.double
getW()
Gets the first component of the quaternion (scalar part).double
getX()
Gets the second component of the quaternion (first component of the vector part).double
getY()
Gets the third component of the quaternion (second component of the vector part).double
getZ()
Gets the fourth component of the quaternion (third component of the vector part).int
hashCode()
Quaternion
inverse()
Returns the inverse of this instance.boolean
isPure(double eps)
Checks whether the instance is a pure quaternion within a given tolerance.boolean
isUnit(double eps)
Checks whether the instance is a unit quaternion within a given tolerance.Quaternion
multiply(double alpha)
Multiplies the instance by a scalar.Quaternion
multiply(Quaternion q)
Returns the Hamilton product of the instance by a quaternion.static Quaternion
multiply(Quaternion q1, Quaternion q2)
Returns the Hamilton product of two quaternions.Quaternion
negate()
Returns the opposite of this instance.double
norm()
Computes the norm of the quaternion.Quaternion
normalize()
Computes the normalized quaternion (the versor of the instance).double
normSq()
Computes the square of the norm of the quaternion.static Quaternion
of(double[] v)
Builds a pure quaternion from a vector (assuming that the scalar part is zero).static Quaternion
of(double scalar, double[] v)
Builds a quaternion from scalar and vector parts.static Quaternion
of(double w, double x, double y, double z)
Builds a quaternion from its components.static Quaternion
parse(java.lang.String s)
Parses a string that would be produced bytoString()
and instantiates the corresponding object.Quaternion
positivePolarForm()
Returns the polar form of the quaternion.Quaternion
subtract(Quaternion q)
Subtracts a quaternion from the instance.static Quaternion
subtract(Quaternion q1, Quaternion q2)
Subtracts two quaternions.java.lang.String
toString()
-
-
-
Field Detail
-
ZERO
public static final Quaternion ZERO
Zero quaternion.
-
ONE
public static final Quaternion ONE
Identity quaternion.
-
I
public static final Quaternion I
i.
-
J
public static final Quaternion J
j.
-
K
public static final Quaternion K
k.
-
serialVersionUID
private static final long serialVersionUID
Serializable version identifier.- See Also:
- Constant Field Values
-
ILLEGAL_NORM_MSG
private static final java.lang.String ILLEGAL_NORM_MSG
Error message.- See Also:
- Constant Field Values
-
FORMAT_START
private static final java.lang.String FORMAT_START
- See Also:
- Constant Field Values
-
FORMAT_END
private static final java.lang.String FORMAT_END
- See Also:
- Constant Field Values
-
FORMAT_SEP
private static final java.lang.String FORMAT_SEP
- See Also:
- Constant Field Values
-
VECTOR_DIMENSIONS
private static final int VECTOR_DIMENSIONS
The number of dimensions for the vector part of the quaternion.- See Also:
- Constant Field Values
-
NUMBER_OF_PARTS
private static final int NUMBER_OF_PARTS
The number of parts when parsing a text representation of the quaternion.- See Also:
- Constant Field Values
-
type
private final Quaternion.Type type
For enabling specialized method implementations.
-
w
private final double w
First component (scalar part).
-
x
private final double x
Second component (first vector part).
-
y
private final double y
Third component (second vector part).
-
z
private final double z
Fourth component (third vector part).
-
-
Constructor Detail
-
Quaternion
private Quaternion(Quaternion.Type type, double w, double x, double y, double z)
Builds a quaternion from its components.- Parameters:
type
- Quaternion type.w
- Scalar component.x
- First vector component.y
- Second vector component.z
- Third vector component.
-
Quaternion
private Quaternion(Quaternion.Type type, Quaternion q)
Copies the given quaternion, but change itsQuaternion.Type
.- Parameters:
type
- Quaternion type.q
- Quaternion whose components will be copied.
-
-
Method Detail
-
of
public static Quaternion of(double w, double x, double y, double z)
Builds a quaternion from its components.- Parameters:
w
- Scalar component.x
- First vector component.y
- Second vector component.z
- Third vector component.- Returns:
- a quaternion instance.
-
of
public static Quaternion of(double scalar, double[] v)
Builds a quaternion from scalar and vector parts.- Parameters:
scalar
- Scalar part of the quaternion.v
- Components of the vector part of the quaternion.- Returns:
- a quaternion instance.
- Throws:
java.lang.IllegalArgumentException
- if the array length is not 3.
-
of
public static Quaternion of(double[] v)
Builds a pure quaternion from a vector (assuming that the scalar part is zero).- Parameters:
v
- Components of the vector part of the pure quaternion.- Returns:
- a quaternion instance.
-
conjugate
public Quaternion conjugate()
Returns the conjugate of this quaternion number. The conjugate ofa + bi + cj + dk
isa - bi -cj -dk
.- Returns:
- the conjugate of this quaternion object.
-
multiply
public static Quaternion multiply(Quaternion q1, Quaternion q2)
Returns the Hamilton product of two quaternions.- Parameters:
q1
- First quaternion.q2
- Second quaternion.- Returns:
- the product
q1
andq2
, in that order.
-
multiply
public Quaternion multiply(Quaternion q)
Returns the Hamilton product of the instance by a quaternion.- Parameters:
q
- Quaternion.- Returns:
- the product of this instance with
q
, in that order.
-
add
public static Quaternion add(Quaternion q1, Quaternion q2)
Computes the sum of two quaternions.- Parameters:
q1
- Quaternion.q2
- Quaternion.- Returns:
- the sum of
q1
andq2
.
-
add
public Quaternion add(Quaternion q)
Computes the sum of the instance and another quaternion.- Parameters:
q
- Quaternion.- Returns:
- the sum of this instance and
q
.
-
subtract
public static Quaternion subtract(Quaternion q1, Quaternion q2)
Subtracts two quaternions.- Parameters:
q1
- First Quaternion.q2
- Second quaternion.- Returns:
- the difference between
q1
andq2
.
-
subtract
public Quaternion subtract(Quaternion q)
Subtracts a quaternion from the instance.- Parameters:
q
- Quaternion.- Returns:
- the difference between this instance and
q
.
-
dot
public static double dot(Quaternion q1, Quaternion q2)
Computes the dot-product of two quaternions.- Parameters:
q1
- Quaternion.q2
- Quaternion.- Returns:
- the dot product of
q1
andq2
.
-
dot
public double dot(Quaternion q)
Computes the dot-product of the instance by a quaternion.- Parameters:
q
- Quaternion.- Returns:
- the dot product of this instance and
q
.
-
norm
public double norm()
Computes the norm of the quaternion.- Returns:
- the norm.
-
normSq
public double normSq()
Computes the square of the norm of the quaternion.- Returns:
- the square of the norm.
-
normalize
public Quaternion normalize()
Computes the normalized quaternion (the versor of the instance). The norm of the quaternion must not be near zero.- Returns:
- a normalized quaternion.
- Throws:
java.lang.IllegalStateException
- if the norm of the quaternion is NaN, infinite, or near zero.
-
equals
public boolean equals(java.lang.Object other)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(Quaternion q, double eps)
Checks whether this instance is equal to another quaternion within a given tolerance.- Parameters:
q
- Quaternion with which to compare the current quaternion.eps
- Tolerance.- Returns:
true
if the each of the components are equal within the allowed absolute error.
-
isUnit
public boolean isUnit(double eps)
Checks whether the instance is a unit quaternion within a given tolerance.- Parameters:
eps
- Tolerance (absolute error).- Returns:
true
if the norm is 1 within the given tolerance,false
otherwise
-
isPure
public boolean isPure(double eps)
Checks whether the instance is a pure quaternion within a given tolerance.- Parameters:
eps
- Tolerance (absolute error).- Returns:
true
if the scalar part of the quaternion is zero.
-
positivePolarForm
public Quaternion positivePolarForm()
Returns the polar form of the quaternion.- Returns:
- the unit quaternion with positive scalar part.
-
negate
public Quaternion negate()
Returns the opposite of this instance.- Returns:
- the quaternion for which all components have an opposite sign to this one.
-
inverse
public Quaternion inverse()
Returns the inverse of this instance. The norm of the quaternion must not be zero.- Returns:
- the inverse.
- Throws:
java.lang.IllegalStateException
- if the norm (squared) of the quaternion is NaN, infinite, or near zero.
-
getW
public double getW()
Gets the first component of the quaternion (scalar part).- Returns:
- the scalar part.
-
getX
public double getX()
Gets the second component of the quaternion (first component of the vector part).- Returns:
- the first component of the vector part.
-
getY
public double getY()
Gets the third component of the quaternion (second component of the vector part).- Returns:
- the second component of the vector part.
-
getZ
public double getZ()
Gets the fourth component of the quaternion (third component of the vector part).- Returns:
- the third component of the vector part.
-
getScalarPart
public double getScalarPart()
Gets the scalar part of the quaternion.- Returns:
- the scalar part.
- See Also:
getW()
-
getVectorPart
public double[] getVectorPart()
Gets the three components of the vector part of the quaternion.
-
multiply
public Quaternion multiply(double alpha)
Multiplies the instance by a scalar.- Parameters:
alpha
- Scalar factor.- Returns:
- a scaled quaternion.
-
divide
public Quaternion divide(double alpha)
Divides the instance by a scalar.- Parameters:
alpha
- Scalar factor.- Returns:
- a scaled quaternion.
-
parse
public static Quaternion parse(java.lang.String s)
Parses a string that would be produced bytoString()
and instantiates the corresponding object.- Parameters:
s
- String representation.- Returns:
- an instance.
- Throws:
java.lang.NumberFormatException
- if the string does not conform to the specification.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-