From 889d4a9ae5b57b85b0619e1165fd686b46ea3524 Mon Sep 17 00:00:00 2001 From: Victor LEUNG Date: Fri, 7 Jun 2024 02:56:02 +0800 Subject: [PATCH] More information in backends.rst --- docs/backends.rst | 109 ++++++++++++++++-- docs/developer/backends.rst | 2 +- .../01_ik_and_cartesian.rst | 4 +- src/compas_fab/backends/__init__.py | 2 +- 4 files changed, 103 insertions(+), 14 deletions(-) diff --git a/docs/backends.rst b/docs/backends.rst index ce6c34929..a4e4d1ed5 100644 --- a/docs/backends.rst +++ b/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 `_ + - 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 ` and the -:ref:`contributors_guide`. - Next steps ========== diff --git a/docs/developer/backends.rst b/docs/developer/backends.rst index 991bd40fd..db87c888a 100644 --- a/docs/developer/backends.rst +++ b/docs/developer/backends.rst @@ -1,4 +1,4 @@ -.. _architecture: +.. _backend_architecture: ******************************************************************************* Backend clients diff --git a/docs/examples/06_backends_kinematics/01_ik_and_cartesian.rst b/docs/examples/06_backends_kinematics/01_ik_and_cartesian.rst index 718c5756c..c9b2f2240 100644 --- a/docs/examples/06_backends_kinematics/01_ik_and_cartesian.rst +++ b/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``: diff --git a/src/compas_fab/backends/__init__.py b/src/compas_fab/backends/__init__.py index a635e6a54..dd18bc3a1 100644 --- a/src/compas_fab/backends/__init__.py +++ b/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. """