Merge pull request #181 from compas-dev/pybullet

Pybullet

Author: beverlylytle

AUTHORS.rst

@@ -19,7 +19,8 @@ If you use COMPAS FAB in a project, please use the following citation:
             Ma, Z. and
             Ariza, I. and
             Pacher, M. and
-            Lytle, B.
+            Lytle, B. and
+            Huang, Y.
             },
         howpublished={https://github.com/compas-dev/compas\_fab/},
         note={Gramazio Kohler Research, ETH Z\"{u}rich},
@@ -43,3 +44,4 @@ Authors
 * Inés Ariza <[email protected]> `@inesariza <https://github.com/inesariza>`_
 * Matteo Pacher <[email protected]> `@matteo-pacher <https://github.com/matteo-pacher>`_
 * Beverly Lytle <[email protected]> `@beverlylytle <https://github.com/beverlylytle>`_
+* Yijiang Huang <[email protected]> `@yijiangh <https://github.com/yijiangh>`_

docs/backends/pybullet.rst

@@ -0,0 +1,19 @@
+.. _pybullet_backend:
+
+****************
+PyBullet
+****************
+
+.. highlight:: bash
+
+`PyBullet <https://pybullet.org/>`_ is a Python module extending Bullet, an open
+source collision detection and rigid dynamics library written in C++.  PyBullet
+was written with the intention of being a "fast and easy to use Python module for
+robotics simulation and machine learning."  It also provides bindings for rendering
+and visualization, and support for virtual reality headsets.  While PyBullet
+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>`_).

docs/examples/03_backends_ros/01_ros_examples.rst

@@ -104,7 +104,7 @@ Now open a second command prompt and start the listener:
 
     python 01_ros_hello_world_listener.py
 
-You should see the listener printing everytime it hears the other node talking.
+You should see the listener printing every time it hears the other node talking.
 
 .. note::
 

docs/examples/03_backends_ros/07_ros_create_urdf_ur5_with_measurement_tool.rst

@@ -136,7 +136,7 @@ Paste the following into the file:
 Explanation
 -----------
 
-The end-effector consists of one fixed joint (that will be attacted to the tool0
+The end-effector consists of one fixed joint (that will be attached to the tool0
 of the robot), one link with geometry (the tool geometry), one fixed joint (the
 tcp joint, defining the TCP frame) and the tcp link without geometry.
 

docs/examples/05_backends_pybullet.rst

@@ -0,0 +1,11 @@
+.. _examples_pybullet:
+
+*******************************************************************************
+Backends: PyBullet
+*******************************************************************************
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    05_backends_pybullet/*

docs/examples/05_backends_pybullet/01_pybullet_examples.rst

@@ -0,0 +1,69 @@
+.. _pybullet_examples:
+
+*******************************************************************************
+Using PyBullet
+*******************************************************************************
+
+First Step
+==========
+
+The first step is to connect to PyBullet and verify that the system is working.
+
+Copy and paste the following example into a Python script or REPL.  If, when run,
+you see the output ``Connected: True``, then everything is working properly.
+
+.. code-block:: python
+
+    from compas_fab.backends import PyBulletClient
+    with PyBulletClient(connection_type='direct') as client:
+        print('Connected:', client.is_connected)
+
+.. note::
+
+    From the PyBullet user manual:
+        The GUI connection will create a new graphical user interface (GUI) with 3D OpenGL
+        rendering, within the same process space as PyBullet. On Linux and Windows this GUI
+        runs in a separate thread, while on OSX it runs in the same thread due to operating
+        system limitations. On Mac OSX you may see a spinning wheel in the OpenGL Window,
+        until you run a 'stepSimulation' or other PyBullet command.
+
+Our first example loads the UR5 robot from a URDF and then adds, then removes, a
+floor as a collision mesh.  The calls to ``sleep`` are only necessary to prevent the
+gui from closing this example too quickly.
+
+.. literalinclude :: files/01_add_collision_mesh.py
+   :language: python
+
+.. raw:: html
+
+    <div class="card bg-light">
+    <div class="card-body">
+    <div class="card-title">Downloads</div>
+
+* :download:`Add Collision Mesh (.PY) <files/01_add_collision_mesh.py>`
+
+.. raw:: html
+
+    </div>
+    </div>
+
+Adding and removing a collision mesh attached to the end effector link of the
+robot is similar.  Again, the calls to ``sleep`` and ``step_simulation`` exist only
+to make the GUI rendering smoother.
+
+.. literalinclude :: files/02_add_attached_collision_mesh.py
+   :language: python
+
+.. raw:: html
+
+    <div class="card bg-light">
+    <div class="card-body">
+    <div class="card-title">Downloads</div>
+
+* :download:`Add Attached Collision Mesh (.PY) <files/02_add_attached_collision_mesh.py>`
+
+.. raw:: html
+
+    </div>
+    </div>
+

docs/examples/05_backends_pybullet/files/01_add_collision_mesh.py

@@ -0,0 +1,20 @@
+import time
+from compas.datastructures import Mesh
+
+import compas_fab
+from compas_fab.backends.pybullet import PyBulletClient
+from compas_fab.robots import CollisionMesh
+
+with PyBulletClient() as client:
+    urdf_filepath = compas_fab.get('universal_robot/ur_description/urdf/ur5.urdf')
+    robot = client.load_robot(urdf_filepath)
+
+    mesh = Mesh.from_stl(compas_fab.get('planning_scene/floor.stl'))
+    cm = CollisionMesh(mesh, 'floor')
+    client.add_collision_mesh(cm)
+
+    time.sleep(1)
+
+    client.remove_collision_mesh('floor')
+
+    time.sleep(1)

docs/examples/05_backends_pybullet/files/02_add_attached_collision_mesh.py

@@ -0,0 +1,25 @@
+import time
+
+import compas_fab
+from compas_fab.backends.pybullet import PyBulletClient
+from compas_fab.robots import AttachedCollisionMesh
+from compas_fab.robots import CollisionMesh
+
+from compas.datastructures import Mesh
+
+with PyBulletClient() as client:
+    urdf_filepath = compas_fab.get('universal_robot/ur_description/urdf/ur5.urdf')
+    robot = client.load_robot(urdf_filepath)
+
+    mesh = Mesh.from_stl(compas_fab.get('planning_scene/cone.stl'))
+    cm = CollisionMesh(mesh, 'tip')
+    acm = AttachedCollisionMesh(cm, 'ee_link')
+    client.add_attached_collision_mesh(acm, {'mass': 1, 'robot': robot})
+
+    time.sleep(1)
+    client.step_simulation()
+    time.sleep(1)
+
+    client.remove_attached_collision_mesh('tip')
+
+    time.sleep(1)

setup.py

@@ -13,6 +13,7 @@
     # Until COMPAS reaches 1.0, we pin major.minor and allow patch version updates
     'compas>=0.16.1,<0.17',
     'roslibpy>=1.1.0',
+    'pybullet',
     'pyserial',
 ]
 keywords_list = ['robotic fabrication', 'digital fabrication', 'architecture', 'robotics', 'ros']

src/compas_fab/backends/__init__.py

@@ -28,6 +28,16 @@
     RosFileServerLoader
     MoveItPlanner
 
+PyBullet
+--------
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    PyBulletClient
+    PyBulletPlanner
+
 Long-running tasks
 ------------------
 
@@ -52,6 +62,8 @@
 
 """
 
+import compas
+
 from .exceptions import *               # noqa: F401,F403
 from .tasks import *                    # noqa: F401,F403
 from .ros.client import *               # noqa: F401,F403
@@ -62,4 +74,8 @@
 from .vrep.helpers import *             # noqa: F401,F403
 from .vrep.planner import *             # noqa: F401,F403
 
+if not compas.is_ironpython():
+    from .pybullet.planner import *           # noqa: F401,F403
+    from .pybullet.client import *            # noqa: F401,F403
+
 __all__ = [name for name in dir() if not name.startswith('_')]