Skip to content

Commit 82b3537

Browse files
petercorkepetercorke
committed
more doco and examples
1 parent 9d2a1f1 commit 82b3537

6 files changed

Lines changed: 754 additions & 509 deletions

File tree

‎docs/source/intro.rst‎

Lines changed: 54 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ Introduction
77
Spatial maths capability underpins all of robotics and robotic vision.
88
It provides the means to describe the relative position and orientation of objects in 2D or 3D space.
99
This package provides Python classes and functions to represent, print, plot, manipulate and covert between such representations.
10-
This includes relevant mathematical objects such as rotation matrices :math:`R \in SO(2), SO(3)`,
11-
homogeneous transformation matrices :math:`T \in SE(2), SE(3)`, unit quaternions :math:`q \in S^3`,
12-
and twists :math:`t \in se(2), se(3)`.
10+
This includes relevant mathematical objects such as rotation matrices :math:`\mat{R} \in \SO{2}, \SO{3}`,
11+
homogeneous transformation matrices :math:`\mat{T} \in \SE{2}, \SE{3}`, unit quaternions :math:`\q \in \mathrm{S}^3`,
12+
and twists :math:`S \in \se{2}, \se{3}`.
1313

1414
For example, we can create a rigid-body transformation that is a rotation about the x-axis of 30 degrees:
1515

@@ -19,7 +19,8 @@ For example, we can create a rigid-body transformation that is a rotation about
1919
>>> rotx(30, 'deg')
2020

2121

22-
which results in a NumPy :math:`4 \times 4` array that belongs to the group SE(3). We could also create a class instance:
22+
which results in a NumPy :math:`4 \times 4` array that belongs to the group
23+
:math:`\SE{3}`. We could also create a class instance:
2324

2425
.. runblock:: pycon
2526

@@ -44,14 +45,12 @@ Spatial math classes
4445
The package provides classes to represent pose and orientation in 3D and 2D
4546
space:
4647

47-
============ ================== =============
48-
Represents in 3D in 2D
49-
============ ================== =============
50-
pose ``SE3``, ``SE2``,
51-
``Twist3`` ``Twist2``
52-
orientation ``SO3`` , ``SO2``
53-
``UnitQuaternion``
54-
============ ================== =============
48+
============ =========================== ===================
49+
Represents in 3D in 2D
50+
============ =========================== ===================
51+
pose ``SE3`` ``Twist3`` ``SE2`` ``Twist2``
52+
orientation ``SO3`` ``UnitQuaternion`` ``SO2``
53+
============ =========================== ===================
5554

5655
Additional classes include:
5756

@@ -62,24 +61,24 @@ Additional classes include:
6261
These classes abstract, and implement appropriate operations, for the following
6362
groups:
6463

65-
====================== ============================ =======================
66-
Group Name Class
67-
====================== ============================ =======================
68-
:math:`\mbox{SE(3)}` rigid-body translation in 3D ``SE3``
69-
:math:`\mbox{se(3)}` twist in 3D ``Twist3``
70-
:math:`\mbox{SO(3)}` orientation in 3D ``SO3``
71-
:math:`S^3` unit quaternion ``UnitQuaternion``
72-
:math:`\mbox{SE(2)}` rigid-body translation in 2D ``SE2``
73-
:math:`\mbox{se(2)}` twist in 2D ``Twist2``
74-
:math:`\mbox{SO(2)}` orientation in 2D ``SO2``
75-
:math:`\mathbb{H}` quaternion ``Quaternion``
76-
:math:`P^5` Plücker lines ``Plucker``
77-
:math:`M^6` spatial velocity ``SpatialVelocity``
78-
:math:`M^6` spatial acceleration ``SpatialAcceleration``
79-
:math:`F^6` spatial force ``SpatialForce``
80-
:math:`F^6` spatial momentum ``SpatialMomentum``
81-
| spatial inertia ``SpatialInertia``
82-
====================== ============================ =======================
64+
================================ ============================== ======================
65+
Group Name Class
66+
================================ ============================== ======================
67+
:math:`\SE{3}` rigid-body transformaton in 3D ``SE3``
68+
:math:`\se{3}` twist in 3D ``Twist3``
69+
:math:`\SO{3}` orientation in 3D ``SO3``
70+
:math:`\mathrm{S}^3` unit quaternion ``UnitQuaternion``
71+
:math:`\SE{2}` rigid-body transformaton in 2D ``SE2``
72+
:math:`\se{2}` twist in 2D ``Twist2``
73+
:math:`\SO{2}` orientation in 2D ``SO2``
74+
:math:`\mathbb{H}` quaternion ``Quaternion``
75+
:math:`P^5` Plücker lines ``Plucker``
76+
:math:`M^6` spatial velocity ``SpatialVelocity``
77+
:math:`M^6` spatial acceleration ``SpatialAcceleration``
78+
:math:`F^6` spatial force ``SpatialForce``
79+
:math:`F^6` spatial momentum ``SpatialMomentum``
80+
:math:`\mathbb{R}^{6 \times 6}` spatial inertia ``SpatialInertia``
81+
================================ ============================== ======================
8382

