Kanzi Framework  3.9.0
Java API
Quaternion Class Reference

Quaternions represent rotation around an axis, defined by quaternion components x, y, z and w. More...

Inheritance diagram for Quaternion:
[legend]

Public Member Functions

 Quaternion (long cPtr, boolean cMemoryOwn)
 
 Quaternion ()
 Default constructor, initializes the quaternion components to identity, representing no rotation (x=0, y=0, z=0, w=1).
 
 Quaternion (float x, float y, float z, float w)
 Constructor, initializes the quaternion components to x, y, z and w. More...
 
Quaternion conjugated ()
 Get conjugated copy of this quaternion. More...
 
synchronized void delete ()
 
Quaternion divideByScalar (float scalar)
 Divides each quaternion component with a scalar and returns the result. More...
 
boolean equals (Object obj)
 
float get (long index)
 Returns individual quaternion element value at index. More...
 
float getW ()
 Get the w component of the quaternion. More...
 
float getX ()
 Get the x component of the quaternion. More...
 
float getY ()
 Get the y component of the quaternion. More...
 
float getZ ()
 Get the z component of the quaternion. More...
 
Quaternion multiplyByScalar (float scalar)
 Multiplies each quaternion component with a scalar. More...
 
Quaternion normalized ()
 Get normalized copy of this quaternion. More...
 
void set (long index, float v)
 Sets the individual quaternion element at index to value. More...
 
void setW (float w)
 Sets the w component of the quaternion. More...
 
void setX (float x)
 Sets the x component of the quaternion. More...
 
void setY (float y)
 Sets the y component of the quaternion. More...
 
void setZ (float z)
 Sets the z component of the quaternion. More...
 

Static Public Member Functions

static Vector3 calculateEulerAngles (Quaternion quaternion)
 Calculates Euler angles from a quaternion. More...
 
static Quaternion componentWiseMultiply (Quaternion q1, Quaternion q2)
 Multiplies quaternion components component-wise and returns the resulting quaternion. More...
 
static Quaternion createFromEulerAngles (Vector3 anglesInRadians)
 Creates a quaternion from Euler angles. More...
 
static Quaternion createFromEulerAngles (float rotationX, float rotationY, float rotationZ)
 Creates a quaternion from Euler angles. More...
 
static Quaternion createFromVector (Vector3 axis, float angleInRadians)
 Creates quaternion from axis and angle. More...
 
static Quaternion divide (Quaternion q, float scalar)
 Divides each quaternion component with a scalar and returns the result. More...
 
static float dotProduct (Quaternion q1, Quaternion q2)
 Calculates the dot product of two quaternions. More...
 
static long getCPtr (Quaternion obj)
 
static Quaternion inverse (Quaternion q)
 Returns an inverse quaternion for a quaternion. More...
 
static Quaternion matrix4x4ToQuaternion (Matrix4x4 matrix)
 Creates a quaternion from Matrix4x4. More...
 
static Quaternion multiply (Quaternion q, float scalar)
 Multiplies each quaternion component with a scalar. More...
 
static Quaternion multiply (Quaternion left, Quaternion right)
 Multiplies two quaternions. More...
 
static Quaternion quaternionSlerp (Quaternion q1, Quaternion q2, float interpolationTime)
 Applies spherical linear interpolation (slerp) to two quaternions using the shortest path. More...
 
static Quaternion quaternionSlerpLongerPath (Quaternion q1, Quaternion q2, float interpolationTime)
 Applies spherical linear interpolation (slerp) to two quaternion using the longer path. More...
 
static Matrix4x4 quaternionToMatrix4x4 (Quaternion quaternion)
 Converts a quaternion rotation to a 4x4 rotation matrix. More...
 
static Vector3 rotateVector (Quaternion quaternion, Vector3 vector)
 Applies quaternion rotation to a vector. More...
 

Protected Member Functions

void finalize ()
 

Protected Attributes

transient boolean swigCMemOwn
 

Detailed Description

Quaternions represent rotation around an axis, defined by quaternion components x, y, z and w.


