Skip to content

Commit 29ee42b

Browse files
petercorkeclaude
andauthored
fix(docs): fix intro.rst syntax errors, dangling section, and stale claims (#549)
Bugs (not just staleness): - Two missing-comma syntax errors in DHRobot() link-list examples (plain :: literal blocks, never executed by Sphinx, so never caught). - The "Straight line (Cartesian) paths" runblock was fully commented out but the prose after it still referenced specific line numbers of the invisible code. Re-enabled with a working example (verified: seeded batch ikine_LM call converges for all 200 poses) and rewrote the prose to match the actual output. - Two literal blocks (closest_point example, default plot() example) weren't indented relative to their introducing paragraph, so per reST rules they rendered as plain text instead of code. - A stray duplicated sentence fragment and two accidental blank lines splitting a sentence mid-word in the opening history paragraph. Staleness (checked against the actual codebase, not assumed): - Python version claims updated 3.6 -> 3.10 (three places), matching pyproject.toml's requires-python. - PyBullet -> coal: the toolbox switched collision backends; added a Windows-wheel-availability note matching tech-debt.md's already-tracked item. - Removed the lgtm.com "automated code review" claim -- confirmed no lgtm/CodeQL references anywhere in .github/workflows/; the service doesn't exist in this repo's actual CI today. - Conclusion's "currently under development" list: mobile robotics motion models/planners/EKF/SLAM are confirmed shipped (mobile/__init__.py has 8+ planners, EKF, ParticleFilter, all wired into the public API) -- moved out of the pending list. ROS/Dynamixel backends were initially assumed shipped too (files exist with real line counts) but on closer inspection are non-functional stubs (ROS.py's methods are literally `super().step` with no parens -- not even calling the parent -- and `# pragma nocover`; Dynamixel has no Connector subclass at all) -- correctly left in the "under development" list. - "over 30 robot models" -> "over 50" (actual count: DH=24, URDF=24, ETS=7). Verified: full docs build still succeeds at the same 5-warning baseline as before these changes; full test suite 653 passed, 13 skipped, no regressions. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
1 parent cd4e997 commit 29ee42b

1 file changed

Lines changed: 52 additions & 48 deletions

File tree

docs/source/intro.rst

Lines changed: 52 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ The design goals of this version can be summarised as new functionality:
5151

5252
and improved software engineering:
5353

54-
* Use Python 3 (3.6 and greater)
54+
* Use Python 3 (3.10 and greater)
5555
* Utilize WebGL and Javascript graphics technologies
5656
* Documentation in ReStructured Text using Sphinx and delivered via GitHub pages.
5757
* Hosted on GitHub with continuous integration using GitHub actions
@@ -241,7 +241,7 @@ Robotics Toolbox
241241
Robot models
242242
^^^^^^^^^^^^
243243

244-
The Toolbox ships with over 30 robot models, most of which are purely kinematic
244+
The Toolbox ships with over 50 robot models, most of which are purely kinematic
245245
but some have inertial and frictional parameters. Kinematic models can be
246246
specified in a variety of ways: standard or modified Denavit-Hartenberg (DH,
247247
MDH) notation, as an ETS string [Corke07]_, as a rigid-body tree, or from a URDF
@@ -259,7 +259,7 @@ a list of link objects. For example, a Puma560 is simply::
259259
RevoluteDH(alpha=pi/2),
260260
RevoluteDH(a=0.4318),
261261
RevoluteDH(d=0.15005, a=0.0203, alpha=-pi/2),
262-
RevoluteDH(d=0.4318, alpha=pi/2)
262+
RevoluteDH(d=0.4318, alpha=pi/2),
263263
RevoluteDH(alpha=-pi/2),
264264
RevoluteDH()
265265
], name="Puma560")
@@ -282,7 +282,7 @@ The toolbox provides such definitions wrapped as class definitions, for example:
282282
RevoluteDH(alpha=pi/2),
283283
RevoluteDH(a=0.4318),
284284
RevoluteDH(d=0.15005, a=0.0203, alpha=-pi/2),
285-
RevoluteDH(d=0.4318, alpha=pi/2)
285+
RevoluteDH(d=0.4318, alpha=pi/2),
286286
RevoluteDH(alpha=-pi/2),
287287
RevoluteDH()
288288
], name="Puma560"
@@ -458,32 +458,30 @@ function::
458458
Straight line (Cartesian) paths can be generated in a similar way between
459459
two points specified by a pair of poses in :math:`\SE{3}`
460460

461-
.. .. runblock:: pycon
462-
.. :linenos:
463-
464-
.. >>> import numpy as np
465-
.. >>> from spatialmath import SE3
466-
.. >>> import roboticstoolbox as rtb
467-
.. >>> puma = rtb.models.DH.Puma560()
468-
.. >>> t = np.arange(0, 2, 0.010)
469-
.. >>> T0 = SE3(0.6, -0.5, 0.0)
470-
.. >>> T1 = SE3(0.4, 0.5, 0.2)
471-
.. >>> Ts = rtb.tools.trajectory.ctraj(T0, T1, len(t))
472-
.. >>> len(Ts)
473-
.. >>> sol = puma.ikine_LM(Ts) # named tuple of arrays
474-
.. >>> sol.q.shape
475-
476-
At line 9 we see that the resulting trajectory, ``Ts``, is an ``SE3`` instance with 200 values.
477-
478-
At line 11 we compute the inverse kinematics of each pose in the trajectory
479-
using a single call to the ``ikine_LM`` method.
480-
The result is a list of named tuples, which gives the IK success status for
481-
each time step.
482-
At line 12 we convert this into an array, with one row per time step, and each
483-
row is a joint coordinate.
484-
The starting
485-
joint coordinates for each inverse kinematic solution
486-
is taken as the result of the solution at the previous time step.
461+
.. runblock:: pycon
462+
:linenos:
463+
464+
>>> import numpy as np
465+
>>> from spatialmath import SE3
466+
>>> import roboticstoolbox as rtb
467+
>>> puma = rtb.models.DH.Puma560()
468+
>>> t = np.arange(0, 2, 0.010)
469+
>>> T0 = SE3(0.6, -0.5, 0.3)
470+
>>> T1 = SE3(0.4, 0.5, 0.2)
471+
>>> Ts = rtb.tools.trajectory.ctraj(T0, T1, len(t))
472+
>>> len(Ts)
473+
>>> sol = puma.ikine_LM(Ts, q0=puma.qn)
474+
>>> sol.success
475+
>>> sol.q.shape
476+
477+
At line 9 we see that the resulting trajectory, ``Ts``, is an ``SE3`` instance
478+
with 200 values.
479+
480+
At line 10 we compute the inverse kinematics of the whole trajectory in a
481+
single call to ``ikine_LM``, seeded with the joint coordinates ``puma.qn``.
482+
Line 11 confirms the solve converged for every pose in the sequence, and at
483+
line 12 the per-step joint coordinates are returned as a single array, with
484+
one row per time step.
487485

488486

489487
Symbolic manipulation
@@ -651,10 +649,17 @@ Collision checking
651649
^^^^^^^^^^^^^^^^^^
652650

653651
RTB-M had a simple, contributed but unsupported, collision checking capability.
654-
This is dramatically improved in the Python version using [PyBullet]_
655-
which supports primitive shapes such as Cylinders, Spheres and Boxes as well as
656-
mesh objects. Every robot link can have a collision shape in addition to the shape
657-
used for rendering.
652+
This is dramatically improved in the Python version using [coal]_, the actively
653+
maintained successor to FCL/hpp-fcl, which performs GJK/EPA-based distance and
654+
collision queries against primitive shapes such as Cylinders, Spheres and Boxes
655+
as well as mesh objects. Every robot link can have a collision shape in addition
656+
to the shape used for rendering.
657+
658+
.. note:: ``coal`` publishes wheels for Linux and macOS; on Windows it is
659+
installable via conda-forge (``conda install -c conda-forge coal-python``)
660+
but not via pip, so collision checking is unavailable on a plain
661+
``pip install`` on Windows.
662+
658663
We can conveniently perform collision checks between links as well as between
659664
whole robots, discrete links, and objects in the world. For example a :math:`1
660665
\times 1 \times 1` box centered at :math:`(1,0,0)` can be tested against all, or
@@ -668,11 +673,10 @@ just one link, of the robot by::
668673

669674
Additionally, we can compute the minimum Euclidean distance between whole
670675
robots, discrete links, or objects. Each distance is the length of a line
671-
segment defined by two points in the world frame
672-
676+
segment defined by two points in the world frame::
673677

674-
>>> d, p1, p2 = panda.closest_point(obstacle)
675-
>>> d, p1, p2 = panda.links[0].closest_point(obstacle)
678+
>>> d, p1, p2 = panda.closest_point(obstacle)
679+
>>> d, p1, p2 = panda.links[0].closest_point(obstacle)
676680

677681

678682
Interfaces
@@ -689,7 +693,7 @@ other robotics packages.
689693

690694
By default the Toolbox behaves like the MATLAB version with a plot method::
691695

692-
>>> puma.plot(q)
696+
>>> puma.plot(q)
693697

694698
which will plot the robot at the specified joint configurmation, or animate it if ``q`` is an :math:`m \times 6` matrix, using
695699
the default ``PyPlot`` backend which draws a "noodle robot" using the PyPlot backend.
@@ -718,10 +722,9 @@ devices. Still frames and animations can be recorded.
718722
Code engineering
719723
^^^^^^^^^^^^^^^^
720724

721-
The code is implemented in Python :math:`\ge 3.6` and all code is hosted on GitHub and
725+
The code is implemented in Python :math:`\ge 3.10` and all code is hosted on GitHub and
722726
unit-testing is performed using GitHub-actions. Test coverage is uploaded to
723-
``codecov.io`` for visualization and trending, and we use ``lgtm.com`` to perform
724-
automated code review. The code is documented with ReStructured Text format
727+
``codecov.io`` for visualization and trending. The code is documented with ReStructured Text format
725728
docstrings which provides powerful markup including cross-referencing,
726729
equations, class inheritance diagrams and figures -- all of which is converted
727730
to HTML documentation whenever a change is pushed, and this is accessible via
@@ -752,17 +755,18 @@ Conclusion
752755

753756
This article has introduced and demonstrated in tutorial form the principle
754757
features of the Robotics Toolbox for Python which runs on Mac, Windows and Linux
755-
using Python 3.6 or better. The code is free and open, and released under the
758+
using Python 3.10 or better. The code is free and open, and released under the
756759
MIT licence. It provides many of the essential tools necessary for robotic
757760
manipulator modelling, simulation and control which is essential for robotics
758761
education and research. It is familiar yet new, and we hope it will serve the
759762
community well for the next 25 years.
760763

761764
A high-performance reactive motion controller, NEO, is based on this toolbox
762-
[neo]_. Currently under development are backend interfaces for CoppeliaSim,
763-
Dynamixel servo chains, and ROS; symbolic dynamics, simplification and code
764-
generation; mobile robotics motion models, planners, EKF localization, map
765-
making and SLAM; and a minimalist block-diagram simulation tool [bdsim]_.
765+
[neo]_. The Toolbox has since grown to include mobile robotics motion models,
766+
planners, EKF localization, map making and SLAM. Currently under development
767+
are backend interfaces for CoppeliaSim, Dynamixel servo chains, and ROS, and
768+
symbolic dynamics simplification/code generation; see also [bdsim]_, a
769+
complementary minimalist block-diagram simulation tool.
766770

767771
References
768772
==========
@@ -773,7 +777,7 @@ References
773777
.. [Featherstone87] R. Featherstone, Robot Dynamics Algorithms. Kluwer Academic, 1987.
774778
.. [Corke07] P. Corke, `“A simple and systematic approach to assigning Denavit- Hartenberg parameters,” IEEE transactions on robotics, vol. 23, no. 3, pp. 590–594, 2007, DOI 10.1109/TRO.2007.896765. <https://ieeexplore.ieee.org/document/4252158>`_.
775779
.. [Haviland20] `J. Haviland and P. Corke, “A systematic approach to computing the manipulator Jacobian and Hessian using the elementary transform sequence,” arXiv preprint, 2020. <https://arxiv.org/abs/2010.08696>`_
776-
.. [PyBullet] `PyBullet <https://pybullet.org/wordpress/>`_
780+
.. [coal] `coal: Collision detection And Lightweight <https://github.com/coal-library/coal>`_
777781
.. [SMTB-P] `Spatial Math Toolbox for Python <https://github.com/petercorke/spatialmath-python>`_
778782
.. [bdsim] `Block diagram simulator for Python <https://github.com/petercorke/bdsim>`_
779783
.. [neo] `NEO: A Novel Expeditious Optimisation Algorithm for Reactive Motion Control of Manipulators <https://jhavl.github.io/neo>`_

0 commit comments

Comments
 (0)