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.

Sign up for GitHub

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
Open

Fix sphinx automation #162

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
826e6aa
Try replaceing github/petercorke with github/bdaiinstitute
myeatman-bdai Jan 30, 2025
797a8a6
Trying to figure out how to trigger the job.
myeatman-bdai Jan 30, 2025
2676c1a
...
myeatman-bdai Jan 30, 2025
8503e18
...
myeatman-bdai Jan 30, 2025
a3b850b
Okay I think this should work.
myeatman-bdai Jan 30, 2025
db451dc
...
myeatman-bdai Jan 30, 2025
c1315c9
Re-add don't trigger on PR.
myeatman-bdai Jan 30, 2025
ab1453a
Revert erenouius blanket replace of "github.com/petercorke" with "git…
myeatman-bdai Jan 31, 2025
aa0102b
Grammar.
myeatman-bdai Jan 31, 2025
062468a
Test sphinx auto run update from peter's repo.
myeatman-bdai Jan 31, 2025
3c87247
Merge branch 'master' into fix-sphinx-automation
myeatman-bdai Feb 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/sphinx.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ jobs:
run: |
python -m pip install --upgrade pip
pip install .[dev,docs]
pip install git+https://github.com/petercorke/sphinx-autorun.git
pip install git+https://github.com/petercorke/sphinx-autorun.git@105fa686606a7551ebf4e7adc1f13a315289e354
pip install sympy
sudo apt-get install graphviz
- name: Build docs
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 "action@github.com"
Expand Down
58 changes: 29 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Spatial Maths for Python