Quaternions are compact, do not suffer from gimbal lock and can be easily interpolated.
Kanzi Engine uses quaternions internally to represent all rotations.
Quaternions are based on complex numbers and are not easy to understand intuitively. You almost never access or modify the individual components.
In most cases you take existing rotations and use them to construct new rotations (e.g. to smoothly interpolate between two rotations).
You can use the Quaternion operator * to rotate one rotation by another, or to rotate a vector by a rotation.

See also
operator*().
rotateVector().

Constructor & Destructor Documentation

◆ Quaternion()

Quaternion ( float  x,
float  y,
float  z,
float  w 
)

Constructor, initializes the quaternion components to x, y, z and w.


Parameters
xx component of the quaternion.
yy component of the quaternion.
zz component of the quaternion.
ww component of the quaternion.

Member Function Documentation

◆ calculateEulerAngles()

static Vector3 calculateEulerAngles ( Quaternion  quaternion)
static

Calculates Euler angles from a quaternion.


Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y, and z.

Returns
Euler angles in radians.

◆ componentWiseMultiply()

static Quaternion componentWiseMultiply ( Quaternion  q1,
Quaternion  q2 
)
static

Multiplies quaternion components component-wise and returns the resulting quaternion.


Parameters
q1The first quaternion.
q2The second quaternion.
Returns
The result quaternion.

◆ conjugated()

Quaternion conjugated ( )

Get conjugated copy of this quaternion.

Conjugation inverses the quaternion axis components x, y and z.
Use this to get the inverse rotation of a quaternion.

Returns
Conjugated quaternion.

◆ createFromEulerAngles() [1/2]

static Quaternion createFromEulerAngles ( Vector3  anglesInRadians)
static

Creates a quaternion from Euler angles.


Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y and z.

Parameters
anglesInRadiansEuler angles in radians.
Returns
Rotated quaternion.

◆ createFromEulerAngles() [2/2]

static Quaternion createFromEulerAngles ( float  rotationX,
float  rotationY,
float  rotationZ 
)
static

Creates a quaternion from Euler angles.


Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y and z.

Parameters
rotationXRotation angle around the x axis in radians.
rotationYRotation angle around the y axis in radians.
rotationZRotation angle around the z axis in radians.
Returns
Rotated quaternion.

◆ createFromVector()

static Quaternion createFromVector ( Vector3  axis,
float  angleInRadians 
)
static

Creates quaternion from axis and angle.

Use this to create a quaternion from axis of rotation and angle in radians.

Parameters
axisAxis components in Vector3(x, y, z).
angleInRadiansAngle in radians.
Returns
Rotated quaternion.

◆ divide()

static Quaternion divide ( Quaternion  q,
float  scalar 
)
static

Divides each quaternion component with a scalar and returns the result.


Parameters
qQuaternion to divide.
scalarDivisor for each quaternion component.
Returns
Result quaternion.

◆ divideByScalar()

Quaternion divideByScalar ( float  scalar)

Divides each quaternion component with a scalar and returns the result.


Parameters
scalarDivisor for each quaternion component.
Returns
Result quaternion.

◆ dotProduct()

static float dotProduct ( Quaternion  q1,
Quaternion  q2 
)
static

Calculates the dot product of two quaternions.


Parameters
q1The first quaternion.
q2The second quaternion.
Returns
The dot product of the quaternions.

◆ get()

float get ( long  index)

Returns individual quaternion element value at index.


Returns
The quaternion element value at index.

◆ getW()

float getW ( )

Get the w component of the quaternion.


Returns
The w component.

◆ getX()

float getX ( )

Get the x component of the quaternion.


Returns
The x component.

◆ getY()

float getY ( )

Get the y component of the quaternion.


Returns
The y component.

◆ getZ()

float getZ ( )

Get the z component of the quaternion.


Returns
The z component.

◆ inverse()

static Quaternion inverse ( Quaternion  q)
static

Returns an inverse quaternion for a quaternion.


Parameters
qQuaternion to invert.
Returns
Inverse quaternion.

◆ matrix4x4ToQuaternion()

static Quaternion matrix4x4ToQuaternion ( Matrix4x4  matrix)
static

Creates a quaternion from Matrix4x4.

