Improve Documentation at backends.rst

docs/backends.rst

@@ -10,10 +10,104 @@ One of the driving principles of **COMPAS** framework is to create an ecosystem
 and serve as an interface between different front-ends (e.g. CAD software) and
 back-ends.
 
-In the case of **COMPAS FAB**, it provides access to multiple robotic platforms
-as backends. This chapter highlights the available ones and explains how to
-obtain them and set them up.
 
+As such, **COMPAS FAB** provides a unified interface to access different robotic platforms
+as backends for motion planning.
+This chapter highlights the supported backends, their capabilities and the steps to set them up.
+The following backends are currently supported:
+
+- **ROS MoveIt!** (OMPL planner implemented by MoveIt, maintained by ROS community, requires a Linux environment, WSL or Docker)
+- **PyBullet Planner** (Planner implemented as part of compas_fab, based on the PyBullet physics simulator. Can run natively on Windows, Mac or Linux)
+- **Analytical Kinematics Planner** (Planner implemented as part of compas_fab. Limited to selected 6DOF articulated robot kinematics. Can run natively on Windows, Mac or Linux)
+
+Different planners have different capabilities (can plan different types of motions and targets)
+and limitations (types of robots kinematics).
+For regular users it is important to choose a backend that best fits their needs.
+For more advanced users, it is possible to develop new backends or extend existing ones
+(see :ref:`backend_architecture`).
+The following tables provides a comparison of the different backends.
+
+.. list-table:: Planning capabilities of different backends
+    :widths: 25 50 50 50
+    :header-rows: 1
+
+    *   - Capabilities
+        - ROS MoveIt!
+        - PyBullet Planner
+        - Analytical Inverse Kinematics Planner
+    *   - Forward Kinematics
+        - Yes
+        - Yes
+        - Yes
+    *   - Inverse Kinematics
+        - Yes (Gradient Based)
+        - Yes (Gradient Based)
+        - Yes (Analytical)
+    *   - Cartesian-Space Motion Planning (Frame Waypoints)
+        - Yes
+        - Yes
+        - Yes (No Collision Detection)
+    *   - Cartesian-Space Motion Planning (Point-Axis Waypoints)
+        - No
+        - Yes
+        - No
+    *   - Free-Space Motion Planning (Frame Target)
+        - Yes
+        - Yes
+        - No
+    *   - Free-Space Motion Planning (Point-Axis Target)
+        - No
+        - Yes
+        - No
+    *   - Free-Space Motion Planning (Configuration Target)
+        - Yes
+        - Yes
+        - No
+
+.. list-table:: Running Environment of different backends
+    :widths: 25 50 50 50
+    :header-rows: 1
+
+    *   -
+        - ROS MoveIt!
+        - PyBullet Planner
+        - Analytical Inverse Kinematics Planner
+    *   - Windows
+        - Yes (via WSL or Docker)
+        - Yes (Already installed with compas_fab)
+        - Yes (Pure Python Implementation in compas_fab)
+    *   - Linux
+        - Yes (Native install or Docker)
+        - Yes (Already installed with compas_fab)
+        - Yes (Pure Python Implementation in compas_fab)
+    *   - Mac
+        - Yes (Native install or Docker)
+        - Yes (Already installed with compas_fab)
+        - Yes (Pure Python Implementation in compas_fab)
+
+.. list-table:: Supported robot kinematics of different backends
+    :widths: 25 50 50 50
+    :header-rows: 1
+
+    *   -
+        - ROS MoveIt!
+        - PyBullet Planner
+        - Analytical Inverse Kinematics Planner
+    *   - Kinematics
+        - Supports arbitrary amount of revolute and prismatic joints.
+        - Supports arbitrary amount of revolute and prismatic joints.
+        - Limited to spherical-wrist and offset-wrist 6DOF articulated robots.
+    *   - Pre-installed Robots
+        - A selection of industrial robots from the ROS-Industrial repository are pre-installed in the Docker distribution provided by compas_fab.
+          See corresponding Dockerfile in `Ros Docker Distribution <https://github.com/gramaziokohler/ros_docker>`_
+        - Any robot with a URDF, SRDF and meshes description can be used.
+          Robots do not need to be pre-installed, they can be loaded to the backend at runtime.
+        - A selection of 6 DOF industrial robots are available as part of the compas_fab package.
+          See :ref:`analytical_kinematics` for full list.
+    *   - Installing New Robots
+        - Require modifying the ROS environment or the Docker container.
+        - Custom robots can be loaded to backend at runtime.
+        - Custom robots can be added by finding out the robot kinematics and creating subclass of :class:`~compas_fab.backends.OffsetWristKinematics` or :class:`~compas_fab.backends.SphericalWristKinematics`.
 
 Installing backends
 ===================
@@ -24,7 +118,7 @@ install, while others are very complex.
 In order to simplify working with these tools and have a consistent way
 to use and test different backends, **COMPAS FAB** provides them as
 `Docker containers`_. Docker containers are a way to bundle systems into
-isolated, standarized software units with full reproducibility. It greatly
+isolated, standardized software units with full reproducibility. It greatly
 reduces the time it takes to get a backend up and running.
 
 However, all of them can be installed *without* Docker as well. Please refer
@@ -58,13 +152,6 @@ Working with containers
 For Visual Studio Code users, we recommend installing the ``Docker`` extension.
 
 
-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/developer/backends.rst

@@ -1,4 +1,4 @@
-.. _architecture:
+.. _backend_architecture:
 
 *******************************************************************************
 Backend clients

docs/examples/06_backends_kinematics/01_ik_and_cartesian.rst

@@ -1,3 +1,5 @@
+.. _analytical_kinematics:
+
 *******************************************************************************
 Analytical kinematics
 *******************************************************************************
@@ -41,7 +43,7 @@ Inverse kinematics
 ==================
 
 The inverse kinematics function calculates the joint states required for the
-end-effector to reach a certain target pose. 
+end-effector to reach a certain target pose.
 
 
 Here is an example of using ``AnalyticalInverseKinematics``:

src/compas_fab/backends/__init__.py

@@ -100,7 +100,7 @@
 ==========
 
 For details about integrating new backends, check
-the :ref:`architecture` documentation.
+the :ref:`backend_architecture` documentation.
 
 """