8483

8584
In addition to the merits of classes outlined above, classes ensure that the numerical value is always valid because the
@@ -180,10 +179,22 @@ Vector transformation
180179
The classes ``SE3``, ``SO3``, ``SE2``, ``SO2`` and ``UnitQuaternion`` support vector transformation when
181180
premultiplying a vector (or a set of vectors columnwise in a NumPy array) using the ``*`` operator.
182181
This is either rotation about the origin (for ``SO3``, ``SO2`` and ``UnitQuaternion``) or rotation and translation (``SE3``, ``SE2``).
182+
The implementation depends on the class of the object involved:
183183

184-
For ``UnitQuaternion`` this is performed directly using Hamilton products :math:`q \circ \mathring{v} \circ q^{-1}`.
185-
For ``SO3`` and ``SO2`` this is a matrix-vector product, for ``SE3`` and ``SE2`` this is a matrix-vector product with the vectors
186-
being first converted to homogeneous form, and the result converted back to Euclidean form.
184+
- for ``UnitQuaternion`` this is performed directly using Hamilton products
185+
:math:`\q \circ \mathring{v} \circ \q^{-1}`.
186+
- for ``SO3`` and ``SO2`` this is a matrix-vector product
187+
- for ``SE3`` and ``SE2`` this is a matrix-vector product with the vectors
188+
being first converted to homogeneous form, and the result converted back to
189+
Euclidean form.
190+
191+
.. runblock:: pycon
192+
193+
>>> from spatialmath import *
194+
>>> v = [1, 2, 3]
195+
>>> SO3.Rx(0.3) * v
196+
>>> SE3.Rx(0.3) * v
197+
>>> UnitQuaternion.Rx(0.3) * v
187198

188199
Non-group operations
189200
^^^^^^^^^^^^^^^^^^^^
@@ -198,7 +209,7 @@ performed elementwise, for example:
198209
>>> T = SE3.Rx(0.3)
199210
>>> T - T
200211

201-
or in the case of a scalar broadcast to each element:
212+
or, in the case of a scalar, broadcast to each element:
202213

203214
.. runblock:: pycon
204215

@@ -266,11 +277,16 @@ _indexcolor (None, 'yellow_2') Foreground, background color of index tag
266277
_format '{:< 12g}' Format string for each matrix element
267278
_suppress_small True Suppress *small* values, set to zero
268279
_suppress_tol 100 Threshold for *small* values in eps units
280+
_ansimatrix False Display as a matrix with brackets
269281
=============== =================== ============================================
270282

271283
For example::
272284

273-
>>> SE3._rotcolor = 'green'
285+
>>> SE3._rotcolor = 'green' # rotation part in green
286+
287+
or to supress color, perhaps for inclusion in documentation::
288+
289+
>>> SE3._color = False
274290

275291

276292
Graphics
@@ -375,7 +391,7 @@ a Python list
375391
where each item is an object of the same class as that it was extracted from.
376392
Slice notation is also available, eg. ``R[0:-1:3]`` is a new SO3 instance containing every third element of ``R``.
377393

378-
In particular it includes an iterator allowing comprehensions:
394+
In particular it supports iteration which allows looping and comprehensions:
379395

