Spatial Maths for Python

Spatial mathematics capability underpins all of robotics and robotic vision where we need to describe the position, orientation or pose of objects in 2D or 3D spaces.

What it does

The package provides classes to represent pose and orientation in 3D and 2D space:

Represents	in 3D	in 2D
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
• SO3 matrices belonging to the group $\mathbf{SO}(3)$ for orientation in 3-dimensions
• UnitQuaternion belonging to the group $\mathbf{S}^3$ for orientation in 3-dimensions
• Twist3 vectors belonging to the group $\mathbf{se}(3)$ for pose in 3-dimensions
• UnitDualQuaternion maps to the group $\mathbf{SE}(3)$ for position and orientation (pose) in 3-dimensions
• SE2 matrices belonging to the group $\mathbf{SE}(2)$ for position and orientation (pose) in 2-dimensions
• SO2 matrices belonging to the group $\mathbf{SO}(2)$ for orientation in 2-dimensions
• Twist2 vectors belonging to the group $\mathbf{se}(2)$ for pose in 2-dimensions

These classes provide convenience and type safety, as well as methods and overloaded operators to support:

• composition, using the * operator
• point transformation, using the * operator
• exponent, using the ** operator
• normalization
• inversion
• connection to the Lie algebra via matrix exponential and logarithm operations
• conversion of orientation to/from Euler angles, roll-pitch-yaw angles and angle-axis forms.
• list operations such as append, insert and get

These are layered over a set of base functions that perform many of the same operations but represent data explicitly in terms of numpy arrays.

The class, method and functions names largely mirror those of the MATLAB toolboxes, and the semantics are quite similar.

Citing

Check out our ICRA 2021 paper on IEEE Xplore or get the PDF from Peter's website. This describes the Robotics Toolbox for Python as well as Spatial Maths.

If the toolbox helped you in your research, please cite

@inproceedings{rtb,
  title={Not your grandmother’s toolbox--the Robotics Toolbox reinvented for Python},
  author={Corke, Peter and Haviland, Jesse},
  booktitle={2021 IEEE International Conference on Robotics and Automation (ICRA)},
  pages={11357--11363},
  year={2021},
  organization={IEEE}
}

Using the Toolbox in your Open Source Code?

If you are using the Toolbox in your open source code, feel free to add our badge to your readme!

Simply copy the following

[![Powered by the Spatial Math Toolbox](https://github.com/rai-opensource/spatialmath-python/raw/master/.github/svg/sm_powered.min.svg)](https://github.com/rai-opensource/spatialmath-python)

Installation

Using pip

Install a snapshot from PyPI

pip install spatialmath-python

Note that if you are using ROS2, you may run into version conflicts when using rosdep, particularly concerning matplotlib. If this happens, you can enable optional version pinning with

pip install spatialmath-python[ros-humble]

From GitHub

Install the current code base from GitHub and pip install a link to that cloned copy

git clone https://github.com/rai-opensource/spatialmath-python.git
cd spatialmath-python
pip install -e .
# Optional: if you would like to contribute and commit code changes to the repository,
# install the development tools (including pre-commit) and set up the git hooks
# pip install -e .[dev]
# pre-commit install

Dependencies

numpy, scipy, matplotlib, ffmpeg (if rendering animations as a movie)

Examples

High-level classes

These classes abstract the low-level numpy arrays into objects that obey the rules associated with the mathematical groups SO(2), SE(2), SO(3), SE(3) as well as twists and quaternions.

This is the beginning of the README. Read the rest at the original. Read the full README ↗