# spatialmath-python gives Python the pose and orientation types robotics code assumes

> rai-opensource/spatialmath-python is an MIT licensed Python implementation of the Spatial Math Toolbox for MATLAB, providing classes for pose and orientation in 2D and 3D that follow the rules of the Lie groups SO(2), SE(2), SO(3) and SE(3), with operators for composition, point transformation, inversion and conversion to Euler angles. The classes exist to stop you mixing a 2D transform with a 3D rotation, and the naming follows the MATLAB toolbox it ports.

**rai-opensource/spatialmath-python** — Create,  manipulate and convert representations of position and orientation in 2D or 3D using Python

- Repository: https://github.com/rai-opensource/spatialmath-python
- Website: http://spatialmath-python.rai-inst.com/
- Stars: 650 · Forks: 107
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/rai-opensource-spatialmath-python

## The classes exist to stop you mixing dimensions

The package provides classes to represent pose and orientation in 3D and 2D space, and the reason to use classes rather than plain arrays is stated directly in the documentation. Using classes ensures type safety, for example it stops us mixing a 2D homogeneous transformation with a 3D rotation matrix, both of which are 3x3 matrices. That is a small problem on paper and a real one in practice, because the two matrices have the same shape and completely different meanings, and nothing in numpy will warn you. The classes are layered over a set of base functions that perform many of the same operations but represent data explicitly in terms of numpy arrays, so the low level interface remains available when you want it. The class, method and function names largely mirror those of the MATLAB toolboxes, and the semantics are quite similar, which means code and habits transfer between the two.

## The class set is the Lie groups and their algebras

The table in the README is the map of the package. In 3D, pose is represented by SE3 matrices, Twist3 vectors and UnitDualQuaternion, and orientation by SO3 matrices and UnitQuaternion. In 2D, pose is SE2 and Twist2, and orientation is SO2. Each class is named for the group it belongs to, and the documentation is explicit about the mapping. SE3 matrices belong to the group SE(3) for position and orientation in 3 dimensions, SO3 matrices to SO(3) for orientation in 3 dimensions, UnitQuaternion to the group S^3 for orientation in 3 dimensions, Twist3 vectors to the group se(3) for pose in 3 dimensions, and UnitDualQuaternion maps to the group SE(3) for position and orientation. The 2D classes follow the same pattern with SE(2), SO(2) and se(2). The naming is not decoration. It tells you at a glance whether a value is a rotation, a rigid body transform, a screw motion or a quaternion, and it is the same convention the wider robotics literature uses.

## Operators for composition, transformation and the Lie algebra

The convenience comes from the operator overloading, and the README lists what each operator means. Composition uses the * operator, and so does point transformation, so a pose times a point moves the point and a pose times a pose composes them. Exponent uses the ** operator, which is how you go between a group element and its Lie algebra representation. Beyond the operators, the classes support normalization, inversion, connection to the Lie algebra via matrix exponential and logarithm operations, conversion of orientation to and from Euler angles, roll-pitch-yaw angles and angle-axis forms, and list operations such as append, insert and get. The composition and point transformation sharing one operator is worth noting, because it is convenient and it is also the thing that a reader has to learn once. The base functions underneath can perform the same operations with numpy arrays directly, which is the escape hatch when you need to work with raw data.

## Installing from PyPI, or from a clone for contributors

The release path is the standard one:

```bash
pip install spatialmath-python
```

There is a specific wrinkle for ROS 2 users, and the README is direct about it. If you are using ROS2, you may run into version conflicts when using rosdep, particularly concerning matplotlib, and the fix is an optional version pinning extra:

```bash
pip install spatialmath-python[ros-humble]
```

For a development install, the instructions are to clone the repository and pip install a link to that cloned copy:

```bash
git clone https://github.com/rai-opensource/spatialmath-python.git
cd spatialmath-python
pip install -e .
```

and, if you intend to contribute and commit changes, a pre-commit install step, which the repository supports with a .pre-commit-config.yaml at the root. The declared dependencies are numpy, scipy, matplotlib and ffmpeg, the last of which is needed if you are rendering animations as a movie, and the manifest adds ansitable and typing_extensions. The package requires Python 3.10 or newer, and the classifiers list 3.10 through 3.14.

## The Makefile covers tests, coverage, docs and upload