380396
.. runblock:: pycon
381397

@@ -412,7 +428,8 @@ Vectorization
412428
.. image:: ../figs/broadcasting.png
413429

414430
For most methods, if applied to an object that contains N elements, the result
415-
will be the appropriate return object type with N elements.
431+
will be the appropriate return object type with N elements. In MATLAB this is
432+
referred to as *vectorization* and in NumPy as *broadcasting*.
416433

417434
Most binary operations are vectorized: ``*``, ``*=``, ``**``, ``/``, ``/=``, ``+``, ``+=``, ``-``, ``-=``,
418435
``==``, ``!=``. For the case::

‎spatialmath/base/quaternions.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -675,15 +675,15 @@ def angle(q1, q2):
675675
return 2.0 * math.atan2(tr.norm(q1 - q2), tr.norm(q1 + q2))
676676

677677

678-
def qprint(q, delim=('<', '>'), fmt='%f', file=sys.stdout):
678+
def qprint(q, delim=('<', '>'), fmt='{: .4f}', file=sys.stdout):
679679
"""
680680
Format a quaternion
681681
682682
:arg q: unit-quaternion as a 4-vector
683683
:type q: array_like
684684
:arg delim: 2-list of delimeters [default ('<', '>')]
685685
:type delim: list or tuple of strings
686-
:arg fmt: printf-style format soecifier [default '%f']
686+
:arg fmt: printf-style format soecifier [default '{: .4f}']
687687
:type fmt: str
688688
:arg file: destination for formatted string [default sys.stdout]
689689
:type file: file object
@@ -703,8 +703,8 @@ def qprint(q, delim=('<', '>'), fmt='%f', file=sys.stdout):
703703
704704
"""
705705
q = argcheck.getvector(q, 4)
706-
template = "# %s #, #, # %s".replace('#', fmt)
707-
s = template % (q[0], delim[0], q[1], q[2], q[3], delim[1])
706+
template = "# {} #, #, # {}".replace('#', fmt)
707+
s = template.format(q[0], delim[0], q[1], q[2], q[3], delim[1])
708708
if file:
709709
file.write(s + '\n')
710710
else:

‎spatialmath/base/symbolic.py‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,14 @@
1212
_symbolics = False
1313
symtype = ()
1414

15-
15+
"""
16+
This package provides a light-weight wrapper to support use of SymPy. It
17+
generalizes some common functions so that they can accept numerical or
18+
Symbolic arguments.
19+
20+
If SymPy is not installed then only the standard numeric operations are
21+
supported.
22+
"""
1623
# ---------------------------------------------------------------------------------------#
1724

1825
def symbol(name, real=True):
@@ -75,9 +82,9 @@ def sin(theta):
7582
"""
7683
Generalized sine function
7784
78-
:param ϴ: argument
79-
:type ϴ: float or symbolic
80-
:return: sin(ϴ)
85+
:param θ: argument
86+
:type θ: float or symbolic
87+
:return: sin(θ)
8188
:rtype: float or symbolic
8289
8390
.. runblock:: pycon
@@ -98,9 +105,9 @@ def cos(theta):
98105
"""
99106
Generalized cosine function
100107
101-
:param ϴ: argument
102-
:type ϴ: float or symbolic
103-
:return: cos(ϴ)
108+
:param θ: argument
109+
:type θ: float or symbolic
110+
:return: cos(θ)
104111
:rtype: float or symbolic
105112
106113
.. runblock:: pycon

‎spatialmath/pose2d.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333

3434
class SO2(SMPose):
3535
"""
36-
SO(2) subclass
36+
SO(2) matrix class
3737
3838
This subclass represents rotations in 2D space. Internally it is a 2x2 orthogonal matrix belonging
3939
to the group SO(2).
@@ -231,7 +231,7 @@ def SE2(self):
231231

232232
class SE2(SO2):
233233
"""
234-
SE(2) subclass
234+
SE(2) matrix class
235235
236236
This subclass represents rigid-body motion (pose) in 2D space. Internally
237237
it is a 3x3 homogeneous transformation matrix belonging to the group SE(2).

0 commit comments

Comments
 (0)