Merge branch 'wip_process' of https://github.com/compas-dev/compas_fab into wip_process

Author: gonzalocasas

docs/backends/ros/files/02_set_robot_cell_state_with_kinematic_tools.py

@@ -40,8 +40,13 @@
     # =========
 
     # Kinematic tools can be moved with it's Configuration
-    # The gripper tool's open gripper state is at [0.025, 0.025]
-    robot_cell_state.tool_states[gripper.name].configuration.joint_values = [0.025, 0.025]
+    # It can be convenient to predefine the open and closed states of a gripper
+    opened_gripper_configuration = gripper.zero_configuration()
+    opened_gripper_configuration.joint_values = [0.025, 0.025]
+    closed_gripper_configuration = gripper.zero_configuration()
+    closed_gripper_configuration.joint_values = [0.0, 0.0]
+
+    robot_cell_state.tool_states[gripper.name].configuration = opened_gripper_configuration
 
     # Calling `set_robot_cell_state` updates the robot cell in the planner
     result = planner.set_robot_cell_state(robot_cell_state)

docs/concepts/03_tool_model/01_tool_model.rst

@@ -45,3 +45,18 @@ It's is defined relative to the TBCF and its transformation is defined in
 The TCF is one of the three target reference that can be used as to create
 :class:`compas_fab.robots.Target` for inverse kinematics calculation and motion planning.
 
+.. _tool_state:
+
+Tool State
+======================
+
+The :class:`compas_fab.robots.ToolState` class is used to represent the state of a
+tool, which includes the tool's configuration and its attachment relationship with the
+robot. The tool's configuration is intended to be changed easily by the user, for visualization
+and during planning of robot motions. For example, a gripper can be attached to the robot
+by setting the :attr:`ToolState.attached_to_group` and the :attr:`ToolState.attachment_frame` 
+attributes. A detached tool is considered to be stationary in the world coordinate frame (WCF)
+and its location is defined by the :attr:`ToolState.frame` attribute.
+
+For planning and collision detection purposes, the :attr:`ToolState.touch_links` attribute 
+is used to define the robot links that are allowed to collide with the tool.

docs/concepts/03_tool_model/02_kinematic_tool.rst

@@ -2,4 +2,24 @@
 
 *******************************************************************************
 Kinematic Tool Model
-*******************************************************************************
+*******************************************************************************
+
+Kinematic tools are defined similar to defining a RobotsModel, with a set of
+:class:`compas_robots.Link` and :class:`compas_robots.Joint` objects. The Joints
+allow the tool to move and change shape, similar to how a robotic arm
+articulates. 
+
+The shape (configuration) of the tool is represented using a
+:class:`compas_robots.Configuration`, and is defined by setting 
+:attr:`ToolState.configuration<compas_fab.robots.ToolState>`.
+It can be convenient for the user to define some known tool states, such as
+the open and closed states of a gripper, or the extended and retracted states of a
+pneumatic cylinder. These states can be defined in the user's code and can 
+be used to set the tool's configuration in the :class:`ToolState` object.
+
+The following ROS example show how to set the configuration of a kinematic tool, 
+the code for other backends are similar.
+
+.. literalinclude:: ../../backends/ros/files/02_set_robot_cell_state_with_kinematic_tools.py
+   :language: python
+