# 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. d – Angular distance between rotation matrices 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. d – Chordal distance between matrices. 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. d – Distance or difference between arrays. 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. d – Deviation from identity matrix. 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) – d – Angle difference between given unit quaternions. 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. d – Cosine of inner products of quaternions. 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. d – Euclidean distance between given unit quaternions 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. d – Euclidean distance of inner products between given unit quaternions. float