8000 Add backend doco · liang324/robotics-toolbox-python@896fea5 · GitHub
[go: up one dir, main page]
Skip to content

Commit 896fea5

Browse files
petercorkepetercorke
committed
Add backend doco
rejig toctrees
1 parent 636b57d commit 896fea5

File tree

10 files changed

+400
-114
lines changed

10 files changed

+400
-114
lines changed

‎docs/source/arm.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
****************
2+
Manipulator arms
3+
****************
4+
5+
.. toctree::
6+
:maxdepth: 2
7+
8+
arm_dh
9+
arm_ets
10+
arm_urdf
11+
arm_backend
12+
arm_trajectory

‎docs/source/arm_backend.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Backends
2+
========
3+
4+
The Robotics Toolbox supports a number of backends, through a standard API, to communicate with simulators or
5+
physical robots.
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
arm_backend_pyplot
11+
arm_backend_vpython
12+
arm_backend_swift

‎docs/source/arm_backend_pyplot.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
PyPlot (matplotlib)
2+
-------------------
3+
4+
.. automodule:: roboticstoolbox.backend.PyPlot
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
:inherited-members:

‎docs/source/arm_backend_swift.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Swift
2+
-----
3+
4+
.. automodule:: roboticstoolbox.backend.Swift
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
:inherited-members:

‎docs/source/arm_backend_vpython.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
VPython
2+
-------
3+
4+
.. automodule:: roboticstoolbox.backend.VPython
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
:inherited-members:
9+

‎docs/source/arm_trajectory.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Trajectories
2+
************
3+

‎docs/source/mobile.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
*************
2+
Mobile robots
3+
*************
4+
5+
6+
Vehicle models
7+
--------------
8+
9+
.. automodule:: roboticstoolbox.robot.ETS
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:
13+
:inherited-members:
14+
:special-members:
15+
:exclude-members: count, index, sort, remove, __dict__, __weakref__, __add__, __init__, __repr__, __str__, __module__
16+
17+
Path planning
18+
-------------
19+
20+
21+
EKF
22+
---

‎roboticstoolbox/backend/PyPlot/PyPlot.py

Lines changed: 117 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,30 @@
2626

2727

2828
class PyPlot(Connector):
29+
"""
30+
Graphical backend using matplotlib
31+
32+
matplotlib is a common and highly portable graphics library for Python,
33+
but has relatively limited 3D capability.
34+
35+
Example:
36+
37+
.. code-block:: python
38+
:linenos:
39+
40+
import roboticstoolbox as rtb
41+
42+
robot = rtb.models.DH.Panda() # create a robot
43+
44+
pyplot = rtb.backend.PyPlot() # create a PyPlot backend
45+
pyplot.add(robot) # add the robot to the backend
46+
robot.q = robot.qz # set the robot configuration
47+
pyplot.step() # update the backend and graphical view
48+
49+
.. note:: PyPlot is the default backend, and ``robot.plot(q)`` effectively
50+
performs lines 7-8 above.
51+
52+
"""
2953

3054
def __init__(self):
3155

@@ -34,10 +58,12 @@ def __init__(self):
3458
self.ellipses = []
3559

3660
def launch(self, name=None, limits=None):
37-
'''
38-
env = launch() launchs a blank 3D matplotlib figure
61+
"""
62+
Launch a graphical interface
3963
40-
'''
64+
```env = launch()``` creates a blank 3D matplotlib figure and returns
65+
a reference to the backend.
66+
"""
4167

4268
super().launch()
4369

@@ -82,19 +108,26 @@ def launch(self, name=None, limits=None):
82108
# TODO still need to finish this, and get Jupyter animation working
83109

84110
def step(self, dt=50):
85-
'''
86-
state = step(args) triggers the external program to make a time step
87-
of defined time updating the state of the environment as defined by
88-
the robot's actions.
111+
"""
112+
Update the graphical scene
89113
90-
The will go through each robot in the list and make them act based on
91-
their control type (position, velocity, acceleration, or torque). Upon
92-
acting, the other three of the four control types will be updated in
93-
the internal state of the robot object. The control type is defined
94-
by the robot object, and not all robot objects support all control
95-
types.
114+
:param dt: time step in milliseconds, defaults to 50
115+
:type dt: int, optional
116+
117+
``env.step(args)`` triggers an update of the 3D scene in the matplotlib
118+
window referenced by ``env``.
96119
97-
'''
120+
.. note::
121+
122+
- Each robot in the scene is updated based on
123+
their control type (position, velocity, acceleration, or torque).
124+
- Upon acting, the other three of the four control types will be
125+
updated in the internal state of the robot object.
126+
- The control type is defined by the robot object, and not all robot
127+
objects support all control types.
128+
- Execution is blocked for the specified interval
129+
130+
"""
98131

99132
super().step()
100133

@@ -111,28 +144,36 @@ def step(self, dt=50):
111144
self._update_robots()
112145

113146
def reset(self):
114-
'''
115-
state = reset() triggers the external program to reset to the
116-
original state defined by launch
147+
"""
148+
Reset the graphical scene
117149
118-
'''
150+
``env.reset()`` triggers a reset of the 3D scene in the matplotlib
151+
window referenced by ``env``. It is restored to the original state
152+
defined by ``launch()``.
153+
"""
154+
# TODO what does this actually do for matplotlib??
119155

