Skip to content

Commit 88e91bb

Browse files
petercorkepetercorke
committed
more content
1 parent 28b2e0c commit 88e91bb

1 file changed

Lines changed: 48 additions & 36 deletions

File tree

‎docs/source/intro.rst‎

Lines changed: 48 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -41,30 +41,6 @@ While functions and classes can provide similar functionality the class provide
4141
- representing not a just a single value, but a sequence, which are handled by the operators with implicit broadcasting of values
4242

4343

44-
Relationship to MATLAB tools
45-
----------------------------
46-
This package replicates, as much as possible, the functionality of the `Spatial Math Toolbox <https://github.com/petercorke/spatial-math>`__ for MATLAB |reg|
47-
which underpins the `Robotics Toolbox <https://github.com/petercorke/robotics-toolbox-matlab>`__ for MATLAB. It comprises:
48-
49-
* the *classic* functions (which date back to the origin of the Robotics Toolbox for MATLAB) such as ``rotx``, ``trotz``, ``eul2tr`` etc. as the ``base`` package which you can access by::
50-
51-
from spatialmath.base import *
52-
53-
and works with NumPy arrays. This package also includes a set of functions to deal with quaternions and unit-quaternions represented as 4-element
54-
Numpy arrays.
55-
* the classes (which appeared in Robotics Toolbox for MATLAB release 10 in 2017) such as ``SE3``, ``UnitQuaternion`` etc. The only significant difference
56-
is that the MATLAB ``Twist`` class is now called ``Twist3``.
57-
58-
The design considerations included:
59-
60-
- being as similar as possible to the MATLAB Toolbox function names and semantics
61-
- but balancing the tension of being as Pythonic as possible
62-
- use Python keyword arguments to replace the MATLAB Toolbox string options supported using ``tb_optparse()``
63-
- use NumPy arrays internally to represent for rotation and homogeneous transformation matrices, quaternions and vectors
64-
- all functions that accept a vector can accept a list, tuple, or ``np.ndarray``
65-
- A class instance can hold a sequence of elements, they are polymorphic with lists, which can be used to represent trajectories or time sequences
66-
- Classes are _fairly_ polymorphic, they share many common constructor options and methods
67-
6844

6945
Spatial math classes
7046
====================
@@ -120,8 +96,13 @@ However a list of these items::
12096

12197
has the type `list` and the elements are not guaranteed to be homogeneous, ie. a list could contain a mixture of classes.
12298
This requires careful coding, or additional user code to check the validity of all elements in the list.
123-
We could create a NumPy array of these objects, the upside being it could be more than one-dimensional, but the again NumPy does not
124-
enforce homogeneity of object types in an array.
99+
We could create a NumPy array of these objects, the upside being it could be more than one-dimensional, but again NumPy does not
100+
enforce homogeneity of objectd within an array (with ``dtype='O'``).
101+
102+
.. image:: ../figs/pose-values.png
103+
:width: 600
104+
:alt: A SpatialMath pose class can hold multiple values
105+
125106

126107
The Spatial Math package give these classes list *super powers* so that, for example, a single `SE3` object can contain a sequence of SE(3) values::
127108

@@ -137,7 +118,7 @@ The Spatial Math package give these classes list *super powers* so that, for exa
137118
The classes inherit from ``collections.UserList`` and have all the functionality of Python lists, and this is discussed further in
138119
section :ref:`list-powers`
139120
The pose objects are a list subclass so we can index it or slice it as we
140-
would a list, but the result each time belongs to the class it was sliced from.
121+
would a list, but the result always belongs to the class it was sliced from.
141122

142123

143124
Operators for pose objects
@@ -282,7 +263,7 @@ The classes ``SE3``, ``SO3``, ``SE2`` and ``SO2`` can provide colorized text out
282263
>>> T = SE3()
283264
>>> T.print()
284265

285-
.. image:: ../../figs/colored_output.png
266+
.. image:: ../figs/colored_output.png
286267

287268
with rotational elements in red, translational elements in blue and constants in grey.
288269

