Metrics

Common metrics used in 3D Orientation representations.

References

[Huynh](1, 2, 3, 4, 5) Huynh, D.Q. Metrics for 3D Rotations: Comparison and Analysis. J Math Imaging Vis 35, 155-164 (2009).
[Kuffner]Kuffner, J.J. Effective Sampling and Distance Metrics for 3D Rigid Body Path Planning. IEEE International Conference on Robotics and Automation (ICRA 2004)
[Hartley](1, 2, 3) R. Hartley, J. Trumpf, Y. Dai, H. Li. Rotation Averaging. International Journal of Computer Vision. Volume 101, Number 2. 2013.
ahrs.utils.metrics.angular_distance(R1: numpy.ndarray, R2: numpy.ndarray) → float

Angular distance between two rotations \(\mathbf{R}_1\) and \(\mathbf{R}_2\) in SO(3), as defined in [Hartley]:

\[d(\mathbf{R}_1, \mathbf{R}_2) = \|\log(\mathbf{R}_1\mathbf{R}_2^T)\|\]

where \(\|\mathbf{x}\|\) represents the usual euclidean norm of the vector \(\mathbf{x}\).

Parameters:
  • R1 (numpy.ndarray) – 3-by-3 rotation matrix.
  • R2 (numpy.ndarray) – 3-by-3 rotation matrix.
Returns:

d – Angular distance between rotation matrices
Return type:

float
ahrs.utils.metrics.chordal(R1: numpy.ndarray, R2: numpy.ndarray) → float

Chordal Distance

The chordal distance between two rotations \(\mathbf{R}_1\) and \(\mathbf{R}_2\) in SO(3) is the Euclidean distance between them in the embedding space \(\mathbb{R}^{3\times 3}=\mathbb{R}^9\) [Hartley]:

\[d(\mathbf{R}_1, \mathbf{R}_2) = \|\mathbf{R}_1-\mathbf{R}_2\|_F\]

where \(\|\mathbf{X}\|_F\) represents the Frobenius norm of the matrix \(\mathbf{X}\).

Parameters:
  • R1 (numpy.ndarray) – 3-by-3 rotation matrix.
  • R2 (numpy.ndarray) – 3-by-3 rotation matrix.
Returns:

d – Chordal distance between matrices.
Return type:

float
ahrs.utils.metrics.euclidean(x: numpy.ndarray, y: numpy.ndarray, **kwargs) → float

Euclidean distance between two arrays as described in [Huynh]:

\[d(\mathbf{x}, \mathbf{y}) = \sqrt{(x_0-y_0)^2 + \dots + (x_n-y_n)^2}\]

Accepts the same parameters as the function numpy.linalg.norm().

This metric gives values in the range [0, \(\pi\sqrt{3}\)]

Parameters:
  • x (array) – M-by-N array to compare. Usually a reference array.
  • y (array) – M-by-N array to compare.
  • mode (str) – Mode of distance computation.
Returns:

d – Distance or difference between arrays.
Return type:

float

Examples

>>> import numpy as np
>>> from ahrs.utils.metrics import euclidean
>>> num_samples = 5
>>> angles = np.random.uniform(low=-180.0, high=180.0, size=(num_samples, 3))
>>> noisy = angles + np.random.randn(num_samples, 3)
>>> euclidean(angles, noisy)
2.585672169476804
>>> euclidean(angles, noisy, axis=0)
array([1.36319772, 1.78554071, 1.28032688])
>>> euclidean(angles, noisy, axis=1)     # distance per sample
array([0.88956871, 1.19727356, 1.5243858 , 0.68765523, 1.29007067])
ahrs.utils.metrics.identity_deviation(R1: numpy.ndarray, R2: numpy.ndarray) → float

Deviation from Identity Matrix as defined in [Huynh]:

\[d(\mathbf{R}_1, \mathbf{R}_2) = \|\mathbf{I}-\mathbf{R}_1\mathbf{R}_2^T\|_F\]

where \(\|\mathbf{X}\|_F\) represents the Frobenius norm of the matrix \(\mathbf{X}\).

The error lies within: [0, \(2\sqrt{2}\)]

Parameters:
  • R1 (numpy.ndarray) – 3-by-3 rotation matrix.
  • R2 (numpy.ndarray) – 3-by-3 rotation matrix.
Returns:

d – Deviation from identity matrix.
Return type:

float
ahrs.utils.metrics.qad(q1: numpy.ndarray, q2: numpy.ndarray) → float

Quaternion Angle Difference

Parameters:
  • q1 (numpy.ndarray) – First quaternion, or set of quaternions, to compare.
  • q2 (numpy.ndarray) – Second quaternion, or set of quaternions, to compare.
  • error lies within (The) –
Returns:

d – Angle difference between given unit quaternions.
Return type:

float
ahrs.utils.metrics.qcip(q1: numpy.ndarray, q2: numpy.ndarray) → float

Cosine of inner products as defined in [Huynh]:

\[d(\mathbf{q}_1, \mathbf{q}_2) = \arccos(|\mathbf{q}_1\cdot\mathbf{q}_2|)\]

The error lies within: [0, \(\frac{\pi}{2}\)]

Parameters:
  • q1 (numpy.ndarray) – First quaternion, or set of quaternions, to compare.
  • q2 (numpy.ndarray) – Second quaternion, or set of quaternions, to compare.
Returns:

d – Cosine of inner products of quaternions.
Return type:

float
ahrs.utils.metrics.qdist(q1: numpy.ndarray, q2: numpy.ndarray) → float

Euclidean distance between two unit quaternions as defined in [Huynh] and [Hartley]:

\[d(\mathbf{q}_1, \mathbf{q}_2) = \mathrm{min} \{ \|\mathbf{q}_1-\mathbf{q}_2\|, \|\mathbf{q}_1-\mathbf{q}_2\|\}\]

The error lies within [0, \(\sqrt{2}\)]

Parameters:
  • q1 (numpy.ndarray) – First quaternion, or set of quaternions, to compare.
  • q2 (numpy.ndarray) – Second quaternion, or set of quaternions, to compare.
Returns:

d – Euclidean distance between given unit quaternions
Return type:

float
ahrs.utils.metrics.qeip(q1: numpy.ndarray, q2: numpy.ndarray) → float

Euclidean distance of inner products as defined in [Huynh] and [Kuffner]:

\[d(\mathbf{q}_1, \mathbf{q}_2) = 1 - |\mathbf{q}_1\cdot\mathbf{q}_2|\]

The error lies within: [0, 1]

Parameters:
  • q1 (numpy.ndarray) – First quaternion, or set of quaternions, to compare.
  • q2 (numpy.ndarray) – Second quaternion, or set of quaternions, to compare.
Returns:

d – Euclidean distance of inner products between given unit quaternions.
Return type:

float