Rename Quaternion.matrix

[jstmn]

Hi,

I wanted to raise the possibility of renaming the .matrix property of the UnitQuaternion class. This property returns a 4x4 matrix to do quaternion multiplication, rather than return the corresponding 3x3 rotation matrix as one would epect. I think this naming should be redone so that it's obvious that the .matrix method has nothing to do with returining a 3x3 rotation matrix.

When you read the documentation it's clear that its unrelated, but with a better naming scheme you wouldn't need to go through the trouble. I just got burnt for making this mistake and would guess others will too. Thanks.

Some possible other names

• hamiltonian_matrix
• hamilton_product_matrix
• multiplication_matrix

    @property
    def matrix(self) -> R4x4:
        """
        Matrix equivalent of quaternion

        :rtype: Numpy array, shape=(4,4)

        ``q.matrix`` is a 4x4 matrix which encodes the arithmetic rules of Hamilton multiplication.
        This matrix, multiplied by the 4-vector equivalent of a second quaternion, results in the 4-vector
        equivalent of the Hamilton product.

        Example:

        .. runblock:: pycon

            >>> from spatialmath import Quaternion
            >>> Quaternion([1,2,3,4]).matrix
            >>> Quaternion([1,2,3,4]) * Quaternion([5,6,7,8])   # Hamilton product
            >>> Quaternion([1,2,3,4]).matrix @ Quaternion([5,6,7,8]).vec  # matrix-vector product

        :seealso: :func:`~spatialmath.base.quaternions.qmatrix`
        """

        return smb.qmatrix(self._A)

• jeremy