Merge branch 'master' into fix/twist-pitch-clean

Author: jbarry-bdai

.github/CODEOWNERS

@@ -1,2 +1,2 @@
 # Global Owners
-* @petercorke @jhavl @myeatman-bdai
+* @petercorke @jbarry-bdai

README.md

@@ -452,7 +452,7 @@ Similarly when we assign an element or slice of the symbolic matrix to a numeric
 
 On April 28, 2026 this repository moved to the **RAI-Opensource** GitHub organization.  If you are still pulling from the previous bdaiinstitute GitHub organization, please update your git remote:
    ```bash
-   git remote set-url origin https://github.com/RAI-Opensource/spot_ros2
+   git remote set-url origin https://github.com/RAI-Opensource/spatialmath-python.git
    ```
 
 Also update any links of `https://bdaiinstitute.github.io/spatialmath-python` to  <https://spatialmath-python.rai-inst.com/>.

docs/source/classes-2d.rst

@@ -262,6 +262,7 @@ The classes ``SE3``, ``SO3``, ``SE2`` and ``SO2`` can provide colorized text out
 
 .. image:: ../figs/colored_output.png
    :width: 300
+
 with rotational elements in red, translational elements in blue and constants in grey.
 
 The foreground and background colors can be controlled using the following
@@ -538,8 +539,10 @@ A numpy column vector has shape ``(N,1)`` and a row vector
 has shape ``(1,N)`` but functions also accept row ``(1,N)``  and column ``(N,1)`` 
 where a vector argument is required.  
 
-.. warning:: For a user transitioning from MATLAB the most significant
-  differences are:
+.. warning::
+
+  For a user transitioning from MATLAB the most significant differences are:
+
     - the use of 1D arrays -- all MATLAB arrays have two dimensions,
       even if one of them is equal to one.
     - Iterating over a 1D NumPy array (N,) returns consecutive elements

docs/source/classes-3d.rst

@@ -338,7 +338,7 @@ def SE3(self) -> SE3:
 
         .. runblock:: pycon
 
-            >>> from spatialmath import DualQuaternion, SE3
+            >>> from spatialmath import UnitDualQuaternion, SE3
             >>> T = SE3.Rand()
             >>> print(T)
             >>> d = UnitDualQuaternion(T)

docs/source/intro.rst

@@ -210,6 +210,7 @@
     "qprint",
     "q2str",
     # spatialmath.base.transforms2d
+    "pos2tr2",
     "rot2",
     "trot2",
     "transl2",
@@ -219,6 +220,9 @@
     "trexp2",
     "trnorm2",
     "tr2jac2",
+    "tr2pos2",
+    "tr2adjoint2",
+    "tradjoint2",
     "trinterp2",
     "trprint2",
     "trplot2",

spatialmath/DualQuaternion.py

@@ -62,7 +62,7 @@ def isinteger(x: Any) -> bool:
 
     .. runblock:: pycon
 
-        >>> from spatialmath.base import isscalar
+        >>> from spatialmath.base import isinteger
         >>> isinteger(1)
         >>> isinteger(1.2)
 

spatialmath/base/__init__.py

