describe format of quaternion coefficents returned by .vec

petercorke · petercorke · commit 1ef54aa55abc · 2021-04-18T12:41:35.000+10:00
Add variant .vec_xyzs to return in three.js friendly order
diff --git a/spatialmath/quaternion.py b/spatialmath/quaternion.py
@@ -216,6 +216,9 @@ def vec(self):
             - 1, return a NumPy array shape=(4,)
             - N>1, return a NumPy array shape=(N,4).
 
+        The quaternion coefficients are in the order (s, vx, vy, vz), ie. with
+        the scalar (real part) first.
+
         Example:
 
         .. runblock:: pycon
@@ -229,6 +232,36 @@ def vec(self):
         else:
             return np.array([q._A for q in self])
 
+    @property
+    def vec_xyzs(self):
+        """
+        Quaternion as a vector
+
+        :return: quaternion expressed as a 4-vector
+        :rtype: numpy ndarray, shape=(4,)
+
+        ``q.vec`` is the quaternion as a vector.  If `len(q)` is:
+
+            - 1, return a NumPy array shape=(4,)
+            - N>1, return a NumPy array shape=(N,4).
+
+        The quaternion coefficients are in the order (vx, vy, vz, s), ie. with
+        the scalar (real part) last. This is useful when exporting to other
+        packages like three.js or pybullet.
+
+        Example:
+
+        .. runblock:: pycon
+
+            >>> from spatialmath import Quaternion
+            >>> Quaternion([1,2,3,4]).vec_xyzs
+            >>> Quaternion([np.r_[1,2,3,4], np.r_[5,6,7,8]]).vec_xyzs
+        """
+        if len(self) == 1:
+            return self._A
+        else:
+            return np.array([q._A for q in self])
+
     @property
     def matrix(self):
         """
