Skip to content

Fix sphinx automation #162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: master
Choose a base branch
from
4 changes: 2 additions & 2 deletions .github/workflows/sphinx.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ on:
jobs:
sphinx:
runs-on: ubuntu-22.04
if: ${{ github.event_name != 'pull_request' }}
# if: ${{ github.event_name != 'pull_request' }}
steps:
- uses: actions/checkout@v2
- name: Set up Python 3.8
Expand All @@ -29,7 +29,7 @@ jobs:
cd ../
- name: Commit documentation changes
run: |
git clone https://github.com/petercorke/spatialmath-python.git --branch gh-pages --single-branch gh-pages
git clone https://github.com/bdaiinstitute/spatialmath-python.git --branch gh-pages --single-branch gh-pages
cp -r docs/build/html/* gh-pages/
cd gh-pages
git config --local user.email "[email protected]"
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ The class, method and functions names largely mirror those of the MATLAB toolbox

# Citing

Check out our ICRA 2021 paper on [IEEE Xplore](https://ieeexplore.ieee.org/document/9561366) or get the PDF from [Peter's website](https://bit.ly/icra_rtb). This describes the [Robotics Toolbox for Python](https://github.com/petercorke/robotics-toolbox-python) as well Spatial Maths.
Check out our ICRA 2021 paper on [IEEE Xplore](https://ieeexplore.ieee.org/document/9561366) or get the PDF from [Peter's website](https://bit.ly/icra_rtb). This describes the [Robotics Toolbox for Python](https://github.com/petercorke/robotics-toolbox-python) as well as Spatial Maths.

If the toolbox helped you in your research, please cite

Expand Down
57 changes: 27 additions & 30 deletions docs/source/intro.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ Introduction
************


Spatial maths capability underpins all of robotics and robotic vision.
It provides the means to describe the relative position and orientation of objects in 2D or 3D space.
Spatial maths capability underpins all of robotics and robotic vision.
It provides the means to describe the relative position and orientation of objects in 2D or 3D space.
This package provides Python classes and functions to represent, print, plot, manipulate and covert between such representations.
This includes relevant mathematical objects such as rotation matrices :math:`\mat{R} \in \SO{2}, \SO{3}`,
This includes relevant mathematical objects such as rotation matrices :math:`\mat{R} \in \SO{2}, \SO{3}`,
homogeneous transformation matrices :math:`\mat{T} \in \SE{2}, \SE{3}`, unit quaternions :math:`\q \in \mathrm{S}^3`,
and twists :math:`S \in \se{2}, \se{3}`.

Expand All @@ -27,7 +27,7 @@ which results in a NumPy :math:`4 \times 4` array that belongs to the group
>>> from spatialmath import *
>>> T = SE3.Rx(30, 'deg')
>>> type(T)
>>> print(T)
>>> print(T)

which is *internally* represented as a :math:`4 \times 4` NumPy array.

Expand Down Expand Up @@ -81,7 +81,7 @@ Group Name Class
================================ ============================== ======================


In addition to the merits of classes outlined above, classes ensure that the numerical value is always valid because the
In addition to the merits of classes outlined above, classes ensure that the numerical value is always valid because the
constraints (eg. orthogonality, unit norm) are enforced when the object is constructed. For example::

>>> SE3(np.zeros((4,4)))
Expand All @@ -90,7 +90,7 @@ constraints (eg. orthogonality, unit norm) are enforced when the object is const
.
AssertionError: array must have valid value for the class

Type safety and type validity are particularly important when we deal with a sequence of values.
Type safety and type validity are particularly important when we deal with a sequence of values.
In robotics we frequently deal with a multiplicity of objects (poses, cameras), or a trajectory of
objects moving over time.
However a list of these items, for example::
Expand All @@ -114,7 +114,7 @@ The Spatial Math package give these classes list *super powers* so that, for exa
>>> from spatialmath import *
>>> X = SE3.Rx([0, 0.2, 0.4, 0.6])
>>> len(X)
>>> print(X[1])
>>> print(X[1])


The classes form a rich hierarchy
Expand All @@ -127,7 +127,7 @@ The classes form a rich hierarchy
Ultimately they all inherit from ``collections.UserList`` and have all the functionality of Python lists, and this is discussed further in
section :ref:`list-powers`
The pose objects are a list subclass so we can index it or slice it as we
would a list, but the result always belongs to the class it was sliced from.
would a list, but the result always belongs to the class it was sliced from.


Operators for pose objects
Expand Down Expand Up @@ -176,9 +176,9 @@ Vector transformation
^^^^^^^^^^^^^^^^^^^^^


The classes ``SE3``, ``SO3``, ``SE2``, ``SO2`` and ``UnitQuaternion`` support vector transformation when
The classes ``SE3``, ``SO3``, ``SE2``, ``SO2`` and ``UnitQuaternion`` support vector transformation when
premultiplying a vector (or a set of vectors columnwise in a NumPy array) using the ``*`` operator.
This is either rotation about the origin (for ``SO3``, ``SO2`` and ``UnitQuaternion``) or rotation and translation (``SE3``, ``SE2``).
This is either rotation about the origin (for ``SO3``, ``SO2`` and ``UnitQuaternion``) or rotation and translation (``SE3``, ``SE2``).
The implementation depends on the class of the object involved:

- for ``UnitQuaternion`` this is performed directly using Hamilton products
Expand Down Expand Up @@ -238,7 +238,7 @@ Compare this to the unit quaternion case:
>>> 2 * q

Noting that unit quaternions are denoted by double angle bracket delimiters of their vector part,
whereas a general quaternion uses single angle brackets. The product of a general quaternion and a
whereas a general quaternion uses single angle brackets. The product of a general quaternion and a
unit quaternion is always a general quaternion.


Expand Down Expand Up @@ -386,7 +386,7 @@ a Python list
>>> len(R)
>>> R = SO3.Rx(np.arange(0, 2*np.pi, 0.2))
>>> len(R)
>>> R[0]
>>> R[0]
>>> R[-1]
>>> R[2:4]

Expand All @@ -404,12 +404,12 @@ In particular it supports iteration which allows looping and comprehensions:
>>> eul = [x.eul() for x in R]
>>> len(eul)
>>> eul[10]

Useful functions that be used on such objects include

============= ================================================
============= ================================================
Method Operation
============= ================================================
============= ================================================
``clear`` Clear all elements, object now has zero length
``append`` Append a single element
``del``
Expand All @@ -421,7 +421,7 @@ Method Operation
``pop`` Remove first element and return it
``slice`` Index from a slice object
``zip`` Iterate over the elments
============= ================================================
============= ================================================


Vectorization
Expand All @@ -444,7 +444,7 @@ the lengths of the operands and the results are given by
====== ====== ====== ========================
operands results
--------------- --------------------------------
len(X) len(Y) len(Z) results
len(X) len(Y) len(Z) results
====== ====== ====== ========================
1 1 1 Z = X op Y
1 M M Z[i] = X op Y[i]
Expand Down Expand Up @@ -523,34 +523,34 @@ Spatial object equivalent class NumPy ndarray.shape
n/a Quaternion (4,)
================= ================ ===================

.. note:: ``SpatialVector`` and ``Line3`` objects have no equivalent in the
.. note:: ``SpatialVector`` and ``Line3`` objects have no equivalent in the
``base`` package.

Inputs to functions in this package are either floats, lists, tuples or
numpy.ndarray objects describing vectors or arrays.
numpy.ndarray objects describing vectors or arrays.

NumPy arrays have a shape described by a shape tuple which is a list of the
dimensions. Typically all ``ndarray`` **vectors** have the shape ``(N,)``, that is,
they have only one dimension. The ``@`` product of an ``(M,N)`` array and a ``(N,)``
vector is an ``(M,)`` vector.
vector is an ``(M,)`` vector.

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.
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:
- 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
- Iterating over a 2D NumPy array is done by row, not columns as in MATLAB.
- Iterating over a 2D NumPy array is done by row, not columns as in MATLAB.
- Iterating over a row vector ``(1,N)`` returns the entire row
- Iterating a column vector ``(N,1)`` returns consecutive elements (rows).

.. note::
- Functions that require vector can be passed a list, tuple or numpy.ndarray
for a vector -- described in the documentation as being of type
*array_like*.
*array_like*.
- This toolbox documentation refers to NumPy arrays succinctly as:

- ``ndarray(N)`` for a 1D array of length ``N``
Expand Down Expand Up @@ -633,7 +633,7 @@ If ``matplotlib`` is installed then we can add 2D coordinate frames to a figure
>>> trplot2( transl2(4, 3)@trot2(math.pi/3), color='green', frame='c')
>>> plt.grid(True)

.. figure:: ../figs/transforms2d.png
.. figure:: ../figs/transforms2d.png
:align: center

Output of ``trplot2``
Expand Down Expand Up @@ -689,7 +689,7 @@ matrix
>>> a
>>> type(a)
>>> a = T[1,1]
>>> a
>>> a
>>> type(a)

We see that the symbolic constants have been converted back to Python numeric
Expand Down Expand Up @@ -730,7 +730,7 @@ comprises:
>>> from spatialmath.base import rotx, trotx

and works with NumPy arrays. This package also includes a set of functions,
not present in the MATLAB version, to handle quaternions, unit-quaternions
not present in the MATLAB version, to handle quaternions, unit-quaternions
which are represented as 4-element NumPy arrays, and twists.
* the classes (which appeared in Robotics Toolbox for MATLAB release 10 in 2017) such as ``SE3``, ``UnitQuaternion`` etc. The only significant difference
is that the MATLAB ``Twist`` class is now called ``Twist3``.
Expand Down Expand Up @@ -766,6 +766,3 @@ which has the familiar *classic* functions like ``rotx`` and ``rpy2r`` available
R2 = rpy2r(0.1, 0.2, 0.3)

T = SE3(1, 2, 3)



Loading