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

`X @= Y` now compounds poses/quaternions in place with automatic
normalization, mirroring the existing `X @ Y` (__matmul__) behaviour
but writing the normalized result back into the left operand instead
of returning a new one. Useful when a pose is updated incrementally
over many cycles and you don't want to pay for a fresh object each
time.

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

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

@@ -668,6 +668,32 @@ def __imul__(
         """
         return left.__mul__(right)
 
+    def __imatmul__(
+        left, right: Quaternion
+    ) -> bool:  # 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`)`
+
+        Example:
+
+        .. runblock:: pycon
+
+            >>> from spatialmath import Quaternion
+            >>> q = UnitQuaternion.Eul([0.1, 0.2, 0.3])
+            >>> q @= Quaternion.Eul([0.3, 0.4, 0.5])
+            >>> print(q)
+
+
+        :seealso: :func:`__mul__`
+        """
+        return left.__mul__(right)
+
     def __pow__(self, n: int) -> Quaternion:
         """
         Overloaded ``**`` operator
@@ -1886,8 +1912,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.