Backends

The Toolbox supports a number of backends to display a robot animation or to control a physical robot.

Available backends

By default, only the PyPlot backend is included in the Toolbox install. Swift requires the swift optional extra (pip install roboticstoolbox-python[swift]).

PyPlot (matplotlib)

This backend displays the robot as a noodle using matplotlib graphics. matplotlib is the most ubiquitous graphics library for Python and runs on all platforms.

>>> import roboticstoolbox as rtb
>>> p560 = rtb.models.DH.Puma560()
>>> qt = rtb.tools.trajectory.jtraj(p560.qz, p560.qr, 50)
>>> p560.plot(qt.q)

Options exist to:

• attach a velocity or force ellipsoid,
• display link frames and joint axes,
• save the animation to a file as an animated GIF,
• start with a flat view of a plane, view="xy", "xz" or "yz" (the view can still be rotated), also for teach,
• draw in a given color, color="red".

Planar (2D) robots and mobile robots use a sibling backend, pyplot2.

Several robots, or several poses

plot returns the scene. Pass it back as env to add another robot, or the same robot in another pose, to the same axes instead of making a new figure. Each drawing holds the pose it was given, so only the one you move moves.

>>> env = p560.plot(p560.qr, color="gray", block=False)
>>> p560.plot(p560.qn, env=env, color="red", name=False, block=False)

Or add to a scene directly and keep the handle: handle = env.add(p560, q=q), then handle.q = q2 moves only that drawing. To draw into an existing matplotlib 3D axes use ax=.

In a notebook PyPlot picks a widget or inline frames from the %matplotlib setting; see Working with Jupyter.

Swift

Swift displays in a web browser using three.js, and is the default for a Robot (a DHRobot defaults to PyPlot). It needs a model with geometry, such as those defined using URDF, and can use STL or Collada meshes. In a notebook it is shown in a frame of the cell (notebook=True), outside one in a browser window (notebook=False, or name a browser=).

>>> import roboticstoolbox as rtb
>>> p560 = rtb.models.URDF.Puma560()
>>> qt = rtb.tools.trajectory.jtraj(p560.qz, p560.qr, 50)
>>> p560.plot(qt.q)

See docs/source/intro.rst for a worked Panda example and a rendered screenshot.

Installation

pip install roboticstoolbox-python[swift], or follow the instructions on the Swift home page to install the bleeding-edge version from GitHub.

CoppeliaSim (nee VREP)

CoppeliaSim is a mature and capable cross-platform robot simulation environment with a free licence to use for education. There is currently no Connector backend for it in roboticstoolbox/backends/ — see issue #675 if you'd like to write one against the Connector API below.

Using the backend

The simplest way is using plot with a backend option as shown above. The alternative is to create a backend environment

from roboticstoolbox.backends.BACKEND import BACKEND
env = BACKEND()

# where BACKEND is PyPlot or Swift

env.launch()  # start the backend
env.add(robot)  # add a robot to the backend

for ...:
    robot.q = some value
    env.step()

Backend API

The backend supports a simple API defined in backends/Connector.py

• launch() launch the external program with an empty or specific scene as defined by args

• step(dt) requests the external program to make a time step of defined time updating the state of the environment, including all robots, as defined by the robot's actions.

• id = add(object) adds an object to the external environment. If object is a robot, it must be of an appropriate class. This adds the object to a list of which will act upon the step() method being called. This method returns the id of the object.

• remove(id) removes the specified object from the external environment.

• reset() triggers the external program to reset to the original state defined by launch

• restart() request the external program to close and relaunch to the state defined by launch

• close() requests that the external program to gracefully close

• hold() requests that the external program stays open, will prevent Python from exiting the script. Is blocking

TODO

Backend API cleanup ideas (common superclass for addable objects, promoting teach out of underscore-function status, a cross-backend getframe()) are tracked in issue #676 rather than here.