Class Quaternion
java.lang.Object
org.apache.commons.numbers.quaternion.Quaternion
- All Implemented Interfaces:
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 the w
component last.
Instances of this class are guaranteed to be immutable.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
Seeparse(String)
.private static enum
For enabling optimized implementations. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final String
private static final String
private static final String
static final Quaternion
i.private static final String
Error message.static final Quaternion
j.static final Quaternion
k.private static final int
The number of parts when parsing a text representation of the quaternion.static final Quaternion
Identity quaternion.private static final long
Serializable version identifier.private final Quaternion.Type
For enabling specialized method implementations.private static final int
The number of dimensions for the vector part of the quaternion.private final double
First component (scalar part).private final double
Second component (first vector part).private final double
Third component (second vector part).private final double
Fourth component (third vector part).static final Quaternion
Zero quaternion. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
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
Modifier and TypeMethodDescriptionadd
(Quaternion q) Computes the sum of the instance and another quaternion.static Quaternion
add
(Quaternion q1, Quaternion q2) Computes the sum of two quaternions.Returns the conjugate of this quaternion number.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
boolean
equals
(Quaternion q, double eps) Checks whether this instance is equal to another quaternion within a given tolerance.double
Gets the scalar part of the quaternion.double[]
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()
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.multiply
(double alpha) Multiplies the instance by a scalar.Returns the Hamilton product of the instance by a quaternion.static Quaternion
multiply
(Quaternion q1, Quaternion q2) Returns the Hamilton product of two quaternions.negate()
Returns the opposite of this instance.double
norm()
Computes the norm of the quaternion.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
Parses a string that would be produced bytoString()
and instantiates the corresponding object.Returns the polar form of the quaternion.Subtracts a quaternion from the instance.static Quaternion
subtract
(Quaternion q1, Quaternion q2) Subtracts two quaternions.toString()
-
Field Details
-
ZERO
Zero quaternion. -
ONE
Identity quaternion. -
I
i. -
J
j. -
K
k. -
serialVersionUID
private static final long serialVersionUIDSerializable version identifier.- See Also:
-
ILLEGAL_NORM_MSG
Error message.- See Also:
-
FORMAT_START
- See Also:
-
FORMAT_END
- See Also:
-
FORMAT_SEP
- See Also:
-
VECTOR_DIMENSIONS
private static final int VECTOR_DIMENSIONSThe number of dimensions for the vector part of the quaternion.- See Also:
-
NUMBER_OF_PARTS
private static final int NUMBER_OF_PARTSThe number of parts when parsing a text representation of the quaternion.- See Also:
-
type
For enabling specialized method implementations. -
w
private final double wFirst component (scalar part). -
x
private final double xSecond component (first vector part). -
y
private final double yThird component (second vector part). -
z
private final double zFourth component (third vector part).
-
-
Constructor Details
-
Quaternion
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
Copies the given quaternion, but change itsQuaternion.Type
.- Parameters:
type
- Quaternion type.q
- Quaternion whose components will be copied.
-
-
Method Details
-
of
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
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:
IllegalArgumentException
- if the array length is not 3.
-
of
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
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
Returns the Hamilton product of two quaternions.- Parameters:
q1
- First quaternion.q2
- Second quaternion.- Returns:
- the product
q1
andq2
, in that order.
-
multiply
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
Computes the sum of two quaternions.- Parameters:
q1
- Quaternion.q2
- Quaternion.- Returns:
- the sum of
q1
andq2
.
-
add
Computes the sum of the instance and another quaternion.- Parameters:
q
- Quaternion.- Returns:
- the sum of this instance and
q
.
-
subtract
Subtracts two quaternions.- Parameters:
q1
- First Quaternion.q2
- Second quaternion.- Returns:
- the difference between
q1
andq2
.
-
subtract
Subtracts a quaternion from the instance.- Parameters:
q
- Quaternion.- Returns:
- the difference between this instance and
q
.
-
dot
Computes the dot-product of two quaternions.- Parameters:
q1
- Quaternion.q2
- Quaternion.- Returns:
- the dot product of
q1
andq2
.
-
dot
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
Computes the normalized quaternion (the versor of the instance). The norm of the quaternion must not be near zero.- Returns:
- a normalized quaternion.
- Throws:
IllegalStateException
- if the norm of the quaternion is NaN, infinite, or near zero.
-
equals
-
hashCode
public int hashCode() -
equals
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
Returns the polar form of the quaternion.- Returns:
- the unit quaternion with positive scalar part.
-
negate
Returns the opposite of this instance.- Returns:
- the quaternion for which all components have an opposite sign to this one.
-
inverse
Returns the inverse of this instance. The norm of the quaternion must not be zero.- Returns:
- the inverse.
- Throws:
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:
-
getVectorPart
public double[] getVectorPart()Gets the three components of the vector part of the quaternion.- Returns:
- the vector part.
- See Also:
-
multiply
Multiplies the instance by a scalar.- Parameters:
alpha
- Scalar factor.- Returns:
- a scaled quaternion.
-
divide
Divides the instance by a scalar.- Parameters:
alpha
- Scalar factor.- Returns:
- a scaled quaternion.
-
parse
Parses a string that would be produced bytoString()
and instantiates the corresponding object.- Parameters:
s
- String representation.- Returns:
- an instance.
- Throws:
NumberFormatException
- if the string does not conform to the specification.
-
toString
-