Merge pull request #58 from sharronliu/master

Sharron LIU · web-flow · commit 7be8232758b3 · 2019-11-08T11:11:08.000+08:00
grasp_tutorials: added two pages
diff --git a/grasp_ros2/README.md b/grasp_ros2/README.md
@@ -0,0 +1 @@
+../grasp_tutorials/doc/grasp_planner.rst
diff --git a/grasp_tutorials/_static/images/ros2_grasp_library.png b/grasp_tutorials/_static/images/ros2_grasp_library.png
diff --git a/grasp_tutorials/doc/bringup_robot.rst b/grasp_tutorials/doc/bringup_robot.rst
@@ -0,0 +1,59 @@
+Bring up a New Robot
+====================
+
+This tutorial explains what is expected to do when bringing up this ROS2 Grasp Library on a new robot.
+
+.. _GraspPlanning: http://docs.ros.org/api/moveit_msgs/html/srv/GraspPlanning.html
+.. _GPD: https://github.com/atenpas/gpd
+.. _OpenVINO™: https://software.intel.com/en-us/openvino-toolkit
+.. _Grasp: http://docs.ros.org/api/moveit_msgs/html/msg/Grasp.html
+
+Minimum APIs to Implement
+-------------------------
+
+- `moveToTcpPose`
+
+  - Move the TCP (tool center point, usually the end effector of the robot arm, not the hand) to a pose specified with position [x, y, z] and orientation [alpha, betta, gamma] (also called [roll, pitch, yaw]). This function returns when the robot `moved` to the specified pose.
+
+- `moveToJointValues`
+
+  - Move each joint of the robot to the specified values (usually angles). This function differs from the `moveToTcpPose` since a same TCP pose may be reached with various solutions of joint values. This function is used when the application expect the joints of the robot in specific state, that is proper to performe any successive picking or place action. This function returns when the robot `moved` to the specified joint values.
+
+- `open`
+
+  - Open the gripper.
+
+- `close`
+
+  - Close the gripper.
+
+- `startLoop`
+
+  - Start a loop to read and publish the robot state. Robot states are subsribed by Rviz for visualization.
+
+Optional implementation and possible extentions
+-----------------------------------------------
+
+- Optionally you may implement the `pick` and `place` interface to customize the pick and placed pipeline, or even plug-in the collision avoidance motion planning.
+
+- Python extention is not supported. It's possible to implement the Robot Interface in python and bind to C++.
+
+
+Refer to `Robot Interface API <../api/html/index.html>`_ for more detailed definition.
+
+Example UR5 Implementation
+--------------------------
+
+Refer to the UR5 `example <https://github.com/intel/ros2_grasp_library/tree/master/grasp_utils/robot_interface/src>`_ implementatino for Robot Interface.
+
+Test Your Implementation
+------------------------
+
+It's important to test your implementation before integrating this part with other components in ROS2 Grasp Library.
+
+Refer to `UR5 tests <https://github.com/intel/ros2_grasp_library/blob/master/grasp_utils/robot_interface/test/ur_test_move_command.cpp>`_, adapt it to your robot tests.
+
+Bring up Robot Control Applications
+-----------------------------------
+
+Once finished the testing, you may start to bring up the `Draw X <draw_x.html>`_ app or the `fixed position pick and place <fixed_position_pick.html>`_ app on your new robot. These application does not require camera, instead they control the robot only.
diff --git a/grasp_tutorials/doc/getting_start.rst b/grasp_tutorials/doc/getting_start.rst
@@ -0,0 +1,51 @@
+Getting Start
+=============
+
+This tutorial introduces getting start to use this ROS2 Grasp Library.
+
+.. _GraspPlanning: http://docs.ros.org/api/moveit_msgs/html/srv/GraspPlanning.html
+.. _GPD: https://github.com/atenpas/gpd
+.. _OpenVINO™: https://software.intel.com/en-us/openvino-toolkit
+.. _Grasp: http://docs.ros.org/api/moveit_msgs/html/msg/Grasp.html
+
+ROS2 Grasp Planner and Detector
+-------------------------------
+
+In this section, you will start with an RGBD sensor connecting to a Ubuntu host machine.
+
+The grasp detection relys on OpenVINO™ toolkit. Follow this `grasp_planner <grasp_planner.html>`_ instruction to install the toolkit, then build and install the ROS2 Grasp Planner and Detector with your camera.
+
+After launch the grasp planner, from rviz you will see grasp detection results highlighted as blue markers.
+
+.. image:: ./grasp_ros2/img/ros2_grasp_library.png
+   :width: 643 px
+   :height: 435 px
+   :align: center
+
+Use Launch Options for Customization
+------------------------------------
+
+ROS2 parameters are supported to customize the Grasp Detector and Grasp Planner for your local workspace. For example, the topic name of point cloud from RGBD sensor, the camera workspace (in the frame_id of the point cloud image), the grasp approach direction and angle, the grasp boundary (in the frame_id of the robot base).
+
+Robot Interface
+---------------
+
+In this section, you will bring up your robot by implementing the Robot Interface. Currently the robot interface is defined in C++, python vesion is still working in progress.
+
+Robot Interface are the minimum APIs a robot should provide to enable this solution. Follow this `robot_interface <bringup_robot.html>`_ insturction to implement the required `move`, `open`, `close`, `startLoop` interfaces.
+
+Then make sure your implementation passed the Robot Interface tests, to garantee later integration with the example applications. Also you may try the "Robot Control Applications" (like Draw X, fixed position pick and place) to verify your implemntation working well.
+
+Hand-eye Calibration
+--------------------
+
+Now start to generate transformation between the camera and the robot. Follow this `handeye_calibration <handeye_calibration.html>`_ insturtion to finish the procedure of hand-eye calibration. The calibration procedure need to be done at the time when camera is setup. The resulting transformation will be remembered in your local environment for later publishing when launching the applications.
+
+Launch Intelligent Visual Grasp Applications
+--------------------------------------------
+
+To this step, you may start to launch the applications.
+
+`Random Picking <random_pick.html>`_ runs OpenVINO grasp detection on GPU, and sends request to ROS2 MoveIt Grasp Planner for grasp planning and detection. The most likely successful grasps are returned by the Grasp Pose Detection from CNN inference, taking 3D point cloud inputs from the camera. The picking order is not pre-defined, so called random picking.
+
+`Recognition Picking <recognize_pick.html>`_ runs OpenVINO grasp detection on GPU, and runs OpenVINO object segmentation on CPU or Movidius VPU. The masks of recognized objects are returned from the `mask_rcnn` model. The `place_publisher` publishing the name of the object to pick and the position to place, so called recognition picking.
diff --git a/grasp_tutorials/doc/grasp_planner.rst b/grasp_tutorials/doc/grasp_planner.rst
@@ -4,9 +4,19 @@ Grasp Planner
 Tutorials
 ---------
 
