fix(quaternion): make __imatmul__ actually normalize

Quaternion.__imatmul__'s own docstring claimed `q1 @= q2` sets
`q1 := qnorm(q1 * q2)`, but the implementation just delegated to
__mul__ - identical to plain *=, no normalization at all, contradicting
both the docstring and the entire point of adding a separate @=
operator. UnitQuaternion.__matmul__ (pre-existing, unchanged) already
does this correctly via smb.qunit(smb.qqmul(x, y)) - qunit being the
normalizer; qnorm just returns the scalar magnitude, so it was never
actually the right function despite the docstring's wording.

Fixed by having __imatmul__ delegate to `left @ right` instead of
left.__mul__(right). Deliberately not left.__matmul__(right): plain
Quaternion has no __matmul__ (only UnitQuaternion defines one, with
normalization), and calling the dunder directly as a plain attribute
bypasses Python's normal operator fallback, raising a confusing
AttributeError instead of the same TypeError `q1 @ q2` already raises
for plain Quaternion. `left @ right` matches @'s behaviour exactly in
both cases: normalizes for UnitQuaternion, raises consistently for
Quaternion. Also fixed the docstring's `-> bool` return type (should
be `-> Quaternion`) and its example, which used Quaternion.Eul() - a
method that only exists on UnitQuaternion.

Tests: added @= coverage for UnitQuaternion (must match @, not *) and
for plain Quaternion (must raise TypeError, matching @, not silently
degrade to *=).

Author: petercorke

spatialmath/quaternion.py

@@ -670,29 +670,37 @@ def __imul__(
 
     def __imatmul__(
         left, right: Quaternion
-    ) -> bool:  # lgtm[py/not-named-self] pylint: disable=no-self-argument
+    ) -> Quaternion:  # lgtm[py/not-named-self] pylint: disable=no-self-argument
         """
         Overloaded ``@=`` operator
 
         :return: product
         :rtype: Quaternion
         :raises: ValueError
 
-        ``q1 @= q2`` sets ``q1 := qnorm(q1 * q2`)`
+        ``q1 @= q2`` sets ``q1 := qnorm(q1 * q2)``. Only meaningful for
+        ``UnitQuaternion``, which is the only subclass defining ``__matmul__``
+        (with normalization) that this delegates to; on a plain ``Quaternion``
+        this raises the same ``TypeError`` that ``q1 @ q2`` would.
 
         Example:
 
         .. runblock:: pycon
 
-            >>> from spatialmath import Quaternion
+            >>> from spatialmath import UnitQuaternion
             >>> q = UnitQuaternion.Eul([0.1, 0.2, 0.3])
-            >>> q @= Quaternion.Eul([0.3, 0.4, 0.5])
+            >>> q @= UnitQuaternion.Eul([0.3, 0.4, 0.5])
             >>> print(q)
 
 
-        :seealso: :func:`__mul__`
+        :seealso: :func:`__matmul__`
         """
-        return left.__mul__(right)
+        # NOT left.__matmul__(right): Quaternion itself has no __matmul__
+        # (only UnitQuaternion defines one), and calling the dunder
+        # directly as a plain attribute skips Python's normal operator
+        # fallback, raising a confusing AttributeError instead of the
+        # TypeError that `left @ right` raises consistently.
+        return left @ right
 
     def __pow__(self, n: int) -> Quaternion:
         """

tests/test_pose3d.py

@@ -419,6 +419,11 @@ def test_arith(self):
         self.assertIsInstance(R, SO3)
         array_compare(R, rotx(pi / 2))
 
+        R = SO3()
+        R @= SO3.Rx(pi / 2)
+        self.assertIsInstance(R, SO3)
+        array_compare(R, rotx(pi / 2))
+
         R = SO3()
         R *= 2
         self.assertNotIsInstance(R, SO3)
@@ -1078,6 +1083,13 @@ def test_arith(self):
             T, np.array([[0, 0, 1, 1], [0, 1, 0, 2], [-1, 0, 0, 3], [0, 0, 0, 1]])
         )
 
+        T = SE3(1, 2, 3)
+        T @= SE3.Ry(pi / 2)
+        self.assertIsInstance(T, SE3)
+        array_compare(
+            T, np.array([[0, 0, 1, 1], [0, 1, 0, 2], [-1, 0, 0, 3], [0, 0, 0, 1]])
+        )
+
         T = SE3()
         T *= 2
         self.assertNotIsInstance(T, SE3)

tests/test_quaternion.py

@@ -507,6 +507,11 @@ def test_matmul(self):
             UnitQuaternion([ry * rx, rz * ry, rx * rz]),
         )
 
+        # @= is @ as an augmented assignment, not *=
+        q = rx
+        q @= ry
+        qcompare(q, rx @ ry)
+
     # def multiply_test_normalized(self):
 
     #     vx = [1, 0, 0]; vy = [0, 1, 0]; vz = [0, 0, 1]
@@ -949,6 +954,14 @@ def test_multiply(self):
         q *= q2
         qcompare(q, [-12, 6, 24, 12])
 
+        # plain Quaternion has no @ (only UnitQuaternion normalizes via @),
+        # so @= must fail the same way @ does, not silently fall back to *=
+        with self.assertRaises(TypeError):
+            q1 @ q2
+        with self.assertRaises(TypeError):
+            q = q1
+            q @= q2
+
         # vector x vector
         qcompare(
             Quaternion([q1, u, q2, u, q3, u]) * Quaternion([u, q1, u, q2, u, q3]),