Extracts and calculates the quaternion components from passed in Matrix4x4.
Use this when you already have the rotation stored in a 4x4 matrix and want to extract the rotation angles to a quaternion.

Parameters
matrixMatrix4x4 from which to extract and calculate the quaternion components.
Returns
Rotated and normalized quaternion.

◆ multiply() [1/2]

static Quaternion multiply ( Quaternion  q,
float  scalar 
)
static

Multiplies each quaternion component with a scalar.


Parameters
qQuaternion to multiply.
scalarMultiplier for each quaternion component.
Returns
This quaternion.

◆ multiply() [2/2]

static Quaternion multiply ( Quaternion  left,
Quaternion  right 
)
static

Multiplies two quaternions.

You can combine a quaternion rotations by multiplying them:
rotating a vector v by quaternion q1 * q2 is the same as rotating the vector first by q2 and then by q1.

Returns
Multiplied quaternion.

◆ multiplyByScalar()

Quaternion multiplyByScalar ( float  scalar)

Multiplies each quaternion component with a scalar.


Parameters
scalarMultiplier for each quaternion component.
Returns
This quaternion.

◆ normalized()

Quaternion normalized ( )

Get normalized copy of this quaternion.

Normalized quaternion is called an unit quaternion.
Calculates the magnitude from the dot product of the quaternion components, and divides all the quaternion components with the magnitude.
Use this when rotating or transforming a vector with a quaternion, and when generating a rotation or transformation matrix from quaternion.
Using unnormalized quaternion in calculations can lead to floating point rounding errors. The errors that result from using an unnormalized
quaternion in calculations are proportional to the square of the quaternion's magnitude.

Returns
Normalized quaternion.

◆ quaternionSlerp()

static Quaternion quaternionSlerp ( Quaternion  q1,
Quaternion  q2,
float  interpolationTime 
)
static

Applies spherical linear interpolation (slerp) to two quaternions using the shortest path.

Use this to evaluate interpolation between two rotations at given interpolation time.
Takes the shortest path of interpolation between two degrees, which amounts to maximum of 180 degrees of rotation in any direction.

Parameters
q1First quaternion.
q2Second quaternion.
interpolationTimeInterpolation parameter in range [0 .. 1].
Returns
Interpolated rotated quaternion.

◆ quaternionSlerpLongerPath()

static Quaternion quaternionSlerpLongerPath ( Quaternion  q1,
Quaternion  q2,
float  interpolationTime 
)
static

Applies spherical linear interpolation (slerp) to two quaternion using the longer path.

Use this to evaluate interpolation between two rotations at given interpolation time.
Takes the longer path to the result. Interpolates the whole angle difference between the two quaternion rotations. For example, from 0 to 270 rotates the whole 270 degrees.

Parameters
q1First quaternion.
q2Second quaternion.
interpolationTimeInterpolation parameter in range [0 .. 1].
Returns
Interpolated rotated quaternion.

◆ quaternionToMatrix4x4()

static Matrix4x4 quaternionToMatrix4x4 ( Quaternion  quaternion)
static

Converts a quaternion rotation to a 4x4 rotation matrix.


Parameters
quaternionQuaternion rotation.
Returns
Matrix4x4 with rotation values extracted from quaternion.

◆ rotateVector()

static Vector3 rotateVector ( Quaternion  quaternion,
Vector3  vector 
)
static

Applies quaternion rotation to a vector.

Calculates q * v * q.conjugated(), for a quaternion q and a vector v.

Parameters
quaternionQuaternion rotation.
vectorVector that you want to rotate.
Returns
The rotated vector.

◆ set()

void set ( long  index,
float  v 
)

Sets the individual quaternion element at index to value.


Parameters
indexQuaternion element index to set.

◆ setW()

void setW ( float  w)

Sets the w component of the quaternion.


Parameters
wThe new value of the w component.

◆ setX()

void setX ( float  x)

Sets the x component of the quaternion.


Parameters
xThe new value of the x component.

◆ setY()

void setY ( float  y)

Sets the y component of the quaternion.


Parameters
yThe new value of the y component.

◆ setZ()

void setZ ( float  z)

Sets the z component of the quaternion.


Parameters
zThe new value of the z component.