Create 'Representation and Evaluation of Constraints' tutorial (#501)

* Create 'Representation and Evaluation of Constraints' tutorial

* Integrate with new Approx Constraint Manifold tutorial

* Update doc/planning_with_approximated_constraint_manifolds/planning_with_approximated_constraint_manifolds_tutorial.rst

Co-authored-by: Mark Moll <[email protected]>

* Update doc/planning_with_approximated_constraint_manifolds/planning_with_approximated_constraint_manifolds_tutorial.rst

Co-authored-by: Felix von Drigalski <[email protected]>

* Apply suggestions from code review

Co-authored-by: Felix von Drigalski <[email protected]>

Co-authored-by: Mark Moll <[email protected]>
Co-authored-by: Felix von Drigalski <[email protected]>

Author: 3 people

doc/planning_constraints/fingertip_collision.png

@@ -0,0 +1,26 @@
+Representation and Evaluation of Constraints
+============================================
+
+Constraints are an integral component of MoveIt and OMPL. They are used both to constrain robot motion as well as to define planning goals. There following set of constraints are defined in the :code:`kinematic_constraints` namespace:
+
+- kinematic_constraints::JointConstraint
+- kinematic_constraints::OrientationConstraint
+- kinematic_constraints::PositionConstraint
+- kinematic_constraints::VisibilityConstraint
+
+All of these constraints inherit from the :code:`kinematic_constraints::KinematicConstraint` base class and thus more constraint types can be added by the user by providing their own derived classes. The main operation each constraint implements is the :code:`KinematicConstraint::decide()` function, which decides whether a constraint is satisfied, and optionally returns a distance (an error) when a constraint is not satisfied.
+
+Often multiple constraints need to be imposed on a particular motion plan or for a particular goal. The class :code:`kinematic_constraints::KinematicConstraintSet` facilitates operating with sets of constraints.
+
+A related functionality to representing and evaluating constraints is :code:`constraint_sampling` "generating samples" that satisfy those constraints.
+
+
+.. figure:: fingertip_collision.png
+   :width: 400px
+
+   An example of a Visibility Constraint, whereby the motion of the arm is planned to avoid obscuring the workpiece from the cameras.
+
+See Also
+--------
+- `How to plan with path constraints in general <../move_group_interface/move_group_interface_tutorial.html#planning-with-path-constraints>`_.
+- `Planning with Approximated Constraint Manifolds <../planning_with_approximated_constraint_manifolds/planning_with_approximated_constraint_manifolds_tutorial>`_.

doc/planning_constraints/planning_constraints.rst

@@ -3,10 +3,9 @@ Planning with Approximated Constraint Manifolds
 
 OMPL supports custom constraints to enable planning trajectories that follow a desired behavior.
 Constraints can be defined in joint space and Cartesian space where the latter is either orientation or position based.
-While planning a trajectory each joint state needs to follow all of the set constraints, which is performed by rejection sampling by default.
-This however might lead to very long planning times, especially when the constraints are very restrictive and the rejection rate is correspondingly high.
+While planning a trajectory, each joint state needs to follow all of the set constraints, which is performed by rejection sampling by default. For more information see `Representation and Evaluation of Constraints <../planning_constraints/planning_constraints>`_.
 
-`Sucan et al <http://ioan.sucan.ro/files/pubs/constraints_iros2012.pdf>`_ present an approach where they compute an approximation of the constraint manifold beforehand and perform trajectory planning in that.
+Rejection sampling for each joint state might lead to very long planning times, especially when the constraints are very restrictive and the rejection rate is correspondingly high. `Sucan et al <http://ioan.sucan.ro/files/pubs/constraints_iros2012.pdf>`_ present an approach where they compute an approximation of the constraint manifold beforehand and perform trajectory planning in that.
 The OMPL plugin contains the functionality to do that for a given set of constraints and save it in a database.
 In later instances the database can be loaded to use for constrained planning with any OMPL planner which strongly reduces planning time.
 
@@ -23,6 +22,7 @@ Defining constraints
 ^^^^^^^^^^^^^^^^^^^^
 
 The ``generate_state_database`` executable reads constraints from ROS parameters on ``/constraints``, in a more compact format that a complete ROS message.
+
 You can define these in ``rosparam`` to be loaded together in a file, eg. ``X_moveit_config/config/constraints.yaml``::
 
  path_constraint:
@@ -61,11 +61,12 @@ For example::
 PositionConstraint
 """"""""""""""""""
 
-A ``PositionConstraint`` constraints the Cartesian positions allowed for a (position relative to a) link.
+A ``PositionConstraint`` constrains the Cartesian positions allowed for a (position relative to a) link.
+
 ``target_offset`` is that relative position w.r.t. a link, e.g., the tip of the end-effector relative to its mounting point or other origin definition.
 This region (boxes only in this compact definition) is compactly defined by specifying the upper and lower bounds along each axis.
 
-For example::
+For example (in YAML format)::
 
  - type: position
    frame_id: base_link

doc/planning_with_approximated_constraint_manifolds/planning_with_approximated_constraint_manifolds_tutorial.rst

@@ -75,6 +75,7 @@ Configuration
 
    doc/kinematics_configuration/kinematics_configuration_tutorial
    doc/custom_constraint_samplers/custom_constraint_samplers_tutorial
+   doc/planning_constraints/planning_constraints.rst
    doc/ompl_interface/ompl_interface_tutorial
    doc/chomp_planner/chomp_planner_tutorial
    doc/stomp_planner/stomp_planner_tutorial