Improved tutorials

conf/gettingstarted.ork

@@ -0,0 +1,44 @@
+source2:
+  type: RosKinect
+  module: 'object_recognition_ros.io'
+  parameters:
+    rgb_frame_id: camera_rgb_optical_frame
+    depth_image_topic: /camera/depth_registered/image_raw
+    depth_camera_info: /camera/depth_registered/camera_info
+    rgb_image_topic: /camera/rgb/image_rect_color
+    rgb_camera_info: /camera/rgb/camera_info
+
+sink1:
+  type: TablePublisher
+  module: 'object_recognition_tabletop'
+  inputs: [source2]
+
+sink2:
+  type: Publisher
+  module: 'object_recognition_ros.io'
+  inputs: [source2]
+
+
+pipeline1:
+  type: TabletopTableDetector
+  module: 'object_recognition_tabletop'
+  inputs: [source2]
+  outputs: [sink1]
+  parameters:
+    table_detector:
+        min_table_size: 1000
+        plane_threshold: 0.01
+
+pipeline2:
+  type: TabletopObjectDetector
+  module: 'object_recognition_tabletop'
+  inputs: [source2, pipeline1]
+  outputs: [sink2]
+  parameters:
+    object_ids: 'all'
+    tabletop_object_ids: 'REDUCED_MODEL_SET'
+    threshold: 0.65
+    db:
+      type: CouchDB
+      root: http://localhost:5984
+      collection: object_recognition

doc/source/conf.py

@@ -32,7 +32,7 @@
               'sphinx.ext.doctest',
               'sphinx.ext.graphviz',
               'sphinx.ext.intersphinx',
-              'sphinx.ext.pngmath',
+              'sphinx.ext.imgmath',
               'sphinx.ext.todo',
               'sphinx.ext.viewcode']
 
