org.biojava.nbio.structure.geometry

Class UnitQuaternions

java.lang.Object

org.biojava.nbio.structure.geometry.UnitQuaternions

public class UnitQuaternions
extends Object

UnitQuaternions is a static Class that contains methods for calculating and using unit quaternions. It assumes the use of Quat4d Class from vecmath to represent the unit quaternions, and it also implements some of the basic methods that the library is missing.

A Unit Quaternion is a four-dimensional vector used to describe a three-dimensional attitude representation (axis and angle of rotation). By definition, unit quaternions are always normalized, so their length is always 1.

Since:

5.0.0

Author:

Aleix Lafita

Method Summary

Modifier and Type	Method and Description
static double	angle(javax.vecmath.Quat4d q) Calculate the rotation angle component of the input unit quaternion.
static double	dotProduct(javax.vecmath.Quat4d q1, javax.vecmath.Quat4d q2) Compute the dot (inner) product of two quaternions.
static javax.vecmath.Quat4d	orientation(javax.vecmath.Point3d[] points) The orientation represents the rotation of the principal axes with respect to the axes of the coordinate system (unit vectors [1,0,0], [0,1,0] and [0,0,1]).
static double	orientationAngle(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved) The angle of the relative orientation of the two sets of points in 3D.
static double	orientationAngle(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved, boolean centered) The angle of the relative orientation of the two sets of points in 3D.
static double	orientationMetric(javax.vecmath.Point3d[] a, javax.vecmath.Point3d[] b) The orientation metric is obtained by comparing the quaternion orientations of the principal axes of each set of points in 3D.
static double	orientationMetric(javax.vecmath.Quat4d q1, javax.vecmath.Quat4d q2) The orientation metric is obtained by comparing two unit quaternion orientations.
static javax.vecmath.Quat4d	relativeOrientation(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved) Calculate the relative quaternion orientation of two arrays of points.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

orientationMetric

public static double orientationMetric(javax.vecmath.Point3d[] a,
                                       javax.vecmath.Point3d[] b)

The orientation metric is obtained by comparing the quaternion orientations of the principal axes of each set of points in 3D.

First, the quaternion orientation of each set of points is calculated using their principal axes with orientation(Point3d[]). Then, the two quaternions are compared using the method orientationMetric(Quat4d, Quat4d).

A requisite for this method to work properly is that both sets of points have to define the same shape (or very low RMSD), otherwise some of the principal axes might change or be inverted, resulting in an unreliable metric. For shapes with some deviations in their shape, use the metric orientationAngle(Point3d[], Point3d[]).

Parameters:

a - array of Point3d

b - array of Point3d

Returns:

the quaternion orientation metric

orientationMetric

public static double orientationMetric(javax.vecmath.Quat4d q1,
                                       javax.vecmath.Quat4d q2)

The orientation metric is obtained by comparing two unit quaternion orientations.

The two quaternions are compared using the formula: d(q1,q2) = arccos(|q1*q2|). The range of the metric is [0, Pi/2], where 0 means the same orientation and Pi/2 means the opposite orientation.

The formula is taken from: Huynh, D. Q. (2009). Metrics for 3D rotations: comparison and analysis. Journal of Mathematical Imaging and Vision, 35(2), 155–164. http://doi.org/10.1007/s10851-009-0161-2

Parameters:

q1 - quaternion as Quat4d object

q2 - quaternion as Quat4d object

Returns:

the quaternion orientation metric

orientation

public static javax.vecmath.Quat4d orientation(javax.vecmath.Point3d[] points)

The orientation represents the rotation of the principal axes with respect to the axes of the coordinate system (unit vectors [1,0,0], [0,1,0] and [0,0,1]).

The orientation can be expressed as a unit quaternion.

Parameters:

points - array of Point3d

Returns:

the orientation of the point cloud as a unit quaternion

angle

public static double angle(javax.vecmath.Quat4d q)

Calculate the rotation angle component of the input unit quaternion.

Parameters:

q - unit quaternion Quat4d

Returns:

the angle in radians of the input quaternion

orientationAngle

public static double orientationAngle(javax.vecmath.Point3d[] fixed,
                                      javax.vecmath.Point3d[] moved)

The angle of the relative orientation of the two sets of points in 3D. Equivalent to angle(Quat4d) of the unit quaternion obtained by relativeOrientation(Point3d[], Point3d[]).

The arrays of points need to be centered at the origin. To center the points use CalcPoint.center(Point3d[]).

Parameters:

fixed - array of Point3d, centered at origin. Original coordinates will not be modified.

moved - array of Point3d, centered at origin. Original coordinates will not be modified.

Returns:

the angle in radians of the relative orientation of the points, angle to rotate moved to bring it to the same orientation as fixed.

orientationAngle

public static double orientationAngle(javax.vecmath.Point3d[] fixed,
                                      javax.vecmath.Point3d[] moved,
                                      boolean centered)

The angle of the relative orientation of the two sets of points in 3D. Equivalent to angle(Quat4d) of the unit quaternion obtained by relativeOrientation(Point3d[], Point3d[]).

Parameters:

fixed - array of Point3d. Original coordinates will not be modified.

moved - array of Point3d. Original coordinates will not be modified.

centered - true if the points are already centered at the origin

Returns:

the angle in radians of the relative orientation of the points, angle to rotate moved to bring it to the same orientation as fixed.

relativeOrientation

public static javax.vecmath.Quat4d relativeOrientation(javax.vecmath.Point3d[] fixed,
                                                       javax.vecmath.Point3d[] moved)

Calculate the relative quaternion orientation of two arrays of points.

Parameters:

fixed - point array, coordinates will not be modified

moved - point array, coordinates will not be modified

Returns:

a unit quaternion representing the relative orientation, to rotate moved to bring it to the same orientation as fixed.

dotProduct

public static double dotProduct(javax.vecmath.Quat4d q1,
                                javax.vecmath.Quat4d q2)

Compute the dot (inner) product of two quaternions.

Parameters:

q1 - quaternion as Quat4d object

q2 - quaternion as Quat4d object

Returns:

the value of the quaternion dot product