-- `Introduction to Intel® DLDT toolkit and Intel® OpenVINO™ toolkit <https://github.com/intel/ros2_grasp_library/tree/master/grasp_tutorials/doc/grasp_ros2/install_openvino.md>`_
+- `Install OpenVINO™ toolkit`_
 
-- `OpenVINO Grasp Library with RGBD Camera <https://github.com/intel/ros2_grasp_library/tree/master/grasp_tutorials/doc/grasp_ros2/tutorials_1_grasp_ros2_with_camera.md>`_
+.. _Install OpenVINO™ toolkit: https://github.com/intel/ros2_grasp_library/tree/master/grasp_tutorials/doc/grasp_ros2/install_openvino.md
 
-- `Grasp Library Tests <https://github.com/intel/ros2_grasp_library/tree/master/grasp_tutorials/doc/grasp_ros2/tutorials_2_grasp_ros2_test.md>`_
+- `Launch ROS2 Grasp Planner and Detector`_
+
+.. _Launch ROS2 Grasp Planner and Detector: https://github.com/intel/ros2_grasp_library/tree/master/grasp_tutorials/doc/grasp_ros2/tutorials_1_grasp_ros2_with_camera.md
+
+- `Launch tests`_
+
+.. _Launch tests: https://github.com/intel/ros2_grasp_library/tree/master/grasp_tutorials/doc/grasp_ros2/tutorials_2_grasp_ros2_test.md
+
+- `Use launch options`_
+
+.. _Use launch options: https://github.com/intel/ros2_grasp_library/tree/master/grasp_tutorials/doc/grasp_ros2/tutorials_3_grasp_ros2_launch_options.md
 