@@ -294,7 +275,7 @@ Each class has a ``plot`` method that displays the corresponding pose as a coord
294275
>>> X = SE3.Rand()
295276
>>> X.plot()
296277

297-
.. image:: figs/fig1.png
278+
.. image:: ../figs/fig1.png
298279

299280
and there are many display options.
300281

@@ -303,7 +284,7 @@ The ``animate`` method animates the motion of the coordinate frame from the null
303284
>>> X = SE3.Rand()
304285
>>> X.animate(frame='A', arrow=False)
305286

306-
.. image:: figs/animate.gif
287+
.. image:: ../figs/animate.gif
307288

308289

309290
Constructors
@@ -421,6 +402,9 @@ Method Operation
421402
Vectorization
422403
-------------
423404

405+
.. image:: ../figs/broadcasting.png
406+
407+
424408
For most methods, if applied to an object that contains N elements, the result will be the appropriate return object type with N elements.
425409

426410
Most binary operations (`*`, `*=`, `**`, `+`, `+=`, `-`, `-=`, `==`, `!=`) are vectorized. For the case::
@@ -664,10 +648,35 @@ but you can't write a symbolic value into a floating point matrix
664648
.
665649
TypeError: can't convert expression to float
666650
667-
MATLAB compatability
668-
--------------------
651+
Relationship to MATLAB tools
652+
----------------------------
653+
654+
This package replicates, as much as possible, the functionality of the `Spatial Math Toolbox <https://github.com/petercorke/spatial-math>`__ for MATLAB |reg|
655+
which underpins the `Robotics Toolbox <https://github.com/petercorke/robotics-toolbox-matlab>`__ for MATLAB. It comprises:
656+
657+
* the *classic* functions (which date back to the origin of the Robotics Toolbox
658+
for MATLAB) such as ``rotx``, ``trotz``, ``eul2tr`` etc. which can be imported
659+
from the ``base`` package
660+
661+
from spatialmath.base import rotx, trotx
662+
663+
and works with NumPy arrays. This package also includes a set of functions, not present in the MATLAB version, to handle quaternions and unit-quaternions which are represented as 4-element
664+
Numpy arrays.
665+
* the classes (which appeared in Robotics Toolbox for MATLAB release 10 in 2017) such as ``SE3``, ``UnitQuaternion`` etc. The only significant difference
666+
is that the MATLAB ``Twist`` class is now called ``Twist3``.
667+
668+
The design considerations included:
669+
670+
- being as similar as possible to the MATLAB Toolbox function names and semantics
671+
- but balancing the tension of being as Pythonic as possible
672+
- use Python keyword arguments to replace the MATLAB Toolbox string options supported using ``tb_optparse()``
673+
- use NumPy arrays internally to represent for rotation and homogeneous transformation matrices, quaternions and vectors
674+
- all functions that accept a vector can accept a list, tuple, or ``np.ndarray``
675+
- A class instance can hold a sequence of elements, they are polymorphic with lists, which can be used to represent trajectories or time sequences
676+
- Classes are _fairly_ polymorphic, they share many common constructor options and methods
677+
669678

670-
We can create a MATLAB like environment by
679+
We can create a MATLAB-like environment by
671680

672681
.. code-block:: python
673682
@@ -678,10 +687,13 @@ which has familiar functions like ``rotx`` and ``rpy2r`` available, as well as c
678687

679688
.. code-block:: python
680689
681-
R = rotx(0.3)
682-
R2 = rpy2r(0.1, 0.2, 0.3)
690+
R = rotx(0.3)
691+
R2 = rpy2r(0.1, 0.2, 0.3)
692+
693+
T = SE3(1, 2, 3)
683694
684-
T = SE3(1, 2, 3)
695+
.. note:: None of the functions are *vectorized*, whereas many of the MATLAB
696+
equivalents are. Vectorization is done by the classes.
685697

686698
.. |reg| unicode:: U+000AE .. REGISTERED SIGN
687699

0 commit comments

Comments
 (0)