Merge pull request #145 from tetov/robots_planning_scene_docs

robots/planning_scene docs

Author: beverlylytle

src/compas_fab/robots/planning_scene.py

@@ -15,18 +15,35 @@
 class CollisionMesh(object):
     """Represents a collision mesh.
 
+    Parameters
+    ----------
+    mesh : :class:`compas.datastructures.Mesh`
+        The collision mesh. Ideally it is as coarse as possible.
+    id : :obj:`str`
+        The id of the mesh, used to identify it for later operations
+        (:meth:`~PlanningScene.add_collision_mesh`,
+        :meth:`~PlanningScene.remove_collision_mesh`,
+        :meth:`~PlanningScene.append_collision_mesh` etc.)
+    frame : :class:`compas.geometry.Frame`, optional
+        The frame of the mesh. Defaults to :meth:`~compas.geometry.Frame.worldXY().
+    root_name : :obj:`str`
+        The name of the root link the collision mesh will be placed in. Defaults
+        to `'world'`.
+
     Attributes
     ----------
     mesh : :class:`compas.datastructures.Mesh`
         The collision mesh. Ideally it is as coarse as possible.
-    id : str
-        The id of the mesh, used to identify it for later operations (remove,
-        append, etc.)
+    id : :obj:`str`
+        The id of the mesh, used to identify it for later operations
+        (:meth:`~PlanningScene.add_collision_mesh`,
+        :meth:`~PlanningScene.remove_collision_mesh`,
+        :meth:`~PlanningScene.append_collision_mesh` etc.)
     frame : :class:`compas.geometry.Frame`, optional
-        The frame of the mesh. Defaults to the world XY frame.
-    root_name : str
-        The name of the root link the collision mesh with be placed in. Defaults
-        to 'world'.
+        The frame of the mesh. Defaults to :meth:`~compas.geometry.Frame.worldXY().
+    root_name : :obj:`str`
+        The name of the root link the collision mesh will be placed in. Defaults
+        to `'world'`.
 
     Examples
     --------
@@ -55,19 +72,33 @@ def scale(self, scale_factor):
 
 
 class AttachedCollisionMesh(object):
-    """Represents a collision mesh that is attached to a robot's link.
+    """Represents a collision mesh that is attached to a :class:`Robot`'s :class:`~compas.robots.Link`.
+
+    Parameters
+    ----------
+    collision_mesh : :class:`compas_fab.robots.CollisionMesh`
+        The collision mesh to be attached to the robot model.
+    link_name : :obj:`str`
+        The name of the :class:`~compas.robots.Link` the collision mesh will be
+        attached to.
+    touch_links : :obj:`list` of :obj:`str`, optional
+        The list of link names the collision mesh is allowed to touch. Defaults
+        to the link it is attached to.
+    weight : :obj:`float`, optional
+        The weight of the attached object in kg. Defaults to ``1.0``.
 
     Attributes
     ----------
     collision_mesh : :class:`compas_fab.robots.CollisionMesh`
         The collision mesh we want to attach.
-    link_name : str
-        The name of the link the collision mesh will be attached to.
-    touch_links : list of str
+    link_name : :obj:`str`
+        The name of the :class:`~compas.robots.Link` the collision mesh will be
+        attached to.
+    touch_links : :obj:`list` of :obj:`str`
         The list of link names the collision mesh is allowed to touch. Defaults
-        to the link_name it is attached to.
-    weight : float
-        The weight of the attached object. Defaults to 1.
+        to the link it is attached to.
+    weight : :obj:`float`
+        The weight of the attached object in kg.
 
     Examples
     --------
@@ -89,45 +120,56 @@ def __init__(self, collision_mesh, link_name, touch_links=None, weight=1.):
 class PlanningScene(object):
     """Represents the planning scene.
 
-    Attributes
+    Parameters
     ----------
-    robot : :class:`compas_fab.robots.Robot`
+    robot : :class:`Robot`
         A reference to the robot in the planning scene.
 