diff --git a/grasp_tutorials/doc/grasp_ros2/install_gpd.md b/grasp_tutorials/doc/grasp_ros2/install_gpd.md
@@ -16,7 +16,7 @@ sudo make install
 ```
 
 ### Install [GPD](https://github.com/sharronliu/gpd)
-1. Get the code
+1. Get the code, originally derived from [GPD](https://github.com/atenpas/gpd) tag 1.5.0
 ```bash
 git clone https://github.com/sharronliu/gpd.git
 git checkout libgpd
diff --git a/grasp_tutorials/doc/overview.rst b/grasp_tutorials/doc/overview.rst
@@ -8,17 +8,15 @@ Overview
 
 ROS2 Grasp Library consists of
 
-- A ROS2 Grasp Planner providing grasp planning service, as an extensible capability of MoveIt (moveit_msgs::srv::`GraspPlanning`_)
+.. image:: ../_static/images/ros2_grasp_library.png
+   :width: 523 px
+   :height: 311 px
+   :align: center
 
-- A ROS2 Grasp Detector interface, enabled with the specific back-end algorithm `GPD`_ with Intel® `OpenVINO™`_ technology
+- A ROS2 Grasp Planner providing grasp planning service, as an extensible capability of MoveIt (moveit_msgs::srv::`GraspPlanning`_), translating grasp detection results into MoveIt Interfaces (moveit_msgs::msg::`Grasp`_). A ROS2 Grasp Detctor abstracting interfaces for grasp detection results
 
-- Hand-eye calibration generating transformation from camera frame to a specified target frame; Grasp translation to the MoveIt Interfaces (moveit_msgs::msg::`Grasp`_)
+- A ROS2 hand-eye calibration module generating transformation from camera frame to robot frame
 
 - Robot interfaces controlling the phsical robot to move, pick, place, as well as to feedback robot states
 
-- Grasp applications demonstrating the grasp planning capabilities, and telling how to put all the above software components together for intelligent visual manipulation tasks
-
-.. image:: ../_static/images/ros2_grasp_library.png
-   :width: 523 px
-   :height: 311 px
-   :align: center
+- ROS2 example applications demonstrating how to use this ROS2 Grasp Library in advanced industrial usages for intelligent visual grasp
diff --git a/grasp_tutorials/index.rst b/grasp_tutorials/index.rst
@@ -1,20 +1,20 @@
 Welcome to ROS2 Grasp Library Tutorial
-==========================================
+======================================
 
-ROS2 Grasp Library enables state-of-the-art CNN based deep learning grasp detection algorithms on ROS2 for visual manipulation of industrial robot. This package provide ROS2 interfaces compliant with the `MoveIt <http://moveit.ros.org>`_ motion planning framework which is supported by most of the `robot models <https://moveit.ros.org/robots>`_ in ROS industrial.
+This is a ROS2 intelligent visual grasp solution for advanced industrial usages, with OpenVINO™ grasp detection and MoveIt Grasp Planning.
 
-Build This Tutorial
--------------------
+Build and test this tutorial
+----------------------------
 
 ::
 
-  cd grasp_tutorials
+  cd ros2_grasp_library/grasp_tutorials
 
-  sphinx-build . build
+  sphinx-build . build # check the outputs in the ./build/ folder
 
-  cd grasp_utils/robot_interface
+  cd ros2_grasp_library/grasp_utils/robot_interface
 
-  doxygen Doxyfile
+  doxygen Doxyfile # check the outputs in the ./build/ folder
 
 Contents:
 ---------
@@ -23,16 +23,20 @@ Contents:
 
    doc/overview
 
+   doc/getting_start
+
+   doc/grasp_planner
+
    doc/robot_interface
 
-   doc/handeye_calibration
+   doc/bringup_robot
 
-   doc/grasp_planner
+   doc/handeye_calibration
 
    doc/random_pick
 
    doc/recognize_pick
 
-   doc/template
-
    doc/grasp_api
+
+   doc/template

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../grasp_tutorials/doc/grasp_planner.rst`