Robotics Toolbox for Python
Status & Project Health
Ecosystem & Dependencies
Contents
Synopsis
This toolbox brings robotics-specific functionality to Python, and leverages
Python's advantages of portability, ubiquity and support, and the capability of
the open-source ecosystem for linear algebra (numpy, scipy), graphics
(matplotlib, three.js, WebGL), interactive development (Jupyter, JupyterLab,
mybinder.org), and documentation (sphinx).
The Toolbox provides tools for representing the kinematics and dynamics of
serial-link manipulators - you can easily create your own in Denavit-Hartenberg
form, import a URDF file, or use over 50 supplied models for well-known
contemporary robots from Franka-Emika, Kinova, Universal Robotics, Rethink as
well as classical robots such as the Puma 560 and the Stanford arm.
The Toolbox contains fast implementations of kinematic operations. The forward
kinematics and the manipulator Jacobian can be computed in less than 1 microsecond
while numerical inverse kinematics can be solved in as little as 4 microseconds.
The toolbox also supports mobile robots with functions for robot motion models
(unicycle, bicycle), path planning algorithms (bug, distance transform, D*,
PRM), kinodynamic planning (lattice, RRT), localization (EKF, particle filter),
map building (EKF) and simultaneous localization and mapping (EKF).
The Toolbox provides:
- code that is mature and provides a point of comparison for other
implementations of the same algorithms;
- routines which are generally written in a straightforward manner which
allows for easy understanding, perhaps at the expense of computational
efficiency;
- source code which can be read for learning and teaching;
- backward compatability with the Robotics Toolbox for MATLAB
The Toolbox leverages the Spatial Maths Toolbox for Python to
provide support for data types such as SO(n) and SE(n) matrices, quaternions, twists and spatial vectors.
Getting going
You will need Python >= 3.10
Using pip
Install a snapshot from PyPI
pip install roboticstoolbox-python
Available options are:
swift install Swift, a web-based visualizerqp install quadratic-programming IK dependencies (qpsolvers, quadprog)collision install collision checking with coal and trimeshtool install IPython and pygments, needed to run the rtbtool interactive shellik install SymPy and python-flint, to derive analytic inverse kinematics (robot.analytic_ik())all install swift, qp, collision, and tool. It does not include ik, since SymPy is large and only needed to derive an analytic solver
Windows note: coal does not publish Windows wheels on PyPI, so the
collision/all extras skip it there and collision checking is
unavailable via pip on Windows. It's available via
conda install -c conda-forge coal-python if needed. Everything else in
the Toolbox works normally.
Put the options in a comma separated list like
pip install roboticstoolbox-python[optionlist]
If you want the Swift visualizer, install the swift extra.
Install matrix:
pip install roboticstoolbox-python
pip install roboticstoolbox-python[swift]
- QP solver dependencies only
pip install roboticstoolbox-python[qp]
- Collision checking dependencies only
pip install roboticstoolbox-python[collision]
rtbtool interactive shell dependencies only
pip install roboticstoolbox-python[tool]
- Analytic inverse kinematics dependencies only (SymPy,
python-flint)
pip install roboticstoolbox-python[ik]
- Everything except
ik (swift + qp + collision + tool)
pip install roboticstoolbox-python[all]
- Multiple extras explicitly
pip install roboticstoolbox-python[swift,qp,collision]
From GitHub
To install the bleeding-edge version from GitHub
git clone https://github.com/petercorke/robotics-toolbox-python.git
cd robotics-toolbox-python
pip install -e .
To generate a Wasm wheel that will run in the browser see the instructions here.
Tutorials
Code Examples
We will load a model of the Franka-Emika Panda robot defined by a URDF file
import roboticstoolbox as rtb
robot = rtb.models.Panda()
print(robot)
URDFRobot.Panda: panda (by Franka Emika), 7 joints (RRRRRRR), 1 gripper, geometry, collision
┌─────┬──────────────┬───────┬─────────────┬────────────────────────────────────────────────┐
│link │ link │ joint │ parent │ ETS: parent to link │
├─────┼──────────────┼───────┼─────────────┼────────────────────────────────────────────────┤
│ 0 │ panda_link0 │ │ BASE │ │
│ 1 │ panda_link1 │ 0 │ panda_link0 │ SE3(0, 0, 0.333) ⊕ Rz(q0) │
│ 2 │ panda_link2 │ 1 │ panda_link1 │ SE3(-90°, -0°, 0°) ⊕ Rz(q1) │
│ 3 │ panda_link3 │ 2 │ panda_link2 │ SE3(0, -0.316, 0; 90°, -0°, 0°) ⊕ Rz(q2) │
│ 4 │ panda_link4 │ 3 │ panda_link3 │ SE3(0.0825, 0, 0; 90°, -0°, 0°) ⊕ Rz(q3) │
│ 5 │ panda_link5 │ 4 │ panda_link4 │ SE3(-0.0825, 0.384, 0; -90°, -0°, 0°) ⊕ Rz(q4) │
│ 6 │ panda_link6 │ 5 │ panda_link5 │ SE3(90°, -0°, 0°) ⊕ Rz(q5) │
│ 7 │ panda_link7 │ 6 │ panda_link6 │ SE3(0.088, 0, 0; 90°, -0°, 0°) ⊕ Rz(q6) │
│ 8 │ @panda_link8 │ │ panda_link7 │ SE3(0, 0, 0.107) │
└─────┴──────────────┴───────┴─────────────┴────────────────────────────────────────────────┘
┌─────┬─────┬────────┬─────┬───────┬─────┬───────┬──────┐
│name │ q0 │ q1 │ q2 │ q3 │ q4 │ q5 │ q6 │
├─────┼─────┼────────┼─────┼───────┼─────┼───────┼──────┤
│ qr │ 0° │ -17.2° │ 0° │ -126° │ 0° │ 115° │ 45° │
│ qz │ 0° │ 0° │ 0° │ 0° │ 0° │ 0° │ 0° │
└─────┴─────┴────────┴─────┴───────┴─────┴───────┴──────┘
The symbol @ indicates the link as an end-effector, a leaf node in the rigid-body
tree (Python prompts are not shown to make it easy to copy+paste the code, console output is indented).
We will compute the forward kinematics next
Te = robot.fkine(robot.qr) # forward kinematics
print(Te)
0.995 0 0.09983 0.484
0 -1 0 0
0.09983 0 -0.995 0.4126
0 0 0 1
We can solve inverse kinematics very easily. We first choose an SE(3) pose
defined in terms of position and orientation (end-effector z-axis down (A=-Z) and finger
orientation parallel to y-axis (O=+Y)).
from spatialmath import SE3
Tep = SE3.Trans(0.6, -0.3, 0.1) * SE3.OA([0, 1, 0], [0, 0, -1])
sol = robot.ik_LM(Tep) # solve IK, with the fast C++ solver (ikine_LM is the Python one)
print(sol)
IKSolution: q=[-2.709, -1.176, 1.961, -1.642, 1.173, 1.958, 2.876], success=True, iterations=6, searches=1, residual=1.06e-07
q_pickup = sol.q
print(robot.fkine(q_pickup)) # FK shows that desired end-effector pose was achieved
-1 0.0002931 0.0003122 0.5999
0.0002931 1 7.601e-05 -0.2999
-0.0003121 7.611e-05 -1 0.1001
0 0 0 1
We can animate a path from the ready pose qr configuration to this pickup configuration
qt = rtb.jtraj(robot.qr, q_pickup, 50)
robot.plot(qt.q, backend='pyplot', movie='panda1.gif')
where we have specified the matplotlib pyplot backend. Blue arrows show the joint axes and the coloured frame shows the end-effector pose.
We can also plot the trajectory in the Swift simulator (a browser-based 3d-simulation environment built to work with the Toolbox)
robot.plot(qt.q)
We can also experiment with velocity controllers in Swift. Here is a resolved-rate motion control example
import swift
import roboticstoolbox as rtb
import spatialmath as sm
import numpy as np
env = swift.Swift()
env.launch(realtime=True)
panda = rtb.models.Panda()
handle = env.add(panda)
handle.q = panda.qr
Tep = panda.fkine(handle.q) * sm.SE3.Trans(0.2, 0.2, 0.45)
arrived = False
dt = 0.05
while not arrived:
v, arrived = rtb.p_servo(panda.fkine(handle.q), Tep, 1)
handle.qd = np.linalg.pinv(panda.jacobe(handle.q)) @ v
env.step(dt)
# Uncomment to stop the browser tab from closing
# env.hold()
env.add(panda) returns a handle owning this instance's live joint state --
drive the simulation via handle.q/handle.qd, not panda.q/panda.qd
directly. panda itself stays a plain, shareable kinematic model, so the
same panda object can back several independent handles/instances at once.
Loading models from robot_descriptions
The Panda example above uses one of the ~50 models shipped with the Toolbox, but many more
robots are available on demand via the robot_descriptions
package, which is installed automatically as a dependency. Passing a bare name (no file suffix)
to URDFRobot fetches and loads it from there:
from roboticstoolbox.models.URDF.URDFRobot import URDFRobot
ur5 = URDFRobot("ur5")
rtb.models.catalog() lists everything available — the models built into the Toolbox as well
as those it can load from robot_descriptions — with filtering by keyword/DoF/model type and
column sorting:
rtb.models.catalog(mtype="URDF", sorton="name")
Run some examples
The notebooks folder contains some tutorial Jupyter notebooks which you can browse on GitHub. Additionally, have a look in the examples folder for many ready to run examples.
References
Key papers
- P. Corke, "A computer tool for simulation and analysis: the Robotics Toolbox for MATLAB," Proc. National Conf. Australian Robot Association, pp. 319–330, Melbourne, July 1995. [PDF]
- P. Corke, "A robotics toolbox for MATLAB," IEEE Robotics and Automation Magazine, 3(1):24–32, Sept. 1996. [IEEE Xplore]
- P. Corke, "A simple and systematic approach to assigning Denavit-Hartenberg parameters," IEEE Transactions on Robotics, 23(3):590–594, 2007. [IEEE Xplore] — introduces the Elementary Transform Sequence (ETS) notation used throughout the Toolbox.
- J. Haviland and P. Corke, "A systematic approach to computing the manipulator Jacobian and Hessian using the elementary transform sequence," arXiv preprint, 2020. [arXiv]
- P. Corke and J. Haviland, "Not your grandmother's toolbox – the Robotics Toolbox reinvented for Python," Proc. ICRA 2021. [IEEE Xplore] [PDF]
Talks
Related book
The Toolbox is a companion to Peter Corke's textbook Robotics, Vision & Control (Springer) — many docstrings and examples reference specific figures/sections from the book.
Citing the Toolbox
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!
For the powered by robotics toolbox badge
copy the following
[](https://github.com/petercorke/robotics-toolbox-python)
For the powered by python robotics badge
copy the following
[](https://github.com/petercorke/robotics-toolbox-python)
Common Issues and Solutions
See the common issues with fixes here.
Using the Toolbox with Windows?
Graphical visualisation via Swift is currently not supported under Windows. However there is a hotfix, by changing in SwiftRoute.py
self.path[9:] to self.path[10:]
Toolbox Research Applications
The toolbox is incredibly useful for developing and prototyping algorithms for research, thanks to the exhaustive set of well documented and mature robotic functions exposed through clean and painless APIs. Additionally, the ease at which a user can visualize their algorithm supports a rapid prototyping paradigm.
It's been the implementation substrate for several published reactive-control papers, and its kinematics are a direct implementation of a two-part differential-kinematics tutorial — see the wiki's Reactive control and Inverse kinematics pages.
