doco update, focus on seealso and pycon example blocks

Author: petercorke

spatialmath/baseposematrix.py

@@ -404,7 +404,7 @@ def interp(self, end=None, s=None):
 
             - For SO3 and SE3 rotation is interpolated using quaternion spherical linear interpolation (slerp).
             - Values of ``s`` outside the range [0,1] are silently clipped
-        :seealso: :func:`interp1`, :func:`~spatialmath.base.transforms3d.trinterp`, :func:`~spatialmath.base.quaternions.slerp`, :func:`~spatialmath.base.transforms2d.trinterp2`
+        :seealso: :func:`interp1`, :func:`~spatialmath.base.transforms3d.trinterp`, :func:`~spatialmath.base.quaternions.qslerp`, :func:`~spatialmath.base.transforms2d.trinterp2`
 
         :SymPy: not supported
         """
@@ -482,7 +482,7 @@ def interp1(self, s=None):
 
         #. For SO3 and SE3 rotation is interpolated using quaternion spherical linear interpolation (slerp).
 
-        :seealso: :func:`interp`, :func:`~spatialmath.base.transforms3d.trinterp`, :func:`~spatialmath.base.quaternions.slerp`, :func:`~spatialmath.base.transforms2d.trinterp2`
+        :seealso: :func:`interp`, :func:`~spatialmath.base.transforms3d.trinterp`, :func:`~spatialmath.base.quaternions.qslerp`, :func:`~spatialmath.base.transforms2d.trinterp2`
 
         :SymPy: not supported
         """
@@ -590,8 +590,8 @@ def stack(self):
 
     # ----------------------- i/o stuff
 
-    def printline(self, arg=None, **kwargs):
-        """
+    def printline(self, *args, **kwargs):
+        r"""
         Print pose in compact single line format (superclass method)
         
         :param arg: value for orient option, optional
@@ -618,7 +618,6 @@ def printline(self, arg=None, **kwargs):
         =============   =================================================
         ``orient``      description
         =============   =================================================
-
         ``'rpy/zyx'``   roll-pitch-yaw angles in ZYX axis order [default]
         ``'rpy/yxz'``   roll-pitch-yaw angles in YXZ axis order
         ``'rpy/zyx'``   roll-pitch-yaw angles in ZYX axis order
@@ -631,38 +630,33 @@ def printline(self, arg=None, **kwargs):
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE2, SE3
             >>> x = SE3.Rx(0.3)
             >>> x.printline()
-            >>> x = SE3.Rx([0.2, 0.3], 'rpy/xyz')
+            >>> x = SE3.Rx([0.2, 0.3])
             >>> x.printline()
             >>> x.printline('angvec')
             >>> x.printline(orient='angvec', fmt="{:.6f}")
             >>> x = SE2(1, 2, 0.3)
             >>> x.printline()
-            >>> SE3.Rand(N=3).printline(fmt='{:8.3g}')
 
         .. note::
             - Default formatting is for compact display of data
             - For tabular data set ``fmt`` to a fixed width format such as
               ``fmt='{:.3g}'``
 
-        :seealso: :func:`trprint`, :func:`trprint2`
+        :seealso: :meth:`strline` :func:`trprint`, :func:`trprint2`
         """
-        if arg is not None and kwargs == {}:
-            if isinstance(arg, str):
-                kwargs = dict(orient=arg)
-            else:
-                raise ValueError('single argument must be a string')
         if self.N == 2:
             for x in self.data:
-                base.trprint2(x, **kwargs)
+                base.trprint2(x, *args, **kwargs)
         else:
             for x in self.data:
-                base.trprint(x, **kwargs)
+                base.trprint(x, *args, **kwargs)
 
     def strline(self, *args, **kwargs):
         """
-        Print pose in compact single line format (superclass method)
+        Convert pose to compact single line string (superclass method)
 
         :param label: text label to put at start of line
         :type label: str
@@ -675,28 +669,44 @@ def strline(self, *args, **kwargs):
         :type orient: str
         :param unit: angular units: 'rad' [default], or 'deg'
         :type unit: str
+        :return: pose in string format
+        :rtype: str
 
-        Print pose in a compact single line format. If ``X`` has multiple
-        values, print one per line.
+        Convert pose in a compact single line format. If ``X`` has multiple
+        values, the string has one pose per line.
+
+        Orientation can be displayed in various formats:
+
+        =============   =================================================
+        ``orient``      description
+        =============   =================================================
+        ``'rpy/zyx'``   roll-pitch-yaw angles in ZYX axis order [default]
+        ``'rpy/yxz'``   roll-pitch-yaw angles in YXZ axis order
+        ``'rpy/zyx'``   roll-pitch-yaw angles in ZYX axis order
+        ``'eul'``       Euler angles in ZYZ axis order
+        ``'angvec'``    angle and axis
+        =============   =================================================
 
         Example:
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE2, SE3
             >>> x = SE3.Rx(0.3)