The repository ships a Makefile whose help target lists the whole developer workflow, which is a quick way to see what the project expects of a contributor. The entries are make test to run all unit tests, make coverage to run unit tests and a coverage report, make docs to build the Sphinx documentation, make dist to build dist files, make upload to upload to PyPI, and make clean to remove dist and docs build files. The test target is a single pytest call, and the coverage target runs coverage with the source pinned to the spatialmath package, then reports and renders HTML. The docs target shells into the docs directory and runs make html there, so the documentation is a separate Sphinx project rather than something generated from the module. The dist target calls the build module and the upload target uses twine, which is the conventional pair for a package that is published to PyPI from a repository.

## Documentation, notebooks and the paper to cite

The documentation for the package is hosted separately from the repository, and the README links a documentation site, a wiki with examples and details, and a page of recent changes. The repository itself carries a docs directory, a notebooks directory, a benchmarks directory, a symbolic directory, a tests directory and the spatialmath package directory, so the example files are versioned alongside the code. There is also a citation request, and the README points at an ICRA 2021 paper on IEEE Xplore with a PDF on the author's site, describing the Robotics Toolbox for Python as well as Spatial Maths. The bibliography entry is given in full so that citing the package is a copy and paste job rather than an exercise in archaeology. The Python Robotics Package and the QUT Centre for Robotics Open Source badges at the top of the README signal the same thing from the other direction, that this code sits inside an academic robotics ecosystem rather than standing alone.

## The alternative is the base functions, or the original MATLAB toolbox

There are two honest alternatives, and they suit different situations. The first is to use the base functions instead of the classes. They perform many of the same operations but represent data explicitly in terms of numpy arrays, which is the right choice when you are working with a large array of poses, when you want to keep everything as plain arrays for a downstream library, or when the type checking gets in the way of a transformation that numpy can express directly. The second is the MATLAB Spatial Math Toolbox itself, which this package implements, with the class, method and function names mirroring it and the semantics quite similar. If your team already works in MATLAB, or your reference implementations are in MATLAB, the toolbox is the shorter path, and this package is the route to take when the surrounding code is Python. The Robotics Toolbox for Python is a related project in the same family, and the citing paper covers both.

## Conclusion

Adopt spatialmath-python if you are writing robotics or computer vision code in Python and want pose and orientation objects that carry the group algebra with them, since the classes give you type safety between 2D and 3D and a consistent operator vocabulary. Do not adopt it if you need the full robotics stack, because this is the spatial mathematics layer that the Robotics Toolbox for Python builds on. Before you install, check the dependency list, which includes ffmpeg for rendering animations as a movie, and decide whether you want the released package from PyPI or an editable install of the repository for contributing, and note that the package requires Python 3.10 or newer.

## FAQ

### What does spatialmath-python provide?

Classes to represent pose and orientation in 3D and 2D space, including SE3, Twist3, UnitDualQuaternion, SE2, Twist2, SO3, UnitQuaternion and SO2, with operators for composition, point transformation, exponent, normalization, inversion, Lie algebra connection and conversion to and from Euler, roll-pitch-yaw and angle-axis forms.

### Why use the classes instead of plain numpy arrays?

The README states that using classes ensures type safety, for example it stops you mixing a 2D homogeneous transformation with a 3D rotation matrix, since both are 3x3 matrices. The classes are layered over base functions that do the same operations with data represented explicitly as numpy arrays, so the low level interface is still available.

### How do I install spatialmath-python with ROS 2?

A plain pip install of spatialmath-python can run into version conflicts with rosdep, particularly around matplotlib. The README says you can enable optional version pinning with pip install spatialmath-python[ros-humble].

### What does the spatialmath-python Makefile do?

The help target lists make test to run the unit tests, make coverage for a coverage report, make docs to build the Sphinx documentation, make dist to build the distribution files, make upload to publish to PyPI with twine, and make clean to remove the dist and docs build files.

### What are the dependencies of spatialmath-python?

The README lists numpy, scipy, matplotlib and ffmpeg, the last being needed if you render animations as a movie. The project manifest also depends on ansitable and typing_extensions, requires Python 3.10 or newer, and offers a dev extra with sympy, pytest and related tooling.

## Sources

- [License: MIT](https://github.com/rai-opensource/spatialmath-python/blob/master/LICENSE)
- [Project website](http://spatialmath-python.rai-inst.com/)
- [rai-opensource/spatialmath-python on GitHub](https://github.com/rai-opensource/spatialmath-python)
- [README](https://github.com/rai-opensource/spatialmath-python/blob/master/README.md)
- [Releases](https://github.com/rai-opensource/spatialmath-python/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rai-opensource-spatialmath-python