@@ -115,42 +115,41 @@ def plot_point(
         Plot one or more points, with optional text label.
 
         - The color of the marker can be different to the color of the text, the
-        marker color is specified by a single letter in the marker string.
+          marker color is specified by a single letter in the marker string.
 
         - A point can have multiple markers, given as a list, which will be
-        overlaid, for instance ``["rx", "ro"]`` will give a ⨂ symbol.
+          overlaid, for instance ``["rx", "ro"]`` will give a ⨂ symbol.
 
         - The optional text label is placed to the right of the marker, and
-        vertically aligned.
+          vertically aligned.
 
         - Multiple points can be marked if ``pos`` is a 2xn array or a list of
-        coordinate pairs.  In this case:
+          coordinate pairs.  In this case:
 
             - all points have the same ``text`` label
             - ``text`` can include the format string {} which is susbstituted for the
-            point index, starting at zero
+              point index, starting at zero
             - ``text`` can be a tuple containing a format string followed by vectors
-            of shape(n).  For example::
+              of shape(n).  For example::
 
-                ``("#{0} a={1:.1f}, b={2:.1f}", a, b)``
+                ("#{0} a={1:.1f}, b={2:.1f}", a, b)
 
             will label each point with its index (argument 0) and consecutive
             elements of ``a`` and ``b`` which are arguments 1 and 2 respectively.
 
         Example::
 
-            >>> from spatialmath.base import plotvol2, plot_text
+            >>> from spatialmath.base import plotvol2, plot_point
             >>> plotvol2(5)
-            >>> plot_point((0, 0))        # plot default marker at coordinate (1,2)
+            >>> plot_point((0,0))        # plot default marker at coordinate (1,2)
             >>> plot_point((1,1), 'r*')  # plot red star at coordinate (1,2)
-            >>> plot_point((2,2), 'r*', 'foo')  # plot red star at coordinate (1,2) and
-        label it as 'foo'
+            >>> plot_point((2,2), 'r*', 'foo')  # plot red star at coordinate (1,2) and label it as 'foo'
 
         .. plot::
 
-            from spatialmath.base import plotvol2, plot_text
+            from spatialmath.base import plotvol2, plot_point
             ax = plotvol2(5)
-            plot_point((0, 0))
+            plot_point((0,0))
             plot_point((1,1), 'r*')
             plot_point((2,2), 'r*', 'foo')
             ax.grid()
@@ -327,7 +326,8 @@ def plot_homline(
         return handles
 
     def plot_box(
-        *fmt: Optional[str],
+        fmt: str | None = None,
+        *,
         lbrt: Optional[ArrayLike4] = None,
         lrbt: Optional[ArrayLike4] = None,
         lbwh: Optional[ArrayLike4] = None,
@@ -339,6 +339,7 @@ def plot_box(
         rt: Optional[ArrayLike2] = None,
         wh: Optional[ArrayLike2] = None,
         centre: Optional[ArrayLike2] = None,
+        center: Optional[ArrayLike2] = None,
         w: Optional[float] = None,
         h: Optional[float] = None,
         ax: Optional[plt.Axes] = None,
@@ -358,39 +359,79 @@ def plot_box(
         :type rt: array_like(2), optional
         :param wh: width and height, if both are the same provide scalar, defaults to None
         :type wh: scalar, array_like(2), optional
-        :param centre: centre of box, defaults to None
+        :param centre: centre of box, defaults to None (alias: ``center``)
         :type centre: array_like(2), optional
         :param w: width of box, defaults to None
         :type w: float, optional
         :param h: height of box, defaults to None
         :type h: float, optional
+        ;param lbrt: left-bottom, right-top corners, defaults to None
+        :type lbrt: array_like(4), optional
+        :param lrbt: left-right, bottom-top corners, defaults to None
+        :type lrbt: array_like(4), optional
+        :param lbwh: left-bottom corner, width and height, defaults to None
+        :type lbwh: array_like(4), optional
+        :param ltrb: left-top, right-bottom corners, defaults to None
+        :type ltrb: array_like(4), optional
         :param ax: the axes to draw on, defaults to ``gca()``
         :type ax: Axis, optional
         :param bbox: bounding box matrix, defaults to None
         :type bbox: array_like(4), optional
-        :param color: box outline color
+        :param filled: fill the box, defaults to False (alias for Matplotlib ``fill``)
+        :type filled: bool
+        :param thickness: line thickness (alias for Matplotlib ``linewidth``)
+        :type thickness: float, optional
+        :param kwargs: additional arguments passed to ``pyplot.Rectangle()``
+
+        :return: the matplotlib object
+        :rtype: Patch.Rectangle instance
+
+        Appearance is controlled by Matplotlib properties passed as keyword arguments, for example:
+
+        :param color: box outline and fill color
         :type color: array_like(3) or str
-        :param fillcolor: box fill color
+        :param edgecolor: box outline colour (alias: ``ec``)
+        :type edgecolor: array_like(3) or str
+        :param fillcolor: box fill colour
         :type fillcolor: array_like(3) or str
+        :param filled: fill the box, defaults to False
+        :type filled: bool
         :param alpha: transparency, defaults to 1
         :type alpha: float, optional
-        :param thickness: line thickness, defaults to None
-        :type thickness: float, optional
-        :return: the matplotlib object
-        :rtype: Patch.Rectangle instance
+        :param linestyle: box outline line style (alias: ``ls``)
+        :type linestyle: str, optional
+        :param linewidth: box outline line thickness (alias: ``lw``)
+        :type linewidth: float, optional
 
-        The box can be specified in many ways:
+        Additionally, the line style and color can be conveniently set using the pyplot
+        convention where the first argument is a ``fmt`` string, for example ``"r--"``
+        for dashed red. The allowable color letters are ``"rgbcmyk"`` and the line style
+        characters are ``"-", "--", "-.", ":"``.
 
-        - bounding box [xmin, xmax, ymin, ymax]
-        - alternative box [xmin, ymin, xmax, ymax]
-        - centre and width+height
-        - left-bottom and right-top corners
-        - left-bottom corner and width+height
-        - right-top corner and width+height
-        - left-top corner and width+height
+        The box can be specified in many ways.  Two corners:
+
+        - `lb` = left-bottom corner
+        - `lt` = left-top corner
+        - `rb` = right-bottom corner
+        - `rt` = right-top corner
+
+        Alternatively, one corner or `centre` plus the dimensons:
+
+        - `wh` = [width, height]
+        - `w` = width
+        - `h` = height
+
+        Alternatively, the box can be specified by a number of 4-vectors, various
+        conventions are in use across different packages, so we support them all:
+
+        - `lbrt` = [umin, vmin, umax, vmax]
+        - `lrbt` = [umin, umax, vmin, vmax]
+        - `lbwh` = [umin, vmin, w, h]
+        - `bbox` same as `lbwh`
+        - `ltrb` = [umin, vmin, umax, vmax]`
 
         For plots where the y-axis is inverted (eg. for images) then top is the
-        smaller vertical coordinate.
+        smaller vertical coordinate (highest in the window).
 
         Example::
 
@@ -440,6 +481,8 @@ def plot_box(
         elif w is not None and h is not None:
             # we have width & height, one corner is enough
 
+            if centre is None:
+                centre = center
             if centre is not None:
                 lb = (centre[0] - w / 2, centre[1] - h / 2)
 
@@ -464,7 +507,7 @@ def plot_box(
                 h = lt[1] - rb[1]
 
             else:
-                raise ValueError("cant compute box")
+                raise ValueError("insufficient parameters to compute a box")
 
         if w < 0:
             raise ValueError("width must be positive")
@@ -479,9 +522,9 @@ def plot_box(
         else:
             ec = None
             ls = ""
-            if len(fmt) > 0:
+            if fmt is not None:
                 colors = "rgbcmywk"
-                for f in fmt[0]:
+                for f in fmt:
                     if f in colors:
                         ec = f
                     else:
@@ -490,8 +533,13 @@ def plot_box(
                 ls = None
 
             if "color" in kwargs:
-                ec = kwargs["color"]
-                del kwargs["color"]
+                ec = kwargs.pop("color")
+            if "edgecolor" in kwargs:
+                ec = kwargs.pop("edgecolor")
+            if "linestyle" in kwargs:
+                ls = kwargs.pop("linestyle")
+            elif "ls" in kwargs:
+                ls = kwargs.pop("ls")
             r = plt.Rectangle(
                 lb, w, h, clip_on=True, linestyle=ls, edgecolor=ec, fill=False, **kwargs
             )
@@ -558,7 +606,7 @@ def plot_arrow(
             ax = plotvol2(5)
             ax.grid()
             plot_arrow(
-                (-2, -2), (2, 4), label="$\mathit{p}_3$", color="r", width=0.1
+                (-2, -2), (2, 4), label=r"$\mathit{p}_3$", color="r", width=0.1
             )
             plt.show(block=True)
 
@@ -846,13 +894,15 @@ def plot_ellipse(
         The ellipse is defined by :math:`x^T \mat{E} x = s^2` where :math:`x \in
         \mathbb{R}^2` and :math:`s` is the scale factor.
 
-        .. note:: For some common cases we require :math:`\mat{E}^{-1}`, for example
+        .. note::
+            For some common cases we require :math:`\mat{E}^{-1}`, for example:
+
             - for robot manipulability
-            :math:`\nu (\mat{J} \mat{J}^T)^{-1} \nu` i
+              :math:`\nu (\mat{J} \mat{J}^T)^{-1} \nu` i
             - a covariance matrix
-            :math:`(x - \mu)^T \mat{P}^{-1} (x - \mu)`
-            so to avoid inverting ``E`` twice to compute the ellipse, we flag that
-            the inverse is provided using ``inverted``.
+              :math:`(x - \mu)^T \mat{P}^{-1} (x - \mu)`
+              so to avoid inverting ``E`` twice to compute the ellipse, we flag that
+              the inverse is provided using ``inverted``.
 
         Returns a set of ``resolution``  that lie on the circumference of a circle
         of given ``center`` and ``radius``.
@@ -1101,7 +1151,7 @@ def plot_ellipsoid(
         .. note::
 
             - If a confidence interval is given then ``E`` is interpretted as a covariance
-            matrix and the ellipse size is computed using an inverse chi-squared function.
+              matrix and the ellipse size is computed using an inverse chi-squared function.
 
         :seealso: :func:`~matplotlib.pyplot.plot_surface`, :func:`~matplotlib.pyplot.plot_wireframe`
         """

spatialmath/base/argcheck.py

@@ -1119,7 +1119,8 @@ def q2str(
     fmt: Optional[str] = "{: .4f}",
 ) -> str:
     """
-    Format a quaternion as a string
+    Convert quaternion to compact single-line string
+
 
     :arg q: unit-quaternion
     :type q: array_like(4)