Merge pull request #195 from compas-dev/pybullet_fk_unify_with_ros

Unify backend feature implementations of FK/IK between Pybullet/ROS

Author: gonzalocasas

CHANGELOG.rst

@@ -13,25 +13,32 @@ Unreleased
 
 **Added**
 
+* **PyBullet integration**: added support for PyBullet client and forward/inverse kinematic solver
 * Added ``ClientInterface``, ``PlannerInterface`` and various backend feature interfaces
 * Added implementations of these interfaces for ROS and V-REP
-* Added client for PyBullet with forward and inverse kinematics
+* Added ``attributes`` dictionary to ``Robot`` class 
 
 **Changed**
 
 * Updated to ``COMPAS 0.16.1``
 * Renamed ``compas_fab.robots.Robot.to_local_coords`` to ``compas_fab.robots.Robot.to_local_coordinates``
 * Renamed ``compas_fab.robots.Robot.to_world_coords`` to ``compas_fab.robots.Robot.to_world_coordinates``
 * Backend clients have been restructured according to the new interfaces
+* Parameter ``backend`` of forward kinematics has been renamed to ``solver``
 * The signatures of all kinematics, motion planning and planning scene management methods have been homogenized across backend clients and within ``Robot``
 * All examples have been updated to reflect these changes
 
+
 **Fixed**
 
 * Attached collision meshes are included in inverse kinematics calculations in ROS
 
 **Deprecated**
 
+* The methods ``forward_kinematics``, ``inverse_kinematics``, ``plan_cartesian_motion`` and ``plan_motion``
+  of ``Robot`` class have been refactored, but a backwards-compatible deprecated version with the old
+  signatures still exists suffixed by ``_deprecated``, e.g. ``forward_kinematics_deprecated``.
+
 **Removed**
 
 0.11.0

CONTRIBUTING.rst

@@ -1,3 +1,5 @@
+.. _contributors_guide:
+
 Contributor's Guide
 ===================
 
@@ -93,3 +95,11 @@ A Note on Architecture for Backend Clients
 To maintain consistency from one backend client to another and to promote modularity,
 we make use of several interfaces.  Please reference :ref:`Note on Architecture <architecture>`
 for more details on how to add or amend a backend client.
+
+Design documents
+----------------
+
+.. toctree::
+    :maxdepth: 1
+
+    architecture

README.rst

@@ -36,7 +36,7 @@ COMPAS FAB: Robotic Fabrication for COMPAS
 planning and execution of robotic fabrication processes. It provides interfaces
 to existing software libraries and tools available in the field of robotics
 (e.g. OMPL, ROS) and makes them accessible from within the parametric design
-environment. The package builds upon `COMPAS <https://compas-dev.github.io/>`_,
+environment. The package builds upon `COMPAS <https://compas.dev/>`_,
 an open-source Python-based framework for collaboration and research in
 architecture, engineering and digital fabrication.
 
@@ -48,7 +48,7 @@ Main features
 * Planning tools: kinematic solvers, path planning, etc.
 * Execution tools: feedback loops, robot control, etc.
 
-**COMPAS FAB** runs on Python 2.x, 3.x and IronPython 2.7.
+**COMPAS FAB** runs on Python 3.x and IronPython 2.7.
 
 
 Getting Started
@@ -87,8 +87,8 @@ First Steps
 * `Documentation <https://gramaziokohler.github.io/compas_fab/>`_
 * `COMPAS FAB Examples <https://gramaziokohler.github.io/compas_fab/latest/examples.html>`_
 * `COMPAS FAB API Reference <https://gramaziokohler.github.io/compas_fab/latest/reference.html>`_
-* `COMPAS Examples <https://compas-dev.github.io/main/examples.html>`_
-* `COMPAS API Reference <https://compas-dev.github.io/main/api.html>`_
+* `COMPAS Tutorials <https://compas.dev/compas/tutorial.html>`_
+* `COMPAS API Reference <https://compas.dev/compas/api.html>`_
 
 
 Questions and feedback

docs/architecture.rst

@@ -1,7 +1,7 @@
 .. _architecture:
 
 *******************************************************************************
-A Note on Backend Client Architecture
+Backend Client Architecture
 *******************************************************************************
 
 To maintain consistency from one backend client to another and to promote
@@ -30,7 +30,8 @@ method.  For example:
     from compas_fab.backends.interfaces import InverseKinematics
 
     class ExampleInverseKinematics(InverseKinematics):
