org.biojava.nbio.structure.geometry

## Class 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

All Methods
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