Merge pull request #368 from compas-dev/update-docs

Small updates to collision objects in ROS

Author: gonzalocasas

CHANGELOG.rst

@@ -14,6 +14,7 @@ Unreleased
 
 * Added support for attached and non-attached collision mesh visualization to the ``Robot Visualize`` GH component.
 * Added a prefix to all GH components.
+* Added ``append`` to the operations of the ``Collision Mesh`` GH component.
 
 **Changed**
 

docs/examples/03_backends_ros/05_collision_objects.rst

@@ -5,26 +5,28 @@ Planning scene and collision objects
 .. note::
 
     The following examples use the `ROS <https://www.ros.org/>`_ backend
-    and the MoveIt! planner for UR5 robots. Before running them, please
+    and the MoveIt! planner for UR5e robots. Before running them, please
     make sure you have the :ref:`ROS backend <ros_backend>` correctly
-    configured and the :ref:`UR5 Demo <ros_bundles_list>` started.
+    configured and the :ref:`UR5e Demo <ros_bundles_list>` started.
+
+There are two types of collision meshes:
+    1. Non-attached collision meshes
+    2. Attached collision meshes
 
 To plan motion paths that avoid collisions with other objects than the robot
 itself, the backend's planning scene has to be updated.
 
-This is the representation of the planning scene in RViz with the UR5.
+After the planner starts, the scene will only contain the robot:
 
-.. figure:: files/05_collision_objects_attached_without.jpg
+.. figure:: files/05_collision_objects_attached_empty.jpg
     :figclass: figure
     :class: figure-img img-fluid
 
-.. note::
-
-    If using Docker to run ROS, you can open
-    `RViz on your browser <http://localhost:8080/vnc.html?resize=scale&autoconnect=true>`_.
+1. Non-attached Collision meshes
+================================
 
-Collision meshes
-================
+Add/remove a single mesh
+------------------------
 
 The following script adds and then removes a floor to the planning scene.
 
@@ -37,6 +39,9 @@ The backend's updated planning scene while executing the above script.
     :figclass: figure
     :class: figure-img img-fluid
 
+Add/remove several meshes
+-------------------------
+
 The following script adds several boxes (bricks) to the planning scene. Here,
 we use ``append`` instead of ``add`` to have multiple collision objects
 clustered under the same identifier. Like that, we don't need to keep track of
@@ -45,26 +50,51 @@ all identifiers when we later remove them.
 .. literalinclude :: files/05_append_collision_meshes.py
    :language: python
 
-The backend's updated planning scene while executing the above script. Note the
-red robot link indicating the collision.
+The backend's updated planning scene while executing the above script.
 
 .. figure:: files/05_collision_objects_append.jpg
     :figclass: figure
     :class: figure-img img-fluid
 
 
 
-Attach tool to a robot's end-effector
-=====================================
+2. Attached collision meshes
+============================
 
-The following script defines a tool, described by a collision mesh and a frame, and
-attaches and removes it to the robot's end-effector.
+Attach end-effector
+-------------------
 
-.. literalinclude :: files/05_attach_mesh_to_ee.py
+The following script defines a tool -also called end effector- which is described by a collision mesh and a frame, and
+attaches it to the robot.
+
+.. literalinclude :: files/05_attach_ee.py
    :language: python
 
-The backend's updated planning scene while executing the above script.
+In this case, we are not adding it to the planning scene explicitely, only attaching it to the robot instance itself.
 
 .. figure:: files/05_collision_objects_attached.jpg
     :figclass: figure
     :class: figure-img img-fluid
+
+
+Grasshopper example
+===================
+
+The following Grasshopper document showcases all the options described above:
+
+.. figure:: files/05_grasshopper_collision_objects.jpg
+    :figclass: figure
+    :class: figure-img img-fluid
+
+.. raw:: html
+
+    <div class="card bg-light">
+    <div class="card-body">
+    <div class="card-title">Download</div>
+
+* :download:`Robot playground (Grasshopper) (.GHX) <files/05_grasshopper_collision_objects.ghx>`
+
+.. raw:: html
+
+    </div>
+    </div>

docs/examples/03_backends_ros/files/05_attach_ee.py

@@ -0,0 +1,18 @@
+import time
+
+from compas.datastructures import Mesh
+from compas.geometry import Frame
+
+import compas_fab
+from compas_fab.backends import RosClient
+from compas_fab.robots import Tool
+
+with RosClient() as client:
+    robot = client.load_robot()
+    assert robot.name == 'ur5_robot'
+
+    # create collision object
+    mesh = Mesh.from_stl(compas_fab.get('planning_scene/cone.stl'))
+    t1cf = Frame([0.14, 0, 0], [0, 0, 1], [0, 1, 0])
+    tool = Tool(mesh, t1cf, name='tip')
+    robot.attach_tool(tool)