-            >>> x.printline()
-            >>> x = SE3.Rx([0.2, 0.3], 'rpy/xyz')
-            >>> x.printline()
+            >>> x.strline()
+            >>> x = SE3.Rx([0.2, 0.3])
+            >>> x.strline()
+            >>> x.strline('angvec')
+            >>> x.strline(orient='angvec', fmt="{:.6f}")
             >>> x = SE2(1, 2, 0.3)
-            >>> x.printline()
-            >>> SE3.Rand(N=3).printline(fmt='{:8.3g}')
+            >>> x.strline()
 
         .. note::
             - Default formatting is for compact display of data
             - For tabular data set ``fmt`` to a fixed width format such as
               ``fmt='{:.3g}'``
 
-        :seealso: :func:`trprint`, :func:`trprint2`
+        :seealso: :meth:`printline` :func:`trprint`, :func:`trprint2`
         """
         s = ""
         if self.N == 2:

spatialmath/pose3d.py

@@ -743,7 +743,7 @@ def angdist(self, other, metric=6):
 
         .. runblock:: pycon
 
-            >>> from spatialmath import UnitQuaternion
+            >>> from spatialmath import SO3
             >>> R1 = SO3.Rx(0.3)
             >>> R2 = SO3.Ry(0.3)
             >>> print(R1.angdist(R1))
@@ -875,18 +875,15 @@ def t(self):
         ``x.t`` is the translational component of ``x`` as an array with
         shape (3,). If ``len(x) > 1``, return an array with shape=(N,3).
 
-        .. runblock:: pycon
+        Example:
 
-            >>> from spatialmath import UnitQuaternion
+        .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> x = SE3(1,2,3)
             >>> x.t
-            array([1., 2., 3.])
             >>> x = SE3([ SE3(1,2,3), SE3(4,5,6)])
             >>> x.t
-            array([[1., 2., 3.],
-                   [4., 5., 6.]])
-
         
         :SymPy: supported
         """
