Robotics Toolbox for Python 1.5.0
Analytic inverse kinematics for any six-axis arm. robot.ikine_analytic(T) returns every solution in closed form, for spherical-wrist arms, arms with three parallel axes, and general 6R arms such as the Kinova Jaco. It can also write the solver out as Python, C, C++ or Rust. Install with pip install roboticstoolbox-python[ik]. All the IK methods return an IKSolution, which is a sequence of the rows of q, and is true if the solve succeeded.
Mobile robotics brought up to standard. The planners, EKF, particle filter, pose graph and sensors have about 20 bug fixes, tests and documentation, and the planners now agree on world coordinates. PRM queries are about twice as fast, and the range-bearing sensor's beam and sensing region can be animated.
Plots that work the same everywhere. plot and teach share env=, ax=, color=, view= and notebook=. Draw a second robot, or the same robot in another pose, in one scene with env=, or start from a flat view="xy". Plots and animations work in Jupyter, Colab and in the browser with JupyterLite.
Rearrange a robot without changing it. On an ETS, merge, swap and replace (each with a copy-returning form), joint offsets, locking a joint with fixjoint, and numerical IK for planar ETS2.
Payload capacity and self-collision. robot.payload_capacity(q, tau_m, w) gives the load each joint can hold, in the base or end-effector frame. Collision checking now covers a robot's own non-adjacent links.
Also: 72 bug fixes, a single documentation style with refreshed example notebooks and wiki, py.typed with mypy covering the whole package except two old DHFactor modules and two unmaintained backend sketches.
Changes to be aware of
Results that change because they were wrong
- URDF inertia tensors are rotated into the link frame, so dynamics of URDF robots change.
DHRobot.jacobeapplies a joint's flip, and ETS2 Jacobians keep the signs of flipped joints.- Python RNE applies prismatic offsets, and operational-space Coriolis terms are transformed consistently.
- IK: a half-turn pose error keeps its size, QP updates apply at the active joints, and the residual of a trajectory is the maximum.
- Puma560 limits for joints 2, 3 and 4 are those of RTB-MATLAB.
robot.payload(m, p)adds to the end-effector link's mass and inertia, where it used to overwrite them.- The
JTrajblock ends at rest, where it used to end moving.
Now an error, where it used to give a wrong result or an obscure failure
- Dynamics methods such as
rne,gravloadandinertiaon a model with no dynamic parameters. - A
q0ormaskof the wrong length passed to an IK solver. PyPlotstep()withdt <= 0, which used to hang a window plot.PRMPlanner.query()beforeplan():RuntimeError, notAttributeError.Robot.rne()on a standard-DH robot:ValueError, notAssertionError. Bad arguments to blocks likewise raiseValueErrororTypeError.
Deprecated, or a different shape
DHRobot.ikine_6sis deprecated. For any six-axis arm useikine_analytic.plot(browser="notebook")is deprecated. Usenotebook=True.jtrajtakes joint coordinates only. PassingSE3poses raises an error, so usectrajfor those.ParticleFilter.get_xytreturns the heading as well as x and y, as documented.- Graphical backends:
Connectoris aProtocol, so a backend no longer has to inherit from it.
Full changelog
Features
- dynamics: payload_capacity() replaces pay() and paycap() (#881) (f7d5548)
- ets: a joint has an offset, and merge() can merge a constant into a joint (#869) (4c91c01)
- ets: a trailing underscore numbers a joint name from one; document joint descriptors (#811) (68f525a)
- ets: add numerical inverse kinematics for planar ETS2 (#826) (aaf0902), closes #824
- ets: fkine and eval take no argument for a sequence without joints (#830) (155a4be)
- ets: merged() and swapped() return a modified copy, and merge() removes a transform that adds up to nothing (#868) (ee91ff9)
- ets: replace() and replaced() put a transform on another axis (#874) (67ea1a1)
- ets: support locking a joint in an ETS (#740) (38fc591)
- ets: swap() carries a transform across a constant quarter or half turn (#870) (84bd1e5)
- ik: analytic inverse kinematics for six-axis arms, with generated code in Python, C, C++ and Rust (#842) (580886e)
- ik: verbose=True prints the progress of the Python IK solvers, and why a solution is rejected (#834) (c225baf)
- mobile: animate range-bearing sensor beam and sensing region (#858) (9402635)
- mobile: planners ignore unknown keywords with a warning; plot(labels=True); distance= for metric (#786) (1a3a19f)
- plot: plot(env=) adds a robot to an earlier scene in a pose of its own, plot(ax=) draws on given axes, and color= sets the color (#873) (1daa4b3)
- plot: plot(notebook=) chooses the Swift frame in a cell or a browser window, and browser=notebook is deprecated (#866) (f68741b)
- plot: view="xy", "xz" or "yz" starts a PyPlot plot in an axis-aligned view of a plane (#879) (649b8fb)
- robot: add self-collision checks for non-adjacent links (#816) (8255224)
- typing: ship a py.typed marker so type checkers use RTB's annotations (#823) (ea8b978)
Bug Fixes
- add the payload to the end-effector link instead of overwriting it (#699) (79b169c)
- backends: PyPlot backend fixes, Connector as a Protocol, one window-title helper (#788) (dcb7982)
- blocks: DiffSteer NameError and VehiclePlot shared defaults, with types and docstrings (#775) (f59eee8)
- blocks: JTraj ends at rest, and accepts qd0 and qdf (#890) (44ebffe)
- dh: DHRobot.jacobe applies the flip of a joint (#806) (d312bc8)
- dhrobot: format prismatic joint limits in string output (#718) (71d07a7)
- docs: drop the obsolete cross-repo spatialgeometry wheel fetch (#703) (477b6e3)
- dynamics: apply prismatic offsets in Python RNE (#800) (544e574)
- dynamics: dynamics methods require dynamic parameters, and hasdynamics is kept by the setters (#846) (b7f9096)
- dynamics: preserve operational gravity overrides and output shape (#797) (b9e71a5)
- dynamics: support arbitrary joint counts in paycap (#731) (6a45f73)
- dynamics: transform operational Coriolis terms consistently (#796) (c93afaf)
- ekf: plot_error in SLAM, against time, honouring bgcolor, with correct bounds (#749) (0119d66)
- ets2: preserve joint indices and flipped Jacobian signs (#792) (8df90ac)
- ets: reject boolean joint indices in fixjoint (#836) (4512e47)
- ets: swap accepts transforms that commute, merge rejects a joint, ET2.s is a 3-vector (#832) (f7edf54)
- ik: a q0 or mask of the wrong length is an error, in the C++ and the Python solvers (#831) (f333582)
- ik: apply QP updates at active joint indices (#794) (38909d2)
- ik: IKSolution is a sequence of the rows of q, true if successful (#717) (be4ad92)
- ik: preserve arbitrary half-turn pose error magnitude (#793) (fe51972)
- ik: Robot.ikine_* accept an (N, 4, 4) array of poses (#714) (385747b)
- ik: trajectory residual is the maximum, and document trajectory behaviour (#712) (aee6fb2)
- lite: the notebooks install the wheel built with the site, and a browser check proves it (#863) (126c410)
- mobile: align grid planners and backgrounds in world coordinates (#791) (b4e05b4)
- mobile: Bug2 animation, trapped, border handling, and docstrings (#780) (44ce707)
- mobile: DistanceTransform, PRM, QuinticPoly and CurvaturePoly planners (#781) (53becb4)
- mobile: EKF map coordinates and range-bearing observation rows (#784) (4a93c88)
- mobile: EKF map ellipses use each landmark's covariance; description, state copy, sensor type (#787) (d909d7c)
- mobile: make PurePursuit usable; rst docstrings and shaped types in drivers.py (#772) (3a3a1d8)
- mobile: maps: stricter arguments, clearer names, docstrings and types (#779) (ec1e3fe)
- mobile: PlannerBase argument checks, plot without side effects, and <thing>_style arguments (#778) (84a07d2)
- mobile: PoseGraph access and errors, verbose output, style arguments, pgraph 1.0 names (#783) (7def8fa)
- mobile: preserve angular turn-rate units for Unicycle (#719) (606223f)
- mobile: reject negative occupancy grid indices (#790) (be029bd)
- mobile: remove debug output from RRT query (#751) (c7c9b58)
- mobile: resolve the workspace in one place, with a documented precedence (#776) (07090ed)
- mobile: type ParticleFilter, and fix x0, gif and mp4 output (#883) (6b85d77)
- mobile: VehicleBase control handling and plot_xyt, tests and docstrings (#774) (2ee9fa9)
- particlefilter: do not pause between steps unless animating (#748) (ea7b4d6)
- particlefilter: get_xyt returns (x, y, theta) as documented (#752) (14775a7)
- planning: retain zero-coordinate path endpoints (#798) (72169ae)
- plot: a trajectory is animated whatever %matplotlib says (#860) (b853cb8)
- plot: drive Swift through its handle, and test Swift in a notebook with a real kernel (#865) (7894328)
- plot: one implementation of the block= contract for every plot method (#820) (2881ee1)
- plot: PyPlot and PyPlot2 step() raise ValueError for a dt of zero or less (#875) (934ca7d)
- plot: Swift is shown in the cell of a notebook, and a trajectory is animated in real time (#864) (fa353d4)
- poe: construct frames for x-aligned screw axes (#799) (7334f2e)
- populate mstraj velocity and acceleration (#706) (8007e33)
- posegraph: ignore blank lines in g2o and toro files (#745) (c66d855)
- prm: honour explicit constructor distance threshold (#754) (788eaf3)
- prm: query before plan raises RuntimeError rather than AttributeError (#744) (e094f89)
- puma560: joint 2, 3 and 4 limits are those of RTB-MATLAB, as the comments say (#835) (5afb34a)
- puma: self-contained ikine_a with trajectory and failure handling; deprecate ikine_6s (#715) (1a609c3)
- robot: hasgeometry is true for planar robots whose links have geometry (#814) (4543500)
- robot: improve jacob0_dot docstring, typing overloads, and representation error handling (#737) (b83b469)
- robot: jtraj takes joint coordinates only, SE3 arguments raise (#716) (68185fc)
- robot: qlim and printing work for a robot with symbolic parameters (#856) (7666c63)
- robot: Robot.set_default_backend replaces rtbtool's monkey-patch; URDFRobot drops a dead guard (#810) (681c725)
- robot: the first line of print(robot) names the class and the model (#862) (4766ca6)
- robot: the first line of print(robot) names the class and the model, as DHRobot.Puma560 (4766ca6)
- robot: the line of sight of vision_collision_damper has the right orientation for parallel and antiparallel vectors (82974b1)
- robot: the line of sight of vision_collision_damper is oriented correctly for parallel and antiparallel vectors (#845) (82974b1)
- slam: report missing PoseGraph vertices with file context (#760) (dba2bfc)
- tests: expect forward-slash filename from spatialgeometry >= 1.4.1 (#702) (c070066)
- tools: report original Jacobian column indices (#795) (cb4b591)
- tools: the data.py demo block called a function that does not exist (#809) (27fd83a)
- trajectory: honour non-zero time origins in scalar profiles (#698) (06b8716)
- trajectory: solve the quintic in normalized time, Hermite form behind method= (#805) (97c6c0f)
- urdf: initialise name maps before transmission validation (#801) (057751f)
- urdf: report stage, element and line when a URDF/xacro fails to load (848114b)
- urdf: report stage, element and line when URDF/xacro loading fails (#701) (848114b)
- urdf: rotate inertia tensors from the inertial frame into the link frame (#707) (566cf70)
Performance Improvements
- mobile: index completed PRM roadmaps and benchmark queries (#889) (0e8d604)
- mobile: reduce RRT collision work and assemble sparse pose graphs (#817) (ff0e902)
Documentation
- add Codacy grade badge to README (0372615)
- AGENTS.md says what the Toolbox is for (#872) (a379193)
- agents: say where the array type aliases are (#757) (5c7d3d4)
- ask contributors to check for existing PRs and claim Issues first (#829) (02af061)
- desiderata: bring up to date with the code, and add status markers (#885) (31d99a9)
- ets: a section for ET and ETS, and a documentation pass: typos, cross-references, zero warnings (#833) (374720a)
- ets: add fixjoint examples and version markers (#877) (093a760)
- ik: add the autosummary template that the IK pages of #833 refer to (#838) (8839ac6)
- ik: say the same thing everywhere about when the C++ ik_XX solvers cannot be used (#871) (bf42b9f)
- ik: the QP solvers say they need qpsolvers and quadprog, and the qp extra that installs them (#841) (9b72b1a)
- landing pages for arms, mobile robots and blocks, with tables, introductions and a clearer sidebar (#844) (f0e22c0)
- lite: keep JupyterLite contents in memory so republished notebooks are never stale (#819) (4e8073d)
- mobile: correct docstrings for the estimators, sensor, drivers and animations (#750) (b6e86e8)
- notebooks: a standard generated first cell, and a shorter bootstrap cell (#850) (2b2fa83)
- notebooks: drop the deprecated path_marker argument (#815) (689ae2a)
- notebooks: drop the path_marker argument, which is deprecated (689ae2a)
- notebooks: follow the notebook plotting recipe, and fix a broken qplot call (#821) (7690e80)
- notebooks: modernise branched-robot.ipynb for the current Robot API (#852) (2d8abf1)
- notebooks: modernise ets.ipynb for the current ET and ETS API (#851) (1460de7)
- notebooks: modernise icra2021.ipynb for the current API (#854) (1ddf6dd)
- notebooks: modernise iros2020.ipynb (renamed from iros2020-workshop) for the current API (#855) (af4de2c)
- notebooks: modernise symbolic.ipynb for the current API and make it fast to run (#857) (bd9e933)
- notebooks: modernise two-link-dynamics.ipynb, including the sign convention of gravity (#853) (e778eb6)
- notebooks: review and refresh the notebooks, add an index (#867) (c72f1bc)
- notebooks: the first cell is hand-written markdown again, and cell ids are committed (#859) (742b6ed)
- one style for docstring section headings, and 1.5.0 for the next release (#882) (6497cdc)
- say which checks are required, and that Codacy is advisory (#802) (1ec699a)
- update copyright information in LICENSE file (#710) (fc969a3)