120156
super().reset()
121157

122158
def restart(self):
123-
'''
124-
state = restart() triggers the external program to close and relaunch
125-
to thestate defined by launch
159+
"""
160+
Restart the graphics display
161+
162+
``env.restart()`` triggers a restart of the matplotlib view referenced
163+
by ``env``. It is closed and relaunched to the original state defined by
164+
``launch()``.
126165
127-
'''
166+
"""
167+
# TODO what does this actually do for matplotlib??
128168

129169
super().restart()
130170

131171
def close(self):
132-
'''
133-
close() closes the plot
134-
135-
'''
172+
"""
173+
``env.close()`` gracefully closes the matplotlib window
174+
referenced by ``env``.
175+
"""
176+
# TODO what does this actually do for matplotlib??
136177

137178
super().close()
138179

@@ -146,12 +187,37 @@ def close(self):
146187
def add(
147188
self, ob, readonly=False, display=True,
148189
jointaxes=True, eeframe=True, shadow=True, name=True):
149-
'''
150-
id = add(robot) adds the robot to the external environment. robot must
151-
be of an appropriate class. This adds a robot object to a list of
152-
robots which will act upon the step() method being called.
153-
154-
'''
190+
"""
191+
Add a robot to the graphical scene
192+
193+
:param ob: [description]
194+
:type ob: [type]
195+
:param readonly: [description], defaults to False
196+
:type readonly: bool, optional
197+
:param display: [description], defaults to True
198+
:type display: bool, optional
199+
:param jointaxes: [description], defaults to True
200+
:type jointaxes: bool, optional
201+
:param eeframe: [description], defaults to True
202+
:type eeframe: bool, optional
203+
:param shadow: [description], defaults to True
204+
:type shadow: bool, optional
205+
:param name: [description], defaults to True
206+
:type name: bool, optional
207+
208+
``id = env.add(robot)`` adds the ``robot`` to the graphical environment.
209+
210+
.. note::
211+
212+
- ``robot`` must be of an appropriate class.
213+
- Adds the robot object to a list of robots which will be updated
214+
when the ``step()`` method is called.
215+
216+
"""
217+
# TODO please fill in the options
218+
# TODO it seems that add has different args for every backend, are
219+
# any common ones? If yes, they should be in the superclass and we
220+
# pass kwargs to that
155221

156222
super().add()
157223

@@ -170,10 +236,23 @@ def add(
170236
self._set_axes_equal()
171237

172238
def remove(self):
173-
'''
174-
id = remove(robot) removes the robot to the external environment.
175-
176-
'''
239+
"""
240+
Remove a robot to the graphical scene
241+
242+
:param id: The id of the robot to remove. Can be either the DHLink or
243+
GraphicalRobot
244+
:type id: class:`~roboticstoolbox.robot.DHRobot.DHRobot`,
245+
class:`roboticstoolbox.backend.VPython.graphics_robot.GraphicalRobot`
246+
:param fig_num: The canvas index to delete the robot from, defaults to
247+
the initial one
248+
:type fig_num: int, optional
249+
:raises ValueError: Figure number must be between 0 and total number
250+
of canvases
251+
:raises TypeError: Input must be a DHLink or GraphicalRobot
252+
253+
``env.remove(robot)`` removes the ``robot`` from the graphical environment.
254+
"""
255+
# TODO should be an id to remove?
177256

178257
super().remove()
179258

@@ -232,13 +311,13 @@ def _plot_handler(self, sig, frame):
232311
pass
233312

234313
def _set_axes_equal(self):
235-
'''
314+
"""
236315
Make axes of 3D plot have equal scale so that spheres appear as
237316
spheres, cubes as cubes, etc.. This is one possible solution to
238317
Matplotlib's ax.set_aspect('equal') and ax.axis('equal') not
239318
working for 3D.
240319
241-
'''
320+
"""
242321

243322
if self.limits is not None:
244323
return

0 commit comments

Comments
 (0)
0