[![A Python Robotics Package](https://raw.githubusercontent.com/petercorke/robotics-toolbox-python/master/.github/svg/py_collection.min.svg)](https://github.com/petercorke/robotics-toolbox-python)
[![A Python Robotics Package](https://raw.githubusercontent.com/petercorke/robotics-toolbox-python/master/.github/svg/py_collection.min.svg)](https://github.com/bdaiinstitute/robotics-toolbox-python)
[![QUT Centre for Robotics Open Source](https://github.com/qcr/qcr.github.io/raw/master/misc/badge.svg)](https://qcr.github.io)

[![PyPI version](https://badge.fury.io/py/spatialmath-python.svg)](https://badge.fury.io/py/spatialmath-python)
Expand All @@ -20,7 +20,7 @@
<td style="border:0px">
<img src="https://github.com/bdaiinstitute/spatialmath-python/raw/master/docs/figs/CartesianSnakes_LogoW.png" width="200"></td>
<td style="border:0px">
A Python implementation of the <a href="https://github.com/petercorke/spatial-math">Spatial Math Toolbox for MATLAB<sup>&reg;</sup></a>
A Python implementation of the <a href="https://github.com/bdaiinstitute/spatial-math">Spatial Math Toolbox for MATLAB<sup>&reg;</sup></a>
Copy link
Collaborator

@petercorke petercorke Jan 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

revert, it refers to the MATLAB ancestor which is surely not at BDAI.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, sorry about that!

<ul>
<li><a href="https://github.com/bdaiinstitute/spatialmath-python">GitHub repository </a></li>
<li><a href="https://bdaiinstitute.github.io/spatialmath-python">Documentation</a></li>
Expand All @@ -45,8 +45,8 @@ space:
| ------------ | ---------------- | -------- |
| pose | ``SE3`` ``Twist3`` ``UnitDualQuaternion`` | ``SE2`` ``Twist2`` |
| orientation | ``SO3`` ``UnitQuaternion`` | ``SO2`` |


More specifically:

* `SE3` matrices belonging to the group $\mathbf{SE}(3)$ for position and orientation (pose) in 3-dimensions
Expand Down 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/bdaiinstitute/robotics-toolbox-python) as well Spatial Maths.

If the toolbox helped you in your research, please cite

Expand Down Expand Up @@ -160,26 +160,26 @@ For example, to create an object representing a rotation of 0.3 radians about th
>>> from spatialmath import SO3, SE3
>>> R1 = SO3.Rx(0.3)
>>> R1
1 0 0
0 0.955336 -0.29552
0 0.29552 0.955336
1 0 0
0 0.955336 -0.29552
0 0.29552 0.955336
```
while a rotation of 30 deg about the z-axis is

```python
>>> R2 = SO3.Rz(30, 'deg')
>>> R2
0.866025 -0.5 0
0.5 0.866025 0
0 0 1
0.866025 -0.5 0
0.5 0.866025 0
0 0 1
```
and the composition of these two rotations is
and the composition of these two rotations is

```python
>>> R = R1 * R2
0.866025 -0.5 0
0.433013 0.75 -0.5
0.25 0.433013 0.866025
0.866025 -0.5 0
0.433013 0.75 -0.5
0.25 0.433013 0.866025
```

We can find the corresponding Euler angles (in radians)
Expand All @@ -198,16 +198,16 @@ Frequently in robotics we want a sequence, a trajectory, of rotation matrices or
>>> len(R)
3
>>> R[1]
1 0 0
0 0.955336 -0.29552
0 0.29552 0.955336
1 0 0
0 0.955336 -0.29552
0 0.29552 0.955336
```
and this can be used in `for` loops and list comprehensions.

An alternative way of constructing this would be (`R1`, `R2` defined above)

```python
>>> R = SO3( [ SO3(), R1, R2 ] )
>>> R = SO3( [ SO3(), R1, R2 ] )
>>> len(R)
3
```
Expand All @@ -233,7 +233,7 @@ will produce a result where each element is the product of each element of the l
Similarly

```python
>>> A = SO3.Ry(0.5) * R
>>> A = SO3.Ry(0.5) * R
>>> len(R)
32
```
Expand All @@ -242,7 +242,7 @@ will produce a result where each element is the product of the left-hand side wi
Finally

```python
>>> A = R * R
>>> A = R * R
>>> len(R)
32
```
Expand All @@ -267,10 +267,10 @@ We can print and plot these objects as well
```
>>> T = SE3(1,2,3) * SE3.Rx(30, 'deg')
>>> T.print()
1 0 0 1
0 0.866025 -0.5 2
0 0.5 0.866025 3
0 0 0 1
1 0 0 1
0 0.866025 -0.5 2
0 0.5 0.866025 3
0 0 0 1

>>> T.printline()
t = 1, 2, 3; rpy/zyx = 30, 0, 0 deg
Expand Down Expand Up @@ -339,7 +339,7 @@ array([[1., 0., 1.],
[0., 0., 1.]])

transl2( (1,2) )
Out[444]:
Out[444]:
array([[1., 0., 1.],
[0., 1., 2.],
[0., 0., 1.]])
Expand All @@ -349,7 +349,7 @@ array([[1., 0., 1.],

```
transl2( np.array([1,2]) )
Out[445]:
Out[445]:
array([[1., 0., 1.],
[0., 1., 2.],
[0., 0., 1.]])
Expand Down Expand Up @@ -436,7 +436,7 @@ Out[259]: int

a = T[1,1]
a
Out[256]:
Out[256]:
cos(theta)
type(a)
Out[255]: cos
Expand All @@ -447,6 +447,6 @@ Similarly when we assign an element or slice of the symbolic matrix to a numeric

## History & Contributors

This package was originally created by [Peter Corke](https://github.com/petercorke) and [Jesse Haviland](https://github.com/jhavl) and was inspired by the [Spatial Math Toolbox for MATLAB](https://github.com/petercorke/spatialmath-matlab). It supports the textbook [Robotics, Vision & Control in Python 3e](https://github.com/petercorke/RVC3-python).
This package was originally created by [Peter Corke](https://github.com/bdaiinstitute) and [Jesse Haviland](https://github.com/jhavl) and was inspired by the [Spatial Math Toolbox for MATLAB](https://github.com/bdaiinstitute/spatialmath-matlab). It supports the textbook [Robotics, Vision & Control in Python 3e](https://github.com/bdaiinstitute/RVC3-python).

The package is now a collaboration with [Boston Dynamics AI Institute](https://theaiinstitute.com/).
61 changes: 29 additions & 32 deletions docs/source/intro.rst
View file
Open in desktop
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 @@ -718,9 +718,9 @@ Relationship to MATLAB tools
----------------------------

This package replicates, as much as possible, the functionality of the `Spatial
Math Toolbox <https://github.com/petercorke/spatial-math>`__ for MATLAB®
Math Toolbox <https://github.com/bdaiinstitute/spatial-math>`__ for MATLAB®
which underpins the `Robotics Toolbox
<https://github.com/petercorke/robotics-toolbox-matlab>`__ for MATLAB®. It
<https://github.com/bdaiinstitute/robotics-toolbox-matlab>`__ for MATLAB®. It
comprises:

* the *classic* functions (which date back to the origin of the Robotics Toolbox
Expand All @@ -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)



2 changes: 1 addition & 1 deletion tests/base/test_quaternions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# This file is part of the SpatialMath toolbox for Python
# https://github.com/petercorke/spatialmath-python
# https://github.com/bdaiinstitute/spatialmath-python
#
# MIT License
#
Expand Down
Loading