@@ -113,7 +113,7 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'ecto_theme'
+html_theme = 'sphinxdoc'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -223,9 +223,9 @@
 
 """
 
-intersphinx_mapping = {'orkcapture': ('http://wg-perception.github.com/capture', None),
-                       'orkcore': ('http://wg-perception.github.com/object_recognition_core', None),
-                       'orklinemod': ('http://wg-perception.github.com/linemod', None),
-                       'orkrenderer': ('http://wg-perception.github.com/ork_renderer', None),
-                       'orktabletop': ('http://wg-perception.github.com/tabletop', None),
+intersphinx_mapping = {'orkcapture': ('http://wg-perception.github.io/capture', None),
+                       'orkcore': ('http://wg-perception.github.io/object_recognition_core', None),
+                       'orklinemod': ('http://wg-perception.github.io/linemod', None),
+                       'orkrenderer': ('http://wg-perception.github.io/ork_renderer', None),
+                       'orktabletop': ('http://wg-perception.github.io/tabletop', None),
 }

doc/source/index.rst

@@ -1,15 +1,19 @@
 .. _object_recognition_tutorials:
 
-Object Recognition Tutorials
-############################
+Object Recognition Kitchen (ORK) Tutorials
+##########################################
 
-Object recognition is a difficult problem in itself. Implementations of it are even more difficult because of the different layers of complexity: data capture, training, detection. Add several layers of complexity for each of those, as well as some robotics integration problems and you see where it's going.
+Welcome to the ORK Tutorials! These tutorials are designed to show how to use
+specific tools and detection pipelines that are part of
+:ref:`ORK <orkcore:index>`.
 
-The following tutorials do not go over the object recognition steps in order of execution but complexity. You probably need the last tutorials fo your real world applications but the first ones will actually make sure that your setup is fine.
+The following tutorials do not go over the object recognition steps in order of
+execution but complexity. You probably need the last tutorials for your real
+world applications, but the first tutorials are simpler, and will make sure
+that your system is set up correctly.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ./tutorial01/tutorial.rst
-   ./tutorial02/tutorial.rst
    ./tutorial03/tutorial.rst

doc/source/tutorial01/tutorial.rst

@@ -1,95 +1,119 @@
 .. _tutorial01:
 
-Object Recognition DB
-#####################
+Database Management
+###################
 
-In the Object Recognition Kitchen, everything is stored in a database: objects, models, training data. We'll walk you through the basics of the DB in this tutorial, you will:
+In the Object Recognition Kitchen, everything is stored in a database (DB):
+objects, models, training data. We'll walk you through the basics of the DB in
+this tutorial. You will learn how to:
 
-   * preparing object's mesh to add to the DB
-   * learn how to manually add an object to the DB
-   * visualize data in the ``ORK`` DB
+   * Prepare an object's mesh to add to the DB
+   * Manually add an object to the DB
+   * Visualize data in the ORK DB
 
 Introduction
 ************
 
-Make sure you followed the steps in the core :ref:`DB instructions <orkcore:object_recognition_core_db>`, especially to get the 3d visualizer in the DB.
+Make sure you followed the steps in the core
+:ref:`DB instructions <orkcore:object_recognition_core_db>`, especially to get
+the 3d visualizer in the DB.
 
-The example we will use is a can of Coke as it's somewhat universal :) For real life experiments, just get the iconic red can and there should not be too many appearance changes.
+In this tutorial, the object you will use is a can of Coke (12 fl. oz./355 mL),
+since it's somewhat universal. For real life experiments, just get the iconic
+red can and there should not be too many appearance changes.
 
 Prepare object's mesh
 *********************
-Object's mesh is important for object detection in ORK. Object's mesh must be in format .stl/obj.
-
-You can prepare your object's mesh by following the ORK's capture procedure (very well explained in Quick Guide). Otherwise, you can use any software that allows mesh creation to prepare your mesh. Or you can use meshes that are free on the internet.
-
-Once you have your mesh, make sure it have the right size and note it's origin point before you upload it onto the DB. As in the following snapshot of blender's screen, you can see that the coke's mesh has a different position to the origin point than the bottle's mesh.
+An object's mesh is important for object detection in ORK. The object's mesh
+must be in ``.stl`` or ``.obj`` format.
+
+ORK's :ref:`capture <orkcapture:ork_capture>`
+capability is designed to automatically create an ``.stl`` or
+``.obj`` file from many images of your object. In this way, you can create a
+mesh from an object without having to model the object in a CAD or modeling
+program. Finally, you can also use a mesh that you find on the internet. Read
+the :ref:`capture <orkcapture:ork_capture>` page for details.
+
+If you are using a mesh that you made yourself or downloaded from the internet,
+make sure that it is the the right size (the default units are meters). Also,
+note its origin point before you upload it onto the DB. As can be seen in the
+following screenshot from Blender (a mesh modeling program), the can's mesh has
+a different position relative to the origin point than the bottle's mesh.
 
 .. image:: blender_coke_bottle_pos.png
    :width: 100%
-
-In ORK, object's position returned by ORK is the position of the origin point of the object's mesh.
 
+When ORK publishes an object's position, that position is the origin point
+of the object's mesh.
 
 Creating an object in the DB
 ****************************
 
-ORK is about recognizing objects so you need to store objects in the DB first. Some pipelines like :ref:`ORK 3d capture <orkcapture:ork_capture>` have an interface to create those for you. But you can also do it with the scripts from the core.
+ORK is about recognizing objects so you need to store objects in the DB first.
+Some pipelines, like :ref:`ORK 3d capture <orkcapture:ork_capture>`, have an
+interface to create objects for you. But you can also do it with the scripts
+from the ``object_recognition_core``.
 
 .. toggle_table::
-   :arg1: Non-ROS
-   :arg2: ROS
+   :arg1: ROS
+   :arg2: Without ROS
 
-.. toggle:: Non-ROS
+.. toggle:: ROS
 
    .. code-block:: sh
-   
-      ./ork_core/apps/dbscripts/object_add.py -n coke -d "A universal can of coke"
-   
-.. toggle:: ROS
+
+      rosrun object_recognition_core object_add.py -n coke -d "A can of Coca-Cola"
+
+.. toggle:: Without ROS
 
    .. code-block:: sh
-
-      rosrun object_recognition_core object_add.py -n coke -d "A universal can of coke"
 
-You can then check this object in the DB by going to http://localhost:5984/_utils/database.html?object_recognition/_design/objects/_view/by_object_name
+      ./ork_core/apps/dbscripts/object_add.py -n coke -d "A can of Coca-Cola"
+
+You can then check this object is loaded into the DB by going to
+http://localhost:5984/_utils/database.html?object_recognition/_design/objects/_view/by_object_name
 
 .. image:: db_screenshot01.png
    :width: 100%
 
-If you click on it, you can see the info you entered about the object, especially the object id:
+If you click on it, you can see the info you entered about the object,
+including the object id:
 
 .. image:: db_screenshot02.png
    :width: 100%
 
-
 Manually adding a mesh for the object
 *************************************
 
-First, check out the object id of your object using the DB interface: each element of the DB (objects included) has its own hash as a unique identifier (in case you give the same name to different objects) and that is how you should refer to objects. To upload the mesh (use an .stl/.obj one):
+First, find you object's ID using the DB interface. Each
+element in the DB (objects included) has its own hash as a unique identifier
+(in case you give the same name to different objects), and that is how you
+should refer to objects. To upload the mesh (use an .stl/.obj one):
 
 .. toggle_table::
-   :arg1: Non-ROS
-   :arg2: ROS
+   :arg1: ROS
+   :arg2: Without ROS
 
-.. toggle:: Non-ROS
+.. toggle:: ROS
 
    .. code-block:: sh
-
-      ./ork_core/apps/dbscripts/mesh_add.py YOUR_OBJECT_ID YOUR_COKE_BLEND_PATH --commit
 
-.. toggle:: ROS
+      rosrun object_recognition_core mesh_add.py YOUR_OBJECT_ID `rospack find object_recognition_tutorials`/data/coke.obj --commit
+
+.. toggle:: Without ROS
 
    .. code-block:: sh
-
-      rosrun object_recognition_core mesh_add.py YOUR_OBJECT_ID `rospack find object_recognition_tutorials`/data/coke.obj --commit
 
+      ./ork_core/apps/dbscripts/mesh_add.py YOUR_OBJECT_ID YOUR_COKE_BLEND_PATH --commit
 
 Visualizing the object
 **********************
 
-Now, if you want to visualize the object in the db, you can just go to the visualization URL at http://localhost:5984/or_web_ui/_design/viewer/meshes.html and you should see the following:
+Now, if you want to visualize the object in the db, you can visit the
+visualization URL at http://localhost:5984/or_web_ui/_design/viewer/meshes.html.
+You should something similar to the following:
 
-.. image:: db_screenshot03.png 
+.. image:: db_screenshot03.png
    :width: 100%
 
 
@@ -100,17 +124,16 @@ You also have a method to delete an object (it will delete all other elements in
 
 
 .. toggle_table::
-   :arg1: Non-ROS
-   :arg2: ROS
-
-.. toggle:: Non-ROS
+   :arg1: ROS
+   :arg2: Without ROS
+.. toggle:: ROS
 
    .. code-block:: sh
 
-      ./ork_core/apps/dbscripts/object_delete.py OBJECT_ID
+      rosrun object_recognition_core object_delete.py OBJECT_ID
 
-.. toggle:: ROS
+.. toggle:: Without ROS
 
    .. code-block:: sh
 
-      rosrun object_recognition_core object_delete.py OBJECT_ID
+      ./ork_core/apps/dbscripts/object_delete.py OBJECT_ID