org.jeometry.math.Quaternion Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jeometry-api Show documentation
Show all versions of jeometry-api Show documentation
Jeometry, a Mathematic and Geometry library for Java
package org.jeometry.math;
import org.jeometry.Jeometry;
/**
* This interface represents a quaternion.
* A quaternion q is a complex number defined such as:
*
* q = a + bi + cj + dk
*
* where (a, b, c, d) are real numbers and (i, j, k) are the fundamental quaternion units.
* Number a is called real part (or scalar part) of the quaternion and bi + cj + dk is called vector part (or imaginary part).
*
* A multiplicative group structure, called the {@link #mult(Quaternion) Hamilton product}, denoted by juxtaposition, can be defined on the quaternions in the following way:
*
* - The real quaternion 1 is the identity element.
*
- The real quaternions commute with all other quaternions, that is aq = qa for every quaternion q and every real quaternion a. In algebraic terminology this is to say that the field of real quaternions are the center of this quaternion algebra.
*
- The product is first given for the basis elements (see next subsection), and then extended to all quaternions by using the distributive property and the center property of the real quaternions. The Hamilton product is not commutative, but associative, thus the quaternions form an associative algebra over the reals.
*
- Additionally, every nonzero quaternion has an inverse with respect to the {@link #mult(Quaternion) Hamilton product}, thus the quaternions form a division algebra.
*
*
* A quaternion can be expressed as a {@link Vector vector} of real numbers q = (a, b, c, d).
*
* Within 3D computation domain, a quaternion can be represented as a vector of real number defined such as:
*
* q = (w, x, y, z)
*
* Where parameters (w, x, y, z) correspond to (a, b, c, d) from the mathematical form.
*
* @author Julien Seinturier - COMEX S.A. - [email protected] - https://github.com/jorigin/jeometry
* @version {@value Jeometry#version} b{@value Jeometry#BUILD}
* @since 1.0.0
*/
public interface Quaternion extends Vector{
/**
* The index of the real part (or scalar part) of a quaternion within an array od numbers.
* @see #QUATERNION_I_COMPONENT
* @see #QUATERNION_J_COMPONENT
* @see #QUATERNION_K_COMPONENT
*/
public static int QUATERNION_SCALAR_COMPONENT = 0;
/**
* The index of the i basis component of the quaternion vector part (or imaginary part) component.
* This component is denoted b with q = a + bi + cj + dk
.
* @see #QUATERNION_SCALAR_COMPONENT
* @see #QUATERNION_J_COMPONENT
* @see #QUATERNION_K_COMPONENT
*/
public static int QUATERNION_I_COMPONENT = 1;
/**
* The index of the j basis component of the quaternion vector part (or imaginary part) component.
* This component is denoted c with q = a + bi + cj + dk
.
* @see #QUATERNION_SCALAR_COMPONENT
* @see #QUATERNION_I_COMPONENT
* @see #QUATERNION_K_COMPONENT
*/
public static int QUATERNION_J_COMPONENT = 2;
/**
* The index of the k basis component of the quaternion vector part (or imaginary part) component.
* This component is denoted d with q = a + bi + cj + dk
.
* @see #QUATERNION_SCALAR_COMPONENT
* @see #QUATERNION_I_COMPONENT
* @see #QUATERNION_J_COMPONENT
*/
public static int QUATERNION_K_COMPONENT = 3;
/**
* Get the quaternion real part (or scalar) parameter, denoted a within the definition
* q = a + bi + cj + dk.
* @return the quaternion real part (or scalar) parameter.
* @see #getI()
* @see #getJ()
* @see #getK()
* @see #setScalar(double)
*/
public double getScalar();
/**
* Set the quaternion real part (or scalar) parameter, denoted a within the definition
* q = a + bi + cj + dk.
* @param a the quaternion real part (or scalar) parameter.
* @see #setI(double)
* @see #setJ(double)
* @see #setK(double)
* @see #getScalar()
*/
public void setScalar(double a);
/**
* Get the i basis component of the quaternion vector part (or imaginary part) parameter, denoted b within the definition
* q = a + bi + cj + dk.
* @return the first component of the quaternion vector part (or imaginary part) parameter.
* @see #getScalar()
* @see #getJ()
* @see #getK()
* @see #setI(double)
*/
public double getI();
/**
* Set the i basis component of the quaternion vector part (or imaginary part) parameter, denoted b within the definition
* q = a + bi + cj + dk.
* @param value the first component of the quaternion vector part (or imaginary part) parameter.
* @see #setScalar(double)
* @see #setJ(double)
* @see #setK(double)
* @see #getI()
*/
public void setI(double value);
/**
* Get the j basis component of the quaternion vector part (or imaginary part) parameter, denoted c within the definition
* q = a + bi + cj + dk.
* @return the second component of the quaternion vector part (or imaginary part) parameter.
* @see #getScalar()
* @see #getI()
* @see #getK()
* @see #setJ(double)
*/
public double getJ();
/**
* Set the j basis component of the quaternion vector part (or imaginary part) parameter, denoted c within the definition
* q = a + bi + cj + dk.
* @param value the second component of the quaternion vector part (or imaginary part) parameter.
* @see #setScalar(double)
* @see #setI(double)
* @see #setK(double)
* @see #getJ()
*/
public void setJ(double value);
/**
* Get the k basis component of the quaternion vector part (or imaginary part) parameter, denoted d within the definition
* q = a + bi + cj + dk.
* @return the third component of the quaternion vector part (or imaginary part) parameter.
* @see #getScalar()
* @see #getI()
* @see #getJ()
* @see #setK(double)
*/
public double getK();
/**
* Set the k basis component of the quaternion vector part (or imaginary part) parameter, denoted d within the definition
* q = a + bi + cj + dk.
* @param value the third component of the quaternion vector part (or imaginary part) parameter.
* @see #setScalar(double)
* @see #setI(double)
* @see #setJ(double)
* @see #getK()
*
*/
public void setK(double value);
/**
* Get the components that compose the quaternion. The output is an array of double, denoted components such as:
*
* components[{@link #QUATERNION_SCALAR_COMPONENT}] = a;
* components[{@link #QUATERNION_I_COMPONENT}] = b;
* components[{@link #QUATERNION_J_COMPONENT}] = c;
* components[{@link #QUATERNION_K_COMPONENT}] = d;
*
* with q = a + bi + cj + dk.
* The components are stored within the given components array.
* @return a reference to the components array.
*/
public double[] getValues();
/**
* Get the components that compose the quaternion. The output is an array of double, denoted components such as:
*
* components[{@link #QUATERNION_SCALAR_COMPONENT}] = a;
* components[{@link #QUATERNION_I_COMPONENT}] = b;
* components[{@link #QUATERNION_J_COMPONENT}] = c;
* components[{@link #QUATERNION_K_COMPONENT}] = d;
*
* with q = a + bi + cj + dk.
* The components are stored within the given components array.
* @param components the double array that store the result.
* @return a reference to the components array.
* @throws IllegalArgumentException if the components array is null or have a size that in inferior to 4.
*/
public double[] getValues(double[] components) throws IllegalArgumentException;
/**
* Set all the components of the quaternion. The components are such that:
* q = a + bi + cj + dk.
* @param a the quaternion real part (or scalar) parameter.
* @param b the first component of the quaternion vector part (or imaginary part) parameter.
* @param c the second component of the quaternion vector part (or imaginary part) parameter.
* @param d the third component of the quaternion vector part (or imaginary part) parameter.
*/
public void setComponents(double a, double b, double c, double d);
/**
* Compute the product (called Hamilton product) of this quaternion with the quaternion q.
* Let q1 = a1 + b1i + c1j + d1k and
* q2 = a2 + b2i + c2j + d2k two quaternions.
* The product q1×q2 is such that:
* $$
* \begin{array}{rcl}
* q_{1}\times{}q_{2} & = & a_{1}a_{2} + a_{1}b_{2}i + a_{1}c_{2}j + a_{1}d_{2}k \\
* & + & b_{1}a_{2}i + b_{1}b_{2}i^{2} + b_{1}c_{2}ij + b_{1}d_{2}ik \\
* & + & c_{1}a_{2}j + c_{1}b_{2}ji + c_{1}c_{2}j^{2} + c_{1}d_{2}jk \\
* & + & d_{1}a_{2}k + d_{1}b_{2}ki + d_{1}c_{2}kj + d_{1}d_{2}k^{2} \\
* \end{array}
* $$
* Using the quaternion product property i2 = j2k2ijk = -1 previous result can be expressed such as:
* $$
* \begin{array}{rcl}
* q_{1}\times{}q_{2} & = & (a_{1}a_{2} - b_{1}b_{2} - c_{1}c_{2} - d_{1}d_{2}) \\
* & + & (a_{1}b_{2} + b_{1}a_{2} + c_{1}d_{2} - d_{1}c_{2})i \\
* & + & (a_{1}c_{2} - b_{1}d_{2} + c_{1}a_{2} + d_{1}b_{2})j \\
* & + & (a_{1}d_{2} + b_{1}c_{2} + c_{1}b_{2} + d_{1}a_{2})k \\
* \end{array}
* $$
* @param p the quaternion to multiply.
* @return the product (called Hamilton product) of this quaternion with p.
*/
public Quaternion mult(Quaternion p);
/**
* Compute the product (called Hamilton product) of this quaternion with the quaternion q.
* Let q1 = a1 + b1i + c1j + d1k and
* q2 = a2 + b2i + c2j + d2k two quaternions.
* The product q1×q2 is such that:
* $$
* \begin{array}{rcl}
* q_{1}\times{}q_{2} & = & a_{1}a_{2} + a_{1}b_{2}i + a_{1}c_{2}j + a_{1}d_{2}k \\
* & + & b_{1}a_{2}i + b_{1}b_{2}i^{2} + b_{1}c_{2}ij + b_{1}d_{2}ik \\
* & + & c_{1}a_{2}j + c_{1}b_{2}ji + c_{1}c_{2}j^{2} + c_{1}d_{2}jk \\
* & + & d_{1}a_{2}k + d_{1}b_{2}ki + d_{1}c_{2}kj + d_{1}d_{2}k^{2} \\
* \end{array}
* $$
* Using the quaternion product property i2 = j2k2ijk = -1 previous result can be expressed such as:
* $$
* \begin{array}{rcl}
* q_{1}\times{}q_{2} & = & (a_{1}a_{2} - b_{1}b_{2} - c_{1}c_{2} - d_{1}d_{2}) \\
* & + & (a_{1}b_{2} + b_{1}a_{2} + c_{1}d_{2} - d_{1}c_{2})i \\
* & + & (a_{1}c_{2} - b_{1}d_{2} + c_{1}a_{2} + d_{1}b_{2})j \\
* & + & (a_{1}d_{2} + b_{1}c_{2} + c_{1}b_{2} + d_{1}a_{2})k \\
* \end{array}
* $$
* @param p the quaternion to multiply.
* @param result the quaternion that store the product (called Hamilton product) of this quaternion with p.
* @return the same reference as result.
*/
public Quaternion mult(Quaternion p, Quaternion result);
/**
* Compute the product (called Hamilton product) of this quaternion with the quaternion q and store the result within this quaternion.
* Let q1 = a1 + b1i + c1j + d1k and
* q2 = a2 + b2i + c2j + d2k two quaternions.
* The product q1×q2 is such that:
* $$
* \begin{array}{rcl}
* q_{1}\times{}q_{2} & = & a_{1}a_{2} + a_{1}b_{2}i + a_{1}c_{2}j + a_{1}d_{2}k \\
* & + & b_{1}a_{2}i + b_{1}b_{2}i^{2} + b_{1}c_{2}ij + b_{1}d_{2}ik \\
* & + & c_{1}a_{2}j + c_{1}b_{2}ji + c_{1}c_{2}j^{2} + c_{1}d_{2}jk \\
* & + & d_{1}a_{2}k + d_{1}b_{2}ki + d_{1}c_{2}kj + d_{1}d_{2}k^{2} \\
* \end{array}
* $$
* Using the quaternion product property i2 = j2k2ijk = -1 previous result can be expressed such as:
* $$
* \begin{array}{rcl}
* q_{1}\times{}q_{2} & = & (a_{1}a_{2} - b_{1}b_{2} - c_{1}c_{2} - d_{1}d_{2}) \\
* & + & (a_{1}b_{2} + b_{1}a_{2} + c_{1}d_{2} - d_{1}c_{2})i \\
* & + & (a_{1}c_{2} - b_{1}d_{2} + c_{1}a_{2} + d_{1}b_{2})j \\
* & + & (a_{1}d_{2} + b_{1}c_{2} + c_{1}b_{2} + d_{1}a_{2})k \\
* \end{array}
* $$
* @param p the quaternion to multiply.
* @return a reference on this object (can be useful for computation chaining).
*/
public Quaternion multAffect(Quaternion p);
/**
* Invert this quaternion with respect to the {@link #mult(Quaternion) Hamilton product}.
* Let q = a + bi + cj + dk a non zero quaternion.
* Its inverse, denoted q-1 is such that:
* $$
* q^{-1}\ =\ \frac{1}{a^{2}+b^{2}+c^{2}+d^{2}}(a-bi-cj-dk)
* $$
* If the quaternion is equals to 0, an {@link IllegalStateException} is raised as it is not invertible.
* @return the inverse of this quaternion with respect to the {@link #mult(Quaternion) Hamilton product}.
* @throws IllegalStateException if this quaternion is equals to 0.
*/
public Quaternion invertQuaternion() throws IllegalStateException;
/**
* Invert this quaternion with respect to the {@link #mult(Quaternion) Hamilton product}.
* Let q = a + bi + cj + dk a non zero quaternion.
* Its inverse, denoted q-1 is such that:
* $$
* q^{-1}\ =\ \frac{1}{a^{2}+b^{2}+c^{2}+d^{2}}(a-bi-cj-dk)
* $$
* If the quaternion is equals to 0, an {@link IllegalStateException} is raised as it is not invertible.
* @param result a quaternion that can store the inverse of this quaternion with respect to the {@link #mult(Quaternion) Hamilton product}.
* @return the same reference as result.
* @throws IllegalStateException if this quaternion is equals to 0.
*/
public Quaternion invertQuaternion(Quaternion result) throws IllegalStateException;
/**
* Change this quaternion by its inverse with respect to the {@link #mult(Quaternion) Hamilton product}.
* Let q = a + bi + cj + dk a non zero quaternion.
* Its inverse, denoted q-1 is such that:
* $$
* q^{-1}\ =\ \frac{1}{a^{2}+b^{2}+c^{2}+d^{2}}(a-bi-cj-dk)
* $$
* If the quaternion is equals to 0, an {@link IllegalStateException} is raised as it is not invertible.
* @return a reference on this quaternion.
* @throws IllegalStateException if this quaternion is equals to 0.
*/
public Quaternion invertQuaternionAffect() throws IllegalStateException;
/**
* Compute the conjugate of this quaternion.
* Let q = a + bi + cj + dk a quaternion.
* Its conjugate, denoted q* is the quaternion such as q* = a - bi - cj - dk
* @return the conjugate of this quaternion.
*/
public Quaternion conjugateQuaternion();
/**
* Compute the conjugate of this quaternion and store it within the given result.
* Let q = a + bi + cj + dk a quaternion.
* Its conjugate, denoted q* is the quaternion such as q* = a - bi - cj - dk
* @param result the quaternion that has to store the result.
* @return the conjugate of this quaternion.
*/
public Quaternion conjugateQuaternion(Quaternion result);
/**
* Change this quaternion by its conjugate.
* Let q = a + bi + cj + dk a quaternion.
* Its conjugate, denoted q* is the quaternion such as q* = a - bi - cj - dk
* @return a reference on this object.
*/
public Quaternion conjugateQuaternionAffect();
/**
* Compute the quaternion that is the sum, component by component of this quaternion and the given scalar.
*
* More formally, let q = a + bi + cj + dk be this quaternion and let s the scalar given in parameter, this method compute the quaternion r such that:
* r = a+s + (b+s)i + (c+s)j + (d+s)k
*
* @param scalar the scalar to add to this quaternion
* @param result the quaternion that holds the result
* @return the quaternion that is the sum, component by component of this quaternion and the given scalar
*/
public Quaternion plus(double scalar, Quaternion result);
/**
* Compute the quaternion that is the difference, component by component of this quaternion and the given scalar.
*
* More formally, let q = a + bi + cj + dk be this quaternion and let s the scalar given in parameter, this method compute the quaternion r such that:
* r = a-s + (b-s)i + (c-s)j + (d-s)k
*
* @param scalar the scalar to subtract to this quaternion
* @param result the quaternion that holds the result
* @return the quaternion that is the difference, component by component of this quaternion and the given scalar
*/
public Quaternion minus(double scalar, Quaternion result);
/**
* Compute the quaternion that is the product, component by component of this quaternion and the given scalar.
*
* More formally, let q = a + bi + cj + dk be this quaternion and let s the scalar given in parameter, this method compute the quaternion r such that:
* r = a×s + (b×s)i + (c×s)j + (d×s)k
*
* @param scalar the scalar to multiply to this quaternion
* @param result the quaternion that holds the result
* @return the quaternion that is the product, component by component of this quaternion and the given scalar
*/
public Quaternion multiply(double scalar, Quaternion result);
/**
* Compute the quaternion that is the division, component by component of this quaternion and the given scalar.
*
* More formally, let q = a + bi + cj + dk be this quaternion and let s the scalar given in parameter, this method compute the quaternion r such that:
* r = a/s + (b/s)i + (c/s)j + (d/s)k
*
* @param scalar the scalar to divide to this quaternion
* @param result the quaternion that holds the result
* @return the quaternion that is the division, component by component of this quaternion and the given scalar
*/
public Quaternion divide(double scalar, Quaternion result);
@Override
public Quaternion plus(double scalar);
@Override
public Quaternion plusAffect(double scalar);
@Override
public Quaternion minus(double scalar);
@Override
public Quaternion minusAffect(double scalar);
@Override
public Quaternion divide(double scalar);
@Override
public Quaternion divideAffect(double scalar);
}