doco updates

Author: petercorke

spatialmath/base/graphics.py

@@ -401,11 +401,50 @@ def plot_box(
     return r
 
 def plot_arrow(start, end, ax=None, **kwargs):
+    """
+    Plot 2D arrow
+
+    :param start: start point, arrow tail
+    :type start: array_like(2)
+    :param end: end point, arrow head
+    :type end: array_like(2)
+    :param ax: axes to draw into, defaults to None
+    :type ax: Axes, optional
+    :param kwargs: argumetns to pass to :class:`matplotlib.patches.Arrow`
+
+    Example:
+
+    .. runblock:: pycon
+
+        >>> from spatialmath.base import plotvol2, plot_arrow
+        >>> plotvol2(5)
+        >>> plot_arrow((-2, 2), (3, 4), color='r', width=0.1)  # red arrow
+    """
     ax = axes_logic(ax, 2)
 
     ax.arrow(start[0], start[1], end[0] - start[0], end[1] - start[1], length_includes_head=True, **kwargs)
 
 def plot_polygon(vertices, *fmt, close=False, **kwargs):
+    """
+    Plot polygon
+
+    :param vertices: vertices
+    :type vertices: ndarray(2,N)
+    :param close: close the polygon, defaults to False
+    :type close: bool, optional
+    :param kwargs: arguments passed to Patch
+    :return: Matplotlib artist
+    :rtype: line or patch
+
+    Example:
+
+    .. runblock:: pycon
+
+        >>> from spatialmath.base import plotvol2, plot_polygon
+        >>> plotvol2(5)
+        >>> vertices = np.array([[-1, 2, -1], [1, 0, -1]])
+        >>> plot_polygon(vertices, filled=True, facecolor='g')  # green filled triangle
+    """
 
     if close:
         vertices = np.hstack((vertices, vertices[:, [0]]))
@@ -471,7 +510,7 @@ def plot_circle(
     :param args:
     :param radius: radius of circle
     :type radius: float
-    :param resolution: number of points on circumferece, defaults to 50
+    :param resolution: number of points on circumference, defaults to 50
     :type resolution: int, optional
     :return: the matplotlib object
     :rtype: list of Line2D or Patch.Polygon
@@ -1168,17 +1207,13 @@ def plotvol2(dim, ax=None, equal=True, grid=False, labels=True):
 
     Initialize axes with dimensions given by ``dim`` which can be:
 
-        * A (scalar), -A:A x -A:A
-        * [A,B], A:B x A:B
-        * [A,B,C,D], A:B x C:D
-
-    ==================  ======  ======
-    input               xrange  yrange
-    ==================  ======  ======
-    A (scalar)          -A:A    -A:A
-    [A, B]              A:B     A:B
-    [A, B, C, D, E, F]  A:B     C:D
-    ==================  ======  ======
+    ==============  ======  ======
+    input           xrange  yrange
+    ==============  ======  ======
+    A (scalar)      -A:A    -A:A
+    [A, B]           A:B     A:B
+    [A, B, C, D]     A:B     C:D
+    ==============  ======  ======
 
     :seealso: :func:`plotvol3`, :func:`expand_dims`
     """
@@ -1259,7 +1294,7 @@ def plotvol3(
 
 def expand_dims(dim=None, nd=2):
     """
-    Expact compact axis dimensions
+    Expand compact axis dimensions
 
     :param dim: dimensions, defaults to None
     :type dim: scalar, array_like(2), array_like(4), array_like(6), optional

spatialmath/base/transforms3d.py

@@ -2242,29 +2242,25 @@ def rotvelxform_inv_dot(𝚪, 𝚪d, full=False, representation="rpy/xyz"):
     :return: derivative of inverse angular velocity transformation matrix
     :rtype: ndarray(6,6) or ndarray(3,3)
 
-    The angular rate transformation matrix :math:`\mat{A}` is such that
+    The angular rate transformation matrix :math:`\mat{A} \in \mathbb{R}^{6 \times 6}` is such that
 
     .. math::
 
         \dvec{x} = \mat{A}^{-1}(\Gamma) \vec{\nu}
 
-    where :math:`\vec{\Gamma} \in \mathbb{R}^3` is a minimal rotational 
-    representation and is used to transform a geometric Jacobian to an analytic Jacobians.
+    where :math:`\dvec{x} \in \mathbb{R}^6` is analytic velocity :math:`(\vec{v}, \dvec{\Gamma})`, 
+    :math:`\vec{\nu} \in \mathbb{R}^6` is spatial velocity :math:`(\vec{v}, \vec{\omega})`, and
+    :math:`\vec{\Gamma} \in \mathbb{R}^3` is a minimal rotational 
+    representation.
 
     The relationship between spatial and analytic acceleration is
 
     .. math::
 
-        \ddvec{x} = \dmat{A}^{-1}(\Gamma) \vec{\nu} + \mat{A}^{-1}(\Gamma) \dvec{\nu}
+        \ddvec{x} = \dmat{A}^{-1}(\Gamma, \dot{\Gamma) \vec{\nu} + \mat{A}^{-1}(\Gamma) \dvec{\nu}
 
-    which requires
+    and :math:`\dmat{A}^{-1}(\Gamma, \dot{\Gamma)` is computed by this function.
     
-    .. math::
-    
-        \frac{d}{dt} \mat{A}^{-1}(\Gamma) = \mat{A}^{-1}(\Gamma, \dot{\Gamma})
-
-    This matrix is a function of :math:`\vec{\Gamma}` and :math:`\dvec{\Gamma}`,
-    and is also required to compute the derivative of an analytic Jacobian.
         
     ============================  ========================================
     ``representation``            Rotational representation
@@ -2276,7 +2272,7 @@ def rotvelxform_inv_dot(𝚪, 𝚪d, full=False, representation="rpy/xyz"):
     ``"exp"``                     exponential coordinate rates
     ============================  ========================================
 
-    If ``full=False`` the lower-right 3x3 matrix is returned which transforms
+    If ``full=True`` a block diagonal 6x6 matrix is returned which transforms analytic
     analytic rotational acceleration to angular acceleration.
 
     Reference:

spatialmath/pose2d.py

@@ -251,10 +251,12 @@ def __init__(self, x=None, y=None, theta=None, *, unit='rad', check=True):
         """
         Construct new SE(2) object
 
-        :param unit: angular units 'deg' or 'rad' [default] if applicable :type
-        unit: str, optional :param check: check for valid SE(2) elements if
-        applicable, default to True :type check: bool :return: homogeneous
-        rigid-body transformation matrix :rtype: SE2 instance
+        :param unit: angular units 'deg' or 'rad' [default] if applicable 
+        :type unit: str, optional 
+        :param check: check for valid SE(2) elements if applicable, default to True 
+        :type check: bool 
+        :return: SE(2) matrix 
+        :rtype: SE2 instance
 
         - ``SE2()`` is an SE2 instance representing a null motion -- the
           identity matrix