feat(pose,quaternion): add __imatmul__ (@=) operator (#199)

## What

`X @= Y` now works as the augmented-assignment form of the existing `X @
Y`
(`__matmul__`, which composes with normalization) — previously only `X
*= Y`
existed, which composes *without* normalization. Useful when a pose or
unit
quaternion is updated incrementally over many cycles and you want the
normalized form without writing `X = X @ Y` by hand.

Added to `BasePoseMatrix` (covers `SO2`/`SE2`/`SO3`/`SE3`) and
`Quaternion`
(covers `Quaternion`/`UnitQuaternion`).

Note on semantics: like the existing `__imul__`, this doesn't mutate the
object in place — `__imatmul__` returns a new (normalized) object and
Python
rebinds the name, same as `X = X @ Y`. That matches the existing `*=`
pattern in this codebase exactly, just saves writing `X = X @ Y`.

## A bug found while adding test coverage

This started as a cherry-pick of old, never-merged WIP work. While
writing
tests I found `Quaternion.__imatmul__`'s 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 `@=`.

`UnitQuaternion.__matmul__` (pre-existing, unchanged) already normalizes
correctly via `smb.qunit(smb.qqmul(x, y))` — `qunit` being the actual
normalizer; `qnorm` just returns the scalar magnitude, so it was never
really 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)` either:
plain `Quaternion` has no `__matmul__` (only `UnitQuaternion` defines
one),
and calling the dunder directly as a plain attribute bypasses Python's
normal operator fallback, raising a confusing `AttributeError` instead
of
the `TypeError` that `q1 @ q2` already raises consistently for plain
`Quaternion`. `left @ right` matches `@`'s behaviour exactly in both
cases.

Also fixed the docstring's `-> bool` return type annotation (should be
`-> Quaternion`) and its example, which called `Quaternion.Eul()` — a
method that only exists on `UnitQuaternion`.

## Testing

- Added `@=` coverage for `SO3`/`SE3` (must match `@`) alongside the
  existing `*=` tests in `test_pose3d.py`.
- Added `@=` coverage for `UnitQuaternion` (must match `@`, not `*`) and
for
  plain `Quaternion` (must raise `TypeError`, matching `@`, not silently
  degrade to `*=`) in `test_quaternion.py`.
- Full suite: 338 passed, 4 skipped.
- `black --check` clean at the pinned 23.10.0.

Author: petercorke

spatialmath/baseposematrix.py

@@ -1360,6 +1360,20 @@ def __imul__(left, right):  # noqa
         """
         return left.__mul__(right)
 
+    def __imatmul__(left, right):  # noqa
+        """
+        Overloaded ``@=`` operator (superclass method)
+
+        :return: Product of two operands with normalization
+        :rtype: Pose instance or NumPy array
+        :raises ValueError: for incompatible arguments
+
+        - ``X @= Y`` compounds the poses ``X`` and ``Y`` and places the normalized result in ``X``
+
+        :seealso: ``__imul__`` :meth:`__matmul__`
+        """
+        return left.__matmul__(right)
+
     def __truediv__(left, right):  # pylint: disable=no-self-argument
         """
         Overloaded ``/`` operator (superclass method)

spatialmath/quaternion.py

@@ -669,6 +669,40 @@ def __imul__(
         """
         return left.__mul__(right)
 
+    def __imatmul__(
+        left, right: Quaternion
+    ) -> 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)``. 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 UnitQuaternion
+            >>> q = UnitQuaternion.Eul([0.1, 0.2, 0.3])
+            >>> q @= UnitQuaternion.Eul([0.3, 0.4, 0.5])
+            >>> print(q)
+
+
+        :seealso: :func:`__matmul__`
+        """
+        # 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:
         """
         Overloaded ``**`` operator
@@ -1887,8 +1921,6 @@ def __matmul__(
         - ``q1 @ q2`` is the Hamilton product of ``q1`` and ``q2``, both unit
           quaternions, followed by explicit normalization.
 
-        - `` q1 @= q2`` as above.
-
         .. note:: This operator is functionally equivalent to ``*`` but is more
             costly.  It is useful for cases where a pose is incrementally update
             over many cycles.

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

@@ -508,6 +508,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]
@@ -990,6 +995,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]),