@@ -918,14 +915,14 @@ def inv(self):
             T = \left[ \begin{array}{cc} \mat{R} & \vec{t} \\ 0 & 1 \end{array} \right],
             \mat{T}^{-1} = \left[ \begin{array}{cc} \mat{R}^T & -\mat{R}^T \vec{t} \\ 0 & 1 \end{array} \right]`
 
-        Example::
+        Example:
+
+        .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> x = SE3(1,2,3)
             >>> x.inv()
-            SE3(array([[ 1.,  0.,  0., -1.],
-                       [ 0.,  1.,  0., -2.],
-                       [ 0.,  0.,  1., -3.],
-                       [ 0.,  0.,  0.,  1.]]))
+
 
         :seealso: :func:`~spatialmath.base.transforms3d.trinv`
 
@@ -949,13 +946,15 @@ def delta(self, X2=None):
         The vector :math:`d = [\delta_x, \delta_y, \delta_z, \theta_x, \theta_y, \theta_z]`
         represents infinitesimal translation and rotation.
 
-        Example::
+        Example:
+
+        .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> x1 = SE3.Rx(0.3)
             >>> x2 = SE3.Rx(0.3001)
             >>> x1.delta(x2)
-            array([0.00000000e+00, 0.00000000e+00, 0.00000000e+00, 9.99999998e-05,
-                0.00000000e+00, 0.00000000e+00])
+
 
         .. note::
 
@@ -1032,11 +1031,13 @@ def twist(self):
         :return: equivalent rigid-body motion as a twist vector
         :rtype: Twist3 instance
 
-        Example::
+        Example:
 
+        .. runblock:: pycon
+
+            >>> from spatialmath import SE3
             >>> x = SE3(1,2,3)
             >>> x.twist()
-            Twist3([1, 2, 3, 0, 0, 0])
 
         :seealso: :func:`spatialmath.twist.Twist3`
         """
@@ -1089,6 +1090,7 @@ def Rx(cls, theta, unit='rad', t=None):
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> SE3.Rx(0.3)
             >>> SE3.Rx([0.3, 0.4])
 
@@ -1124,6 +1126,7 @@ def Ry(cls, theta, unit='rad', t=None):
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> SE3.Ry(0.3)
             >>> SE3.Ry([0.3, 0.4])
 
@@ -1159,6 +1162,7 @@ def Rz(cls, theta, unit='rad', t=None):
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> SE3.Rz(0.3)
             >>> SE3.Rz([0.3, 0.4])
 
@@ -1189,18 +1193,13 @@ def Rand(cls, N=1, xrange=(-1, 1), yrange=(-1, 1), zrange=(-1, 1)):  # pylint: d
         - ``SE3.Rand(N)`` is an SE3 object containing a sequence of N random
           poses.
 
-        Example::
 
+        Example:
+
+        .. runblock:: pycon
+
+            >>> from spatialmath import SE3
             >>> SE3.Rand(2)
-            SE3([
-            array([[ 0.58076657,  0.64578702, -0.49565041, -0.78585825],
-                [-0.57373134, -0.10724881, -0.8119914 ,  0.72069253],
-                [-0.57753142,  0.75594763,  0.30822173,  0.12291999],
-                [ 0.        ,  0.        ,  0.        ,  1.        ]]),
-            array([[ 0.96481299, -0.26267256, -0.01179066,  0.80294729],
-                [ 0.06421463,  0.19190584,  0.97931028, -0.15021311],
-                [-0.25497525, -0.94560841,  0.20202067,  0.02684599],
-                [ 0.        ,  0.        ,  0.        ,  1.        ]]) ])
 
         :seealso: :func:`~spatialmath.quaternions.UnitQuaternion.Rand`
         """
@@ -1333,13 +1332,12 @@ def OA(cls, o, a):
             - ``o`` and ``a`` do not have to be orthogonal, so long as they are not parallel
               ``o`` is adjusted to be orthogonal to ``a``.
 
-        Example::
+        Example:
+
+        .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> SE3.OA([1, 0, 0], [0, 0, -1])
-            SE3(array([[-0.,  1.,  0.,  0.],
-                    [ 1.,  0.,  0.,  0.],
-                    [ 0.,  0., -1.,  0.],
-                    [ 0.,  0.,  0.,  1.]]))
 
         :seealso: :func:`~spatialmath.base.transforms3d.oa2r`
         """
@@ -1519,6 +1517,7 @@ def Tx(cls, x):
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> SE3.Tx(2)
             >>> SE3.Tx([2,3])
 
@@ -1545,6 +1544,7 @@ def Ty(cls, y):
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> SE3.Ty(2)
             >>> SE3.Ty([2,3])
 
@@ -1570,6 +1570,7 @@ def Tz(cls, z):
 
         .. runblock:: pycon
 
+            >>> from spatialmath import SE3
             >>> SE3.Tz(2)
             >>> SE3.Tz([2,3])
 
@@ -1638,7 +1639,7 @@ def angdist(self, other, metric=6):
 
         .. runblock:: pycon
 
-            >>> from spatialmath import UnitQuaternion
+            >>> from spatialmath import SE3
             >>> T1 = SE3.Rx(0.3)
             >>> T2 = SE3.Ry(0.3)
             >>> print(T1.angdist(T1))

spatialmath/spatialvector.py

@@ -39,11 +39,28 @@ class SpatialVector(BasePoseList):
     ``+``      addition of spatial vectors of the same subclass
     ``-``      subtraction of spatial vectors of the same subclass
     ``-``      unary minus
-    ``*``      premultiplication by Twist3 is transformation to new frame
+    ``*``      see table below
     ``^``      cross product x or x*
     ========   ===========================================================
 
 
+    Certain subtypes can be multiplied
+
+    ===================   ====================  ===================  =========================
+                Multiplicands                   Product
+    ------------------------------------------  ----------------------------------------------
+    left                  right                 type                 operation
+    ===================   ====================  ===================  =========================
+    SE3, Twist3           SpatialVelocity       SpatialVelocity      adjoint product
+    SE3, Twist3           SpatialAcceleration   SpatialAcceleration  adjoint product
+    SE3, Twist3           SpatialMomentum       SpatialMomentum      adjoint transpose product
+    SE3, Twist3           SpatialForce          SpatialForce         adjoint transpose product
+    SpatialAcceleration   SpatialInertia        SpatialForce         matrix-vector product**
+    SpatialVelocity       SpatialInertia        SpatialMomentum      matrix-vector product**
+    ===================   ====================  ===================  =========================
+
+    ** indicates commutative operator.
+
     .. inheritance-diagram:: spatialmath.spatialvector.SpatialVelocity spatialmath.spatialvector.SpatialAcceleration spatialmath.spatialvector.SpatialForce spatialmath.spatialvector.SpatialMomentum
        :top-classes: spatialmath.spatialvector.SpatialVector
        :parts: 1
@@ -442,7 +459,7 @@ def __init__(self, value=None):
         super().__init__(value)
 # n = SpatialForce(val);
 
-    def __rmul(right, left):  # lgtm[py/not-named-self] pylint: disable=no-self-argument
+    def __rmul__(right, left):  # lgtm[py/not-named-self] pylint: disable=no-self-argument
         # Twist * SpatialForce -> SpatialForce
         return SpatialForce(left.Ad.T @ right.A)