Consistent operation of printline() method for SO2, SE2, SO3, SE3, Quaternion, UnitQuaternion types. In base now have separate functions to convert type to a single line string or to print it. Fixed problem where stdout redirection failed using contextlib.redirect_stdout.

Author: petercorke

spatialmath/base/__init__.py

@@ -221,6 +221,7 @@
     "tr2jac2",
     "trinterp2",
     "trprint2",
+    "tr2str2",
     "trplot2",
     "tranimate2",
     "xyt2tr",
@@ -264,6 +265,7 @@
     "exp2jac",
     "rot2jac",
     "trprint",
+    "tr2str",
     "trplot",
     "tranimate",
     "tr2x",

spatialmath/base/quaternions.py

@@ -1152,14 +1152,9 @@ def q2str(
     return template.format(q[0], delim[0], q[1], q[2], q[3], delim[1])
 
 
-def qprint(
-    q: Union[ArrayLike4, ArrayLike4],
-    delim: Optional[Tuple[str, str]] = ("<", ">"),
-    fmt: Optional[str] = "{: .4f}",
-    file: Optional[TextIO] = sys.stdout,
-) -> None:
+def qprint(q: Union[ArrayLike4, ArrayLike4], file=False, **kwargs) -> None:
     """
-    Format a quaternion to a file
+    Compact single-line display of a quaternion
 
     :arg q: unit-quaternion
     :type q: array_like(4)
@@ -1195,7 +1190,9 @@ def qprint(
             "Usage: qprint(..., file=None) -> str is deprecated, use q2str() instead",
             DeprecationWarning,
         )
-    print(q2str(q, delim=delim, fmt=fmt), file=file)
+    if file is False:
+        file = None  # defaults to stdout
+    print(q2str(q, **kwargs), file=file)
 
 
 if __name__ == "__main__":  # pragma: no cover

spatialmath/base/transforms2d.py

@@ -17,6 +17,7 @@
 import sys
 import math
 import numpy as np
+import warnings
 
 try:
     import matplotlib.pyplot as plt
@@ -959,15 +960,15 @@ def trinterp2(start, end, s, shortest: bool = True):
         raise ValueError("Argument must be SO(2) or SE(2)")
 
 
-def trprint2(
+def tr2str2(
     T: Union[SO2Array, SE2Array],
     label: str = "",
-    file: TextIO = sys.stdout,
+    file: TextIO = None,
     fmt: str = "{:.3g}",
     unit: str = "deg",
 ) -> str:
     """
-    Compact display of SE(2) or SO(2) matrices
+    Convert SO(2) or SE(3) matrices to compact single-line string
 
     :param T: matrix to format
     :type T: ndarray(3,3) or ndarray(2,2)
@@ -985,12 +986,12 @@ def trprint2(
     The matrix is formatted and written to ``file`` and the
     string is returned.  To suppress writing to a file, set ``file=None``.
 
-    - ``trprint2(R)`` displays the SO(2) rotation matrix in a compact
+    - ``tr2str2(R)`` displays the SO(2) rotation matrix in a compact
       single-line format and returns the string::
 
         [LABEL:] θ UNIT
 
-    - ``trprint2(T)`` displays the SE(2) homogoneous transform in a compact
+    - ``tr2str2(T)`` displays the SE(2) homogoneous transform in a compact
       single-line format and returns the string::
 
         [LABEL:] [t=X, Y;] θ UNIT
@@ -999,17 +1000,18 @@ def trprint2(
 
         >>> from spatialmath.base import *
         >>> T = transl2(1,2) @ trot2(0.3)
-        >>> trprint2(T, file=None, label='T')
-        >>> trprint2(T, file=None, label='T', fmt='{:8.4g}')
-
+        >>> tr2str2(T, label='T')
+        >>> tr2str2(T, label='T', fmt='{:8.4g}')
 
     .. note::
 
         - Default formatting is for compact display of data
         - For tabular data set ``fmt`` to a fixed width format such as
           ``fmt='{:.3g}'``
 
-    :seealso: trprint
+    .. versionadded:: 1.1.15
+
+    :seealso: :func:`~tr2str`
     """
 
     s = ""
@@ -1028,8 +1030,6 @@ def trprint2(
     else:
         s += " {} rad".format(_vec2s(fmt, [angle]))
 
-    if file:
-        print(s, file=file)
     return s
 
 
@@ -1052,6 +1052,70 @@ def _vec2s(fmt: str, v: ArrayLikePure, tol: float = 20) -> str:
     return ", ".join([fmt.format(x) for x in v])
 
 
+def trprint2(
+    T: Union[SO2Array, SE2Array],
+    label: str = "",
+    file: TextIO = False,
+    **kwargs,
+) -> str:
+    """
+    Compact single-line display of SE(2) or SO(2) matrices
+
+    :param T: matrix to format
+    :type T: ndarray(3,3) or ndarray(2,2)
+    :param label: text label to put at start of line
+    :type label: str
+    :param file: file to write formatted string to [default is stdout]
+    :type file: file object
+    :param fmt: conversion format for each number
+    :type fmt: str
+    :param unit: angular units: 'rad' [default], or 'deg'
+    :type unit: str
+    :return: formatted string
+    :rtype: str
+
+    The matrix is formatted and written to ``file`` and the
+    string is returned.  To suppress writing to a file, set ``file=None``.
+
+    - ``trprint2(R)`` displays the SO(2) rotation matrix in a compact
+      single-line format and returns the string::
+
+        [LABEL:] θ UNIT
+
+    - ``trprint2(T)`` displays the SE(2) homogoneous transform in a compact
+      single-line format and returns the string::
+
+        [LABEL:] [t=X, Y;] θ UNIT
+
+    .. runblock:: pycon
+
+        >>> from spatialmath.base import *
+        >>> T = transl2(1,2) @ trot2(0.3)
+        >>> trprint2(T, label='T')
+        >>> trprint2(T, label='T', fmt='{:8.4g}')
+
+
+    .. note::
+
+        - Default formatting is for compact display of data
+        - For tabular data set ``fmt`` to a fixed width format such as
+          ``fmt='{:.3g}'``
+
+    .. versionchanged:: 1.1.15
+        To create a string use :func:`~tr2str2` instead of ``trprint2(...file=None)``
+
+    :seealso: :func:`~tr2str2` :func:`~trprint`
+    """
+    if file is None:
+        warnings.warn(
+            "Usage: trprint2(..., file=None) -> str is deprecated, use tr2str2() instead",
+            DeprecationWarning,
+        )
+    if file is False:
+        file = None  # defaults to stdout
+    print(tr2str2(T, **kwargs), file=file)
+
+
 def points2tr2(p1: NDArray, p2: NDArray) -> SE2Array:
     """
     SE(2) transform from corresponding points

spatialmath/base/transforms3d.py

@@ -18,6 +18,8 @@
 from collections.abc import Iterable
 import math
 import numpy as np
+import warnings
+
 
 from spatialmath.base.argcheck import getunit, getvector, isvector, isscalar, ismatrix
 from spatialmath.base.vectors import (
@@ -2779,50 +2781,44 @@ def rodrigues(w: ArrayLike3, theta: Optional[float] = None) -> SO3Array:
     )
 
 
-def trprint(
+def tr2str(
     T: Union[SO3Array, SE3Array],
     orient: str = "rpy/zyx",
     label: str = "",
-    file: TextIO = sys.stdout,
+    file: TextIO = None,
     fmt: str = "{:.3g}",
     degsym: bool = True,
     unit: str = "deg",
 ) -> str:
     """
-     Compact display of SO(3) or SE(3) matrices
+    Convert SO(3) or SE(3) matrices to compact single-line string
 
-     :param T: SE(3) or SO(3) matrix
-     :type T: ndarray(4,4) or ndarray(3,3)
-     :param label: text label to put at start of line
-     :type label: str
-     :param orient: 3-angle convention to use
-     :type orient: str
-     :param file: file to write formatted string to. [default, stdout]
-     :type file: file object
-     :param fmt: conversion format for each number in the format used with ``format``
-     :type fmt: str
-     :param unit: angular units: 'rad' [default], or 'deg'
-     :type unit: str
-     :return: formatted string
-     :rtype: str
-     :raises ValueError: bad argument
+    :param T: SE(3) or SO(3) matrix
+    :type T: ndarray(4,4) or ndarray(3,3)
+    :param label: text label to put at start of line
+    :type label: str
+    :param orient: 3-angle convention to use
+    :type orient: str
+    :param fmt: conversion format for each number in the format used with ``format``
+    :type fmt: str
+    :param unit: angular units: 'rad' [default], or 'deg'
+    :type unit: str
+    :return: formatted string
+    :rtype: str
+    :raises ValueError: bad argument
 
-     The matrix is formatted and written to ``file`` and the
-     string is returned.  To suppress writing to a file, set ``file=None``.
+    The matrix is formatted and returned as a string.
 
-    - ``trprint(R)`` prints the SO(3) rotation matrix to stdout in a compact
-       single-line format:
+    - ``tr2str(R)`` converts the SO(3) rotation matrix to a compact
+      single-line string:
 
          [LABEL:] ORIENTATION UNIT
 
-     - ``trprint(T)`` prints the SE(3) homogoneous transform to stdout in a
-       compact single-line format:
+     - ``tr2str(T)`` prints the SE(3) homogoneous transform to a compact
+       single-line string:
 
          [LABEL:] [t=X, Y, Z;] ORIENTATION UNIT
 
-     - ``trprint(X, file=None)`` as above but returns the string rather than
-       printing to a file
-
      Orientation is expressed in one of several formats:
 
      - 'rpy/zyx' roll-pitch-yaw angles in ZYX axis order [default]
@@ -2834,11 +2830,11 @@ def trprint(
 
      .. runblock:: pycon
 
-         >>> from spatialmath.base import transl, rpy2tr, trprint
+         >>> from spatialmath.base import *
          >>> T = transl(1,2,3) @ rpy2tr(10, 20, 30, 'deg')
-         >>> trprint(T, file=None)
-         >>> trprint(T, file=None, label='T', orient='angvec')
-         >>> trprint(T, file=None, label='T', orient='angvec', fmt='{:8.4g}')
+         >>> tr2str(T)
+         >>> tr2str(T, label='T', orient='angvec')
+         >>> tr2str(T, label='T', orient='angvec', fmt='{:8.4g}')
 
      .. note::
 
@@ -2849,7 +2845,9 @@ def trprint(
          - For tabular data set ``fmt`` to a fixed width format such as
            ``fmt='{:.3g}'``
 
-     :seealso: :func:`~spatialmath.base.transforms2d.trprint2` :func:`~tr2eul` :func:`~tr2rpy` :func:`~tr2angvec`
+    .. versionadded:: 1.1.15
+
+     :seealso: :func:`~trprint` :func:`~spatialmath.base.transforms2d.trprint2` :func:`~tr2eul` :func:`~tr2rpy` :func:`~tr2angvec`
      :SymPy: not supported
     """
 
@@ -2898,10 +2896,6 @@ def trprint(
             s += " angvec = ({} | {})".format(theta, _vec2s(fmt, v))
     else:
         raise ValueError("bad orientation format")
-
-    if file:
-        print(s, file=file)
-
     return s
 
 
@@ -2910,6 +2904,80 @@ def _vec2s(fmt, v):
     return ", ".join([fmt.format(x) for x in v])
 
 
+def trprint(T: Union[SO3Array, SE3Array], file=False, **kwargs) -> str:
+    """
+     Compact single-line display of SO(3) or SE(3) matrices
+
+     :param T: SE(3) or SO(3) matrix
+     :type T: ndarray(4,4) or ndarray(3,3)
+     :param label: text label to put at start of line
+     :type label: str
+     :param orient: 3-angle convention to use
+     :type orient: str
+     :param file: file to write formatted string to. [default, stdout]
+     :type file: file object
+     :param fmt: conversion format for each number in the format used with ``format``
+     :type fmt: str
+     :param unit: angular units: 'rad' [default], or 'deg'
+     :type unit: str
+     :return: formatted string
+     :rtype: str
+     :raises ValueError: bad argument
+
+     The matrix is formatted and written to ``file``.
+
+    - ``trprint(R)`` prints the SO(3) rotation matrix to stdout in a compact
+      single-line format:
+
+         [LABEL:] ORIENTATION UNIT
+
+     - ``trprint(T)`` prints the SE(3) homogoneous transform to stdout in a
+       compact single-line format:
+
+         [LABEL:] [t=X, Y, Z;] ORIENTATION UNIT
+
+     Orientation is expressed in one of several formats:
+
+     - '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
+
+
+     .. runblock:: pycon
+
+         >>> from spatialmath.base import *
+         >>> T = transl(1,2,3) @ rpy2tr(10, 20, 30, 'deg')
+         >>> trprint(T)
+         >>> trprint(T, label='T', orient='angvec')
+         >>> trprint(T, label='T', orient='angvec', fmt='{:8.4g}')
+
+     .. note::
+
+         - If the 'rpy' option is selected, then the particular angle sequence can be
+           specified with the options 'xyz' or 'yxz' which are passed through to ``tr2rpy``.
+           'zyx' is the default.
+         - Default formatting is for compact display of data
+         - For tabular data set ``fmt`` to a fixed width format such as
+           ``fmt='{:.3g}'``
+
+    .. versionchanged:: 1.1.15
+        To create a string use :func:`~tr2str` instead of ``trprint(...file=None)``
+
+     :seealso: :func:`~tr2str` :func:`~spatialmath.base.transforms2d.trprint2` :func:`~tr2eul` :func:`~tr2rpy` :func:`~tr2angvec`
+     :SymPy: not supported
+    """
+    if file is None:
+        warnings.warn(
+            "Usage: trprint(..., file=None) -> str is deprecated, use tr2str() instead",
+            DeprecationWarning,
+        )
+    if file is False:
+        file = None  # defaults to stdout
+    print(tr2str(T, **kwargs), file=file)
+
+
 try:
     import matplotlib.pyplot as plt
     from mpl_toolkits.mplot3d import Axes3D