-    Examples
-    --------
+    Attributes
+    ----------
+    robot : :class:`Robot`
+        A reference to the robot in the planning scene.
+    client
+        A reference to the robot's backend client.
     """
 
     def __init__(self, robot):
         self.robot = robot
 
     @property
     def client(self):
-        """The backend client."""
+        """:class:`compas_fab.backend.RosClient` or :class:`compas_fab.backend.VrepClient` : The backend client."""
         return self.robot.client
 
     def ensure_client(self):
+        """Ensure that the planning scene's robot has a defined client.
+
+        Raises
+        ------
+        :exc:`Exception`
+            If no client is set for planning scene's robot.
+        """
         if not self.client:
             raise Exception(
                 'This method is only callable once a client is assigned')
 
     def add_collision_mesh(self, collision_mesh, scale=False):
-        """Adds a collision mesh to the planning scene.
+        """Add a collision mesh to the planning scene.
 
-        If the object with the same name previously existed, it is replaced.
+        If there is already a :class:`CollisionMesh` in the
+        :class:`PlanningScene` with the same `id` it will be replaced.
 
         Parameters
         ----------
-        collision_mesh : :class:`compas_fab.robots.CollisionMesh`
+        collision_mesh : :class:`CollisionMesh`
             The collision mesh we want to add.
-        scale : bool, optional
-            If `True`, the mesh will be scaled according to the robot's scale
+        scale : :obj:`bool`, optional
+            If ``True``, the mesh will be scaled according to the robot's scale
             factor.
 
         Returns
         -------
-        None
-
+        ``None``
 
         Examples
         --------
@@ -147,16 +189,16 @@ def add_collision_mesh(self, collision_mesh, scale=False):
         self.client.add_collision_mesh(collision_mesh)
 
     def remove_collision_mesh(self, id):
-        """Removes a collision object from the planning scene.
+        """Remove a collision object from the planning scene.
 
         Parameters
         ----------
-        id : str
-            The identifier of the collision object.
+        id : :obj:`str`
+            The `id` of the :class:`CollisionMesh` instance to remove.
 
         Returns
         -------
-        None
+        ``None``
 
         Examples
         --------
@@ -167,21 +209,28 @@ def remove_collision_mesh(self, id):
         self.robot.client.remove_collision_mesh(id)
 
     def append_collision_mesh(self, collision_mesh, scale=False):
-        """Appends a collision mesh that already exists in the planning scene.
+        """Append a collision mesh to the planning scene.
+
+        Appends a :class:`CollisionMesh` to the :class:`PlanningScene` using
+        `id` as an identifier of a group or cluster of collision meshes. If the group
+        does not exist, it will be created implicitly; if it does exist, the meshes will be
+        appended to it instead.
 
-        If the does not exist, it is added.
+        Grouping meshes under a common identifier allows to remove them all
+        in one operation, using the :meth:`~PlanningScene.remove_collision_mesh` with
+        the group identifier.
 
         Parameters
         ----------
-        collision_mesh : :class:`compas_fab.robots.CollisionMesh`
-            The collision mesh we want to append.
-        scale : bool, optional
-            If `True`, the mesh will be scaled according to the robot's scale
+        collision_mesh : :class:`CollisionMesh`
+            The collision mesh we want to append to the :class:`PlanningScene`.
+        scale : :obj:`bool`, optional
+            If ``True``, the mesh will be scaled according to the robot's scale
             factor.
 
         Returns
         -------
-        None
+        ``None``
 
         Examples
         --------
@@ -201,18 +250,20 @@ def append_collision_mesh(self, collision_mesh, scale=False):
         self.robot.client.append_collision_mesh(collision_mesh)
 
     def add_attached_collision_mesh(self, attached_collision_mesh, scale=False):
-        """Adds an attached collision object to the planning scene.
+        """Add an attached collision object to the planning scene.
 
         Parameters
         ----------
-        attached_collision_mesh : :class:`compas_fab.robots.AttachedCollisionMesh`
-        scale : bool, optional
-            If `True`, the mesh will be scaled according to the robot's scale
-            factor.
+        attached_collision_mesh : :class:`AttachedCollisionMesh`
+            The :class:`AttachedCollisionMesh` (a :class:`CollisionMesh`
+            attached to a :class:`Robot`'s :class:`~compas.robots.Link`) that
+            we want to add to the :class:`PlanningScene`.
+        scale : :obj:`bool`, optional
+            If ``True``, the mesh will be scaled using the robot's scale factor.
 
         Returns
         -------
-        None
+        ``None``
 
         Examples
         --------
@@ -233,16 +284,18 @@ def add_attached_collision_mesh(self, attached_collision_mesh, scale=False):
         self.client.add_attached_collision_mesh(attached_collision_mesh)
 
     def remove_attached_collision_mesh(self, id):
-        """Removes an attached collision object from the planning scene.
+        """Remove an attached collision object from the planning scene.
 
         Parameters
         ----------
-        id : str
-            The identifier of the object.
+        id : :obj:`str`
+            The `id` of the :class:`CollisionMesh` in the
+            :class:`AttachedCollisionMesh` to remove from the
+            :class:`PlanningScene`.
 
         Returns
         -------
-        None
+        ``None``
 
         Examples
         --------
@@ -257,18 +310,18 @@ def attach_collision_mesh_to_robot_end_effector(self, collision_mesh, scale=Fals
 
         Parameters
         ----------
-        collision_mesh: :class:`compas_fab.robots.CollisionMesh`
-            The collision mesh.
-        scale : bool, optional
-            If `True`, the mesh will be scaled according to the robot's scale
+        collision_mesh: :class:`CollisionMesh`
+            The collision mesh to attach to robot's end effector.
+        scale : :obj:`bool`, optional
+            If ``True``, the mesh will be scaled using the robot's scale
             factor.
-        group : str
-            The planning group to which we want to attach the mesh to. Defaults
-            to the robot's main planning group.
+        group : :obj:`str`
+            The planning group with the end effector we want to attach the mesh
+            to. Defaults to the robot's main planning group.
 
         Returns
         -------
-        None
+        ``None``
 
         Examples
         --------
@@ -303,15 +356,13 @@ def attach_collision_mesh_to_robot_end_effector(self, collision_mesh, scale=Fals
         self.add_attached_collision_mesh(acm)
 
     def add_attached_tool(self):
-        """Adds the robot's attached tool to the planning scene if set.
-        """
+        """Add the robot's attached tool to the planning scene if tool is set."""
         self.ensure_client()
         if self.robot.attached_tool:
             self.add_attached_collision_mesh(self.robot.attached_tool.attached_collision_mesh)
 
     def remove_attached_tool(self):
-        """Removes the robot's attached tool from the planning scene.
-        """
+        """Remove the robot's attached tool from the planning scene."""
         self.ensure_client()
         if self.robot.attached_tool:
             self.remove_attached_collision_mesh(self.robot.attached_tool.name)