-        def inverse_kinematics(self, frame_WCF,
+        def inverse_kinematics(self, robot,
+                               frame_WCF,
                                start_configuration=None,
                                group=None,
                                options=None):
@@ -43,9 +44,9 @@ can be instantiated and called in the following manner:
 
     calculate_example_ik = ExampleInverseKinematics()
     frame = Frame([0, 0, 0], [1, 0, 0], [0, 1, 0])
-    ik_result = calculate_example_ik(frame)
+    ik_result = calculate_example_ik(robot, frame)
     # or equivalently:
-    ik_result = calculate_example_ik.inverse_kinematics(frame)
+    ik_result = calculate_example_ik.inverse_kinematics(robot, frame)
 
 
 These backend feature interfaces exist in part to enforce a common
@@ -78,6 +79,6 @@ Interfaces
 ==========
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
     interfaces

docs/backends.rst

@@ -63,6 +63,13 @@ running containers:
 * `Kitematic for Windows`_
 * `Kitematic for Mac`_
 
+Developing new backends
+=======================
+
+If you are interested in developing/integrating backends to the framework, check
+the :ref:`backend architecture document <architecture>` and the
+:ref:`contributors_guide`.
+
 Next steps
 ==========
 

docs/backends/pybullet.rst

@@ -15,5 +15,13 @@ is based on a client-server architecture, there is no need to spin up any Docker
 containers to run the server.  This, along with its speed, may make PyBullet a
 preferable backend for COMPAS_FAB.  However, it, alone, does not provide motion
 planning functionality.  PyBullet is also not compatible with IronPython. Hence to use
-it with Rhinoceros and Grasshopper it must be invoked through :ref:``compas.rpc``
-(see `COMPAS RPC <https://compas-dev.github.io/main/api/compas.rpc.html>`_).
+it with Rhinoceros and Grasshopper it must be invoked through the 
+:mod:`compas.rpc` module.
+
+Next Steps
+==========
+
+* :ref:`Tutorial: COMPAS Robots <compas:robots>`
+* :ref:`Examples: Description models <examples_description_models>`
+* :ref:`Examples: PyBullet Backend <examples_pybullet>`
+* :ref:`COMPAS FAB API Reference <reference>`

docs/backends/ros.rst

@@ -265,6 +265,7 @@ Check :ref:`the following page <backends_gui>` for more details.
 Next Steps
 ==========
 
+* :ref:`Tutorial: COMPAS Robots <compas:robots>`
 * :ref:`Examples: Description models <examples_description_models>`
 * :ref:`Examples: ROS Backend <examples_ros>`
 * :ref:`COMPAS FAB API Reference <reference>`

docs/backends/vrep.rst

@@ -37,5 +37,6 @@ container with the following commands on the command prompt::
 Next Steps
 ==========
 
+* :ref:`Tutorial: COMPAS Robots <compas:robots>`
 * :ref:`Examples: V-REP Backend <examples_vrep>`
 * :ref:`COMPAS FAB API Reference <reference>`

docs/backends_gui.rst docs/backends/web_x11_gui.rstdocs/backends_gui.rst renamed to docs/backends/web_x11_gui.rst

@@ -1,7 +1,7 @@
 .. _backends_gui:
 
 ********************************************************************************
-Backends with graphical user interface
+Access backend GUI
 ********************************************************************************
 
 .. highlight:: bash
@@ -32,6 +32,15 @@ This feature is possible thanks to `NoVNC <https://novnc.com/>`_.
 Visualization forwarding display
 ================================
 
+.. note::
+
+    🐉 HERE BE DRAGONS!
+
+    Be aware that the following can be time-consuming and frustrating to configure.
+    We recommend using the web browser visualization in the general case, and only
+    use X11 forwarding if you know what you are getting yourself into.
+
+
 This option allows to forward a display directly to your operating system. It is
 especially useful when used in combination with WSL.
 
@@ -56,15 +65,3 @@ replacing ``YOUR_IP_ADDRESS`` with your current IP:
 ::
 
     export DISPLAY=YOUR_IP_ADDRESS:0.0
-
-Next steps
-==========
-
-Check documentation for your backend of choice:
-
-.. toctree::
-    :maxdepth: 2
-    :titlesonly:
-    :glob:
-
-    backends/*

docs/conf.py

@@ -42,8 +42,8 @@
 
 # intersphinx options
 intersphinx_mapping = {'python': ('https://docs.python.org/', None),
-                       'compas': ('http://compas-dev.github.io/main/', None),
-                       'roslibpy': ('http://roslibpy.readthedocs.org/en/latest/', None)}
+                       'compas': ('https://compas.dev/compas/', None),
+                       'roslibpy': ('https://roslibpy.readthedocs.io/en/latest/', None)}
 
 # autodoc options
 autodoc_default_options = {