Add quaternion_double

doc/source/api.rst

@@ -112,6 +112,7 @@ Quaternion and Axis-Angle Operations
 
    ~axis_angle_from_two_directions
    ~axis_angle_slerp
+   ~quaternion_double
    ~concatenate_quaternions
    ~q_prod_vector
    ~q_conj

pytransform3d/rotations/__init__.py

@@ -87,8 +87,9 @@
     mrp_from_quaternion,
     quaternion_from_mrp)
 from ._quaternion_operations import (
-    quaternion_integrate, quaternion_gradient, concatenate_quaternions, q_conj,
-    q_prod_vector, quaternion_diff, quaternion_dist, quaternion_from_euler)
+    quaternion_double, quaternion_integrate, quaternion_gradient,
+    concatenate_quaternions, q_conj, q_prod_vector, quaternion_diff,
+    quaternion_dist, quaternion_from_euler)
 from ._mrp import concatenate_mrp
 from ._slerp import (slerp_weights, pick_closest_quaternion, quaternion_slerp,
                      axis_angle_slerp, rotor_slerp)
@@ -218,6 +219,7 @@
     "cross_product_matrix",
     "mrp_from_quaternion",
     "quaternion_from_mrp",
+    "quaternion_double",
     "quaternion_integrate",
     "quaternion_gradient",
     "concatenate_quaternions",

pytransform3d/rotations/_quaternion_operations.py

@@ -6,6 +6,25 @@
     axis_angle_from_quaternion, quaternion_from_angle, check_axis_index)
 
 
+def quaternion_double(q):
+    """Create another quaternion that represents the same orientation.
+
+    The unit quaternions q and -q represent the same orientation (double
+    cover).
+
+    Parameters
+    ----------
+    q : array-like, shape (4,)
+        Unit quaternion.
+
+    Returns
+    -------
+    q_double : array, shape (4,)
+        -q
+    """
+    return -check_quaternion(q, unit=True)
+
+
 def quaternion_integrate(Qd, q0=np.array([1.0, 0.0, 0.0, 0.0]), dt=1.0):
     """Integrate angular velocities to quaternions.
 

pytransform3d/rotations/_quaternion_operations.pyi

@@ -2,6 +2,9 @@ import numpy as np
 import numpy.typing as npt
 
 
+def quaternion_double(q: npt.ArrayLike) -> np.ndarray: ...
+
+
 def quaternion_integrate(Qd: npt.ArrayLike, q0: npt.ArrayLike = ..., dt: float = ...) -> np.ndarray: ...
 
 

pytransform3d/test/test_rotations.py

@@ -1611,6 +1611,14 @@ def test_quaternion_invert():
     assert_array_almost_equal(pr.q_id, q_q_inv)
 
 
+def test_quaternion_double():
+    rng = np.random.default_rng(2235)
+    for _ in range(5):
+        q1 = pr.random_quaternion(rng)
+        q2 = pr.quaternion_double(q1)
+        pr.assert_quaternion_equal(q1, q2)
+
+
 def test_quaternion_gradient_integration():
     """Test integration of quaternion gradients